Match-three looks simple and contains one genuinely tricky problem: guaranteeing the board is always playable. Solving it properly is the interesting part.

1. The core loop

Swap two adjacent tiles. If it creates a line of three or more, remove them, drop everything above, fill the gaps from the top, and check again — because the new tiles may create more matches.

That "check again" is the cascade, and it's what makes the genre satisfying.

match-three.txt
Build a match-three core. Canvas or DOM, one file.

- A grid of coloured tiles.
- Swap adjacent tiles; revert the swap if it creates no match.
- Detect matches of 3+ horizontally and vertically, including L and T
  shapes where both directions match.
- Remove, drop tiles down, refill from the top, then re-check for
  cascades. Loop until stable.
- Score, with a multiplier increasing through a cascade.

The initial board must contain no matches, and must contain at least
one possible move. Show me how you guarantee both.

2. The two board guarantees

No matches at the start. Generating randomly produces boards that immediately cascade. Generate, check, and re-roll the offending tiles.

At least one valid move exists. This is the one people miss. A board with no possible move is a deadlock, and the player just sits there. After every cascade settles, scan for a possible move; if none exists, shuffle and check again.

3. Animate the state changes

The logic resolves instantly; the player needs to see it happen. Swap, match, remove, drop, refill — each needs a short animation, and input must be locked while they run.

Getting this wrong produces the bug where a player swaps during a cascade and the board state desynchronises from what's drawn.

4. Then add the special tiles

Matching four or five creates a tile with an area effect. This is where the depth is, and it's also where the edge cases live — two specials swapped together, a special triggering another special. Handle the recursion carefully.

Build a board editor before you build levels. Being able to set up an exact board state is the only practical way to test cascade and special-tile interactions.