Color Sort Water Puzzle — Free HTML CSS JS Snippet

Water sort puzzles became one of the most-downloaded mobile game genres of the last few years precisely because the rules are so simple to state and so satisfying to reason through: pour a colour from one tube into another, and you may only pour onto empty space or a matching colour. This snippet implements the real mechanic in vanilla JavaScript — genuine stack data structures, real pour validation, and a shuffle algorithm that mathematically guarantees every generated puzzle is solvable.

Modelling tubes as LIFO stacks

Each tube is represented as a plain JavaScript array where index 0 is the bottom of the tube and the last index is the top — a textbook LIFO (last-in, first-out) stack. topColor(tube) reads tube[tube.length - 1], and pouring uses pop() on the source and push() on the destination, which is exactly how a real stack data structure is manipulated. Rendering reverses this visually with CSS flex-direction: column-reverse on .tube, so segment index 0 (the bottom of the logical stack) renders at the visual bottom of the tube even though it is the first child in the DOM.

Generating a puzzle that is provably solvable

It's tempting to "scramble" a water sort board the same way a 15-puzzle is scrambled — start from the solved state and repeatedly apply random *legal* moves in reverse. For this game that approach quietly fails: a legal pour can only add liquid to an empty tube or onto a matching top colour, so starting from monochrome tubes and only ever applying legal pours can never produce a tube containing two different colours — every tube stays monochrome-or-empty no matter how many legal pours you replay, which also means a naive "is this scramble trivial" check would answer yes every single time. Genuinely mixed tubes have to come from somewhere else: dealRandomState() builds a flat list of every colour unit (colorCount * TUBE_CAPACITY of them), shuffles it with a real Fisher–Yates shuffle, then deals each unit into a random tube that still has spare capacity — the same way you'd deal a shuffled deck of cards into hands. That produces authentic mixed-colour tubes, but a random deal isn't automatically solvable. So every deal is checked with isSolvable(), a breadth-first search over legal-pour states (canonicalised by sorting tubes before hashing, since which physical tube holds what doesn't affect solvability) capped at a few thousand explored states — a board is only accepted once the search actually finds a path to every tube being monochrome-or-empty; an unproven deal is discarded and scramblePuzzle() simply deals again.

Real pour validation, including multi-segment pours

canPour(from, to) enforces the actual water sort ruleset: pouring is illegal from an empty tube, into a tube whose top colour differs from the source's top colour, or into a tube without enough remaining capacity. Critically, a pour is not limited to one unit — topRunLength() walks down from the top of the source tube counting how many consecutive segments share the same top colour, and pour() transfers Math.min(run, availableSpace) segments in one action, exactly matching how the real genre works: pouring a tube with three stacked red segments onto an empty tube moves all three at once, not one at a time.

Selection, undo, and win detection

Clicking a tube with liquid selects it (visually lifted with a translateY and indigo border via .tube.selected); clicking a second tube attempts canPour and, if valid, calls pour() and records { from, to, count } onto a moveHistory stack. The Undo button pops that history and pushes the exact segment count back from destination to source, cleanly reversing any pour including multi-segment ones. checkWin() calls isTubeSolved() on every tube — a tube counts as solved if it is empty, or if it is completely full and every segment shares the same colour — and the puzzle is won only when every single tube satisfies that condition simultaneously.

Why this teaches real constraint-based game logic

Water sort is a clean example of a puzzle whose entire challenge lives in state and move validation rather than visuals. Building it correctly forces you to reason about stack semantics, legal-move generation, and reversible shuffles — the same conceptual toolkit used in the Mini Sudoku Puzzle's constraint checking, just applied to a different rule set.