Color Sort Bottle Puzzle – Liquid Logic HTML5 Game

Version 1.0 | 1,200 Solvable Levels | A* Hint Solver | Undo System | Background Music | Sponsor Ad Modal | Responsive Canvas Engine | No Build Step

Color Sort Bottle Puzzle is an engaging, polished browser puzzle game built entirely with vanilla HTML5, CSS3, and modern JavaScript. Players sort vibrant colored liquids among glass bottles until every vessel contains a single uniform color or remains completely empty. Featuring 1,200 pre-computed solvable levels across three difficulty tiers, an intelligent A* pathfinding hint solver, an unlimited step-by-step undo system, dynamic fluid-pour particle physics on HTML5 Canvas, a dedicated background music engine, and a configurable pre-game sponsor ad modal, this package delivers a complete, production-ready gaming experience that runs smoothly on desktop, tablet, and mobile devices.

Game Modes

• Classic Mode – The standard puzzle challenge. Each level provides a fixed set of bottles and empty sorting vessels. Players must carefully plan each transfer to avoid dead ends.
• Relaxed Mode – A stress-free, casual variation. Adds an extra empty bottle on Medium and Hard difficulty levels, giving players extra workspace to maneuver and sort tricky color combinations.

Difficulty Tiers

• Easy (400 Levels) – 3 distinct liquid colors with 2 empty bottles (5 bottles total). Perfect for casual play, quick sessions, and beginners learning color stacking logic.
• Medium (400 Levels) – 5 distinct liquid colors with 3 empty bottles (8 bottles total in a dual-row layout). Introduces deeper color interleaving and multi-step transfer planning.
• Hard (400 Levels) – 7 distinct liquid colors with 3 empty bottles (10 bottles total in a dual-row layout). Demanding puzzles requiring forward thinking and precise move sequences.

Every single level across all 1,200 stages is mathematically verified as 100% solvable using an automated A* water-sort search algorithm. The first ten levels of each tier are specifically arranged in ascending order of optimal move count for a gentle learning curve. Unlocking is sequential: completing each level unlocks the subsequent puzzle in the tier.

Key Features

• 1,200 Solvable Levels – 400 Easy, 400 Medium, and 400 Hard levels stored in structured JSON, verified with an A* water-sort algorithm.
• Dedicated Background Music Engine – High-quality looping ambient soundtrack (scripts/music/bgm.mp3) with independent music toggle controls (.sd-music) in all settings menus, first-gesture audio unlock, and automatic tab visibility pause/resume listeners.
• Pre-Game Interstitial Sponsor Ad Modal – Sourced from the latest lobby architecture, featuring standard 300 × 250 Medium Rectangle iframe placement, configurable countdown skip button (default 2s in scripts/config/ads.js), and live theme color synchronization (--sponsor-text and --sponsor-acc).
• Comprehensive In-Game Modal System – Includes dedicated Pause / Resume modal (#popup-pause) with Quick Resume, Return to Levels, New Game, and Quit to Lobby buttons; New Game confirmation modal (#popup-newgame) with live elapsed time and move counters; and Reset Progress modal (#popup-reset).
• Sequential Level Progression – Progressive level unlocking ensures players solve stages in order, preventing accidental skips while saving all completed stages.
• In-Grid Difficulty Tier Switching – Interactive tier tabs on the Level Select screen enable instantaneous switching between Easy, Medium, and Hard grids without returning to the Mode Select menu.
• Dynamic Canvas Bottle Rendering – Realistic glass bottles, customizable cork stoppers, dynamic liquid layers with color gradients, curved menisci, and glass reflection highlights rendered via HTML5 Canvas 2D.
• Physics-Based Pouring Simulation – Dynamic bottle tilting, popping cork animations, and realistic liquid particle streams calculated with parabolic flight trajectory and splash particle effects.
• Two-Stage A* Hint Engine – When stuck, the first hint tap calculates and highlights the optimal source and target bottles. A second tap automatically executes the recommended pour.
• Full Undo System – Complete history stack allows players to step back any number of moves with animated bottle reset transitions.
• Paginated Level Select Screen – Clean 15-level grid per page (27 pages per tier) displaying completed levels, active levels, and locked stages.
• Dual-Layer Audio Engine – Web Audio API with decoded audio buffers for zero-latency sound effects (pouring, cork drop, glass tap, undo, hint, invalid move, win fanfare) plus an HTMLAudio fallback for local file execution.
• Local Progress Persistence – Player progression, unlocked levels, audio settings, and active modes automatically save to LocalStorage under color-sort-progress with a graceful in-memory fallback for private/incognito browsing.
• Zero Build Tools Required – Pure vanilla web architecture. Open main_file/index.html directly in any web browser or upload to any static hosting server with zero compilation steps.

Controls & Gameplay Mechanics

• Select Bottle – Click or tap any bottle containing liquid to select it. The bottle lifts upward with an audible glass chime.
• Pour Liquid – Click or tap a valid target bottle. The selected bottle flies to the destination, unplugs its cork, tilts, and pours matching top-layer liquid in a realistic fluid stream.
• Deselect Bottle – Click or tap the currently selected bottle again to lower it back to the table.
• Undo Move – Click or tap the Undo icon in the top header to reverse the last move and restore previous liquid layers.
• Hint – Click or tap the lightbulb Hint icon. The first click highlights the optimal source and destination bottles. Clicking again executes the move.
• Sound & Music Toggles – Independently mute or enable SFX and background music loops via header buttons and settings dropdown icons.
• Pause & Navigation – Access the Settings dropdown during gameplay and click Pause to open the Pause modal (Resume, Levels, New Game, Quit to Lobby) or click Restart to instantly reset the current puzzle.

Technology Stack

• Markup & Styling – Semantic HTML5 with single-page architecture (Loading, Lobby, Mode Select, Level Select, Play, Complete, and modal screens) and responsive CSS3 with custom properties (CSS variables), Flexbox, and CSS Grid.
• Core Logic – Modern modular JavaScript (ES6+) organized into specialized modules: sort-core.js (rules and solver), tube-render.js (canvas bottle renderer), pour-fluid.js (fluid stream simulation), levels.js (level database), and sort-game.js (state management and UI).
• Graphics & Animation – HTML5 Canvas 2D for bottle surfaces, liquid menisci, fluid particles, and win-screen confetti.
• Audio Architecture – Web Audio API with AudioContext and buffer decoding for high-frequency SFX, combined with HTML5 Audio for looping background music.
• Data Storage – Browser LocalStorage for persistent player progress with in-memory fallback protection.

Third-Party Services & Dependencies

Color Sort Bottle Puzzle is built on pure vanilla web standards. The game contains no external JavaScript frameworks or charting libraries (no Chart.js, no Three.js, no jsPDF, no html2canvas, no jQuery, no React).

The project relies on an external CDN for web font typography:

• Google Fonts (Bungee) – Loaded via external CDN (https://fonts.googleapis.com) for stylized arcade headings and game buttons. If offline, the game automatically falls back to system fonts (system-ui, sans-serif).
• Google Fonts (Montserrat, Bungee, DM Sans) – Loaded via CDN in scripts/sponsor/sponsor-placeholder.html for ad container formatting.

Please note that CDN-hosted resources are third-party dependencies and are outside of the author’s control. An internet connection is required to load these CDN-hosted resources unless buyers replace them with local copies. Gameplay, rendering, physics, levels, solver logic, audio playback, and storage are entirely local and operate with no internet connection required.

Third-Party Asset Licensing

• Google Fonts (Bungee, Montserrat, DM Sans): Licensed under the SIL Open Font License (OFL) 1.1. Commercial and personal use, bundling, and redistribution are fully permitted. No attribution is required in the end-user game interface.
• Audio Effects & Background Music: Royalty-free sound effects and background music created for interactive web games. Commercial use, white-label deployment, and redistribution with the game are permitted without mandatory attribution.
• Graphics & Illustrations: Original vector SVG graphics and illustrated PNG/WebP assets designed specifically for Color Sort Bottle Puzzle. Full white-label and customization rights are included for commercial deployment.

Advertisement & Sponsor Integration

Important: Ad network integrations (such as Google AdSense, Google AdMob, ironSource, or Unity Ads) are external third-party services not affiliated with or included in this product. Each ad network operates independently and enforces its own account registration requirements, eligibility criteria, approval procedures, policies, and potential service fees. Color Sort Bottle Puzzle provides the ad slot integration infrastructure only — buyers are solely responsible for obtaining their own publisher accounts, submitting applications, and complying with provider terms.

• Ad behavior is easily controlled from scripts/config/ads.js using simple flags (enabled: true/false, countdown: 2).
• The ready-made sponsor iframe (scripts/sponsor/sponsor-placeholder.html) is pre-configured to standard 300 × 250 (Medium Rectangle) dimensions and receives active theme colors through URL parameters.
• To integrate an ad network such as Google AdSense, paste your publisher snippet directly into scripts/sponsor/sponsor-placeholder.html.

Ad Network Approval Process FAQ

• Do ads display immediately out of the box? No. The game ships with the integration placeholder and countdown infrastructure. No third-party ad scripts are included by default; you must add your own publisher code.
• Who reviews and approves my ad account? Account approval is handled entirely and independently by your chosen ad provider (such as Google AdSense). The author and product cannot approve, influence, or expedite ad network decisions.
• Is ad network approval guaranteed? No. Approval depends solely on your website traffic, domain age, content quality, and compliance with the provider’s publisher policies. Approval is not guaranteed by the product or author.
• How long does ad network review take? Review times vary widely by provider, ranging from a few days to several weeks. Plan your release schedule accordingly.
• Who is responsible for meeting ad provider requirements? Buyers are solely responsible for meeting the ad network’s eligibility requirements, policies, and terms. The product provides only the placement slot and countdown modal infrastructure.
• Are there costs involved? While most ad networks are free to join as a publisher, some specialized ad mediation platforms or ad servers may have minimum traffic requirements or fee structures. Review your provider’s terms before integrating.

Frequently Asked Questions (FAQ)

• Can this game be embedded inside an iframe? Yes. Color Sort Bottle Puzzle is a self-contained single-page application that embeds seamlessly into iframes on web portals, gaming websites, and WordPress sites. Make sure your iframe tag includes allow="autoplay; fullscreen".
• Does the game support mobile phones and tablets? Yes. The interface is touch-optimized and fully responsive. It automatically scales bottle sizes, spacing, and multi-row grids to fit screens from small smartphones to large desktop monitors.
• Are there device or orientation-specific limitations? No. Color Sort Bottle Puzzle runs fluidly in both portrait and landscape orientations on phones, tablets, and desktops. In portrait orientation, bottles scale using CSS clamp functions for easy one-handed thumb play; in landscape, the canvas automatically arranges bottles in balanced dual rows.
• Can a specific game mode or difficulty tier be disabled? Yes. You can hide or lock any mode (Classic or Relaxed) or tier (Easy, Medium, Hard) by adjusting the button markup in index.html or setting default mode values in scripts/js/sort-game.js.
• Can the game run completely offline? Yes. All game logic, levels, physics, audio files, and artwork are stored locally. To eliminate the external CDN font request, follow the step-by-step air-gapped setup instructions in the documentation.
• How can I disable advertisements entirely? Open scripts/config/ads.js and set enabled: false. The pre-game interstitial popup will be skipped entirely.
• Which settings are safe for non-developers to edit? Non-developers can safely replace brand logos (scripts/images/logo/logo.png), play button artwork (scripts/images/play/play-warm.webp), audio files (scripts/audio/*.mp3), background music (scripts/music/bgm.mp3), and ad switches in scripts/config/ads.js without touching game code.

System Requirements & Browser Compatibility

• Tested Minimum Browser Support Floors:
  • Google Chrome 80+ (Windows, macOS, Linux, Android, ChromeOS)
  • Mozilla Firefox 74+ (Windows, macOS, Linux, Android)
  • Apple Safari 13.1+ (iOS 13.4+, iPadOS, macOS)
  • Microsoft Edge 80+ (Chromium-based)
  • Opera 67+
• Required Browser Technologies: HTML5 Canvas 2D, Web Audio API (or HTML5 Audio fallback), LocalStorage, and ES6+ JavaScript.
• Hosting Requirements: Any standard HTTP/HTTPS web server (Apache, Nginx, LiteSpeed, Cloudflare Pages, GitHub Pages, Netlify, AWS S3) or local testing via local HTTP server.

Changelog

29 September 2026 - Version 1.0 - Initial Public Release - 1,200 verified solvable levels (400 Easy, 400 Medium, 400 Hard) - Dual game modes: Classic Mode and Relaxed Mode (extra staging bottle on Medium/Hard) - Two-stage A* pathfinding hint engine (move highlight preview & auto-pour execution) - Unlimited step-by-step Undo system with animated bottle and fluid restoration - Dynamic HTML5 Canvas 2D procedural bottle renderer with 3D cylindrical lighting and curved menisci - Physics-based fluid pouring simulation with animated cork pops and splash particle effects - Dedicated background music engine with ambient loop and independent audio toggles - Dual-layer audio architecture: Web Audio API buffer playback and HTML5 Audio fallback - Pre-game interstitial sponsor ad modal with configurable countdown timer and skip button - In-game modal suite: Pause / Resume with quick navigation, New Game, and Reset Progress - Sequential level unlocking and in-grid difficulty tier switching tabs - Paginated level selection screen with 15 levels per page across 27 pages per tier - LocalStorage progress persistence with in-memory fallback for private browsing - Zero build tools required: 100% vanilla HTML5, CSS3, and ES6+ JavaScript