puzzle

1# Puzzle
2 
3A playbook for grid/board puzzle games — the board model, move input, rule resolution
4(matching, pushing, logic), scoring, undo, and level progression. This is a **compositional**
5skill: it models board state and rules and presents them through a tilemap/UI. It does not
6re-teach tilemaps; it defines the resolution loop and the correctness rules (clean state,
7deterministic resolution, undo) that keep a puzzle fair and bug-free.
8 
9## When to use
10 
11- Use when the game is a **discrete board** the player changes with moves, and the board
12  **resolves by rules**: match-3/tile-matching, sokoban/block-pusher, sliding puzzle, logic grid.
13- Use when designing match/cascade resolution, undo, level progression, or solvability.
14 
15**When *not* to use:** real-time grid action with permadeath → `roguelike`. Card zones/turns →
16`card-game`. Physics-based "puzzle platformer" → `platformer` + `physics-tuning`. For the tile
17rendering, use `godot-tilemap` / `unity-tilemap-2d`.
18 
19## Core loop
20 
21**Read the board → plan a move → make the move → the board resolves by its rules (match, push,
22fall, fill, cascade) → see progress toward the objective → repeat until solved/failed.** The
23fun is the *planning*; the engine's job is to resolve each move **deterministically** and
24present it clearly.
25 
26## Must-have systems
27 
281. **Board model** — a grid of cells holding pieces; the single source of truth (logic, not visuals).
29…