gamedev-skills/awesome-gamedev-agent-skills / skills/genres/puzzle
puzzle
VerifiedDesigns grid and logic puzzle games in any engine: match-3 cascades, Sokoban pushing, unique-solution grids (nonogram, Sudoku), exact undo and solver-checked levels. Use for a Candy Crush-like, Sokoban or Picross, or broken cascades, drifting undo or unsolvable levels. Not for physics puzzlers (`platformer`, `physics-tuning`) or card games (`card-game`).
Puzzle
Owns discrete board puzzles: the rules engine, resolution order, undo, solvability and level difficulty. The board model is the only truth; the view replays the list of changes each move produced.
When to use
- The player changes a discrete board with moves and the board resolves by rules: matching, pushing, sliding, merging, or pure logic deduction.
- Writing a solver or generator, ordering levels by difficulty, fixing undo or soft-locks.
When not to use: physics-driven puzzles and puzzle platformers (platformer,
physics-tuning); turn-based dungeon runs (roguelike); card zones (card-game).
Workflow
- Model the board as plain data (grid of cell values plus counters and RNG state) with a
pure
apply(state, move) -> (state, events)function. The view animatesevents. - Write the rule resolver for the family (below) and loop until stable where rules cascade.
- Undo from day one: push a snapshot (or invertible command) before every move, including score, move counters and RNG state. Add restart, which thinky puzzles need as much as undo.
- Write a solver early (BFS or A* over states for push and slide puzzles, a line or constraint solver for logic grids, move-existence for match-3). It validates every level, measures difficulty and powers hints.
- Order levels by measured difficulty, introducing one mechanic at a time: a level that teaches it alone, a level that tests it, then one that combines it with a known mechanic.
- Check it. Run these in the project's test runner and report the numbers:
- the solver solves every shipped level; print minimum moves and states explored per level and flag levels whose order disagrees with difficulty;
- logic grids: the solver finds exactly one solution without guessing;
- undo: hash the full state, make a random move, undo, and compare hashes (1,000 times);
- match-3: 10,000 random boards after generation have no ready-made match and at least one valid move;
- input during a resolving cascade is ignored or queued, never applied mid-resolution.
Rule families and numbers
| Family | Rules that matter | Starting numbers |
|---|---|---|
| Match-3 | 4 in a line makes a line-clear piece, an L or T of 5 makes an area bomb, 5 in a line makes a colour bomb (Candy Crush naming) | 8x8 or 9x9 board, 5-6 colours (fewer colours, more cascades), hint after about 5 s idle |
| Push (Sokoban) | push one box, never pull; dead squares (non-goal corners, wall edges with no goal) | difficulty from minimum pushes and states explored, not board size |
| Slide (15-puzzle) | half of random arrangements are unsolvable | check inversion parity (refs §7) |
| Merge (2048) | slide, merge equal neighbours once per move, then spawn | the original spawns a 2 with 90% chance and a 4 with 10% |
| Logic grids | exactly one solution, reachable by deduction alone | grade difficulty by the hardest deduction rule the solver needed |
| Rule-changing (Baba Is You style) | rules are board objects; re-derive the rule set after every move, before win checks | test every rule word against every object type |
No-guess generation is standard for logic puzzles: Simon Tatham's Mines, for example, ensures by default that the whole grid can be deduced from the first opening.
Pattern 1: resolve to stability (match-3)
def resolve(board, rng):
events, chain = [], 0
while True:
matches = find_matches(board) # runs of 3+, rows and columns
if not matches:
break
chain += 1
specials = specials_from(matches) # decide BEFORE clearing (shape and swap cell)
events.append(("clear", matches, chain))
clear(board, matches); place(board, specials)
events.append(("fall", apply_gravity(board)))
events.append(("spawn", refill(board, rng))) # seeded RNG, saved in undo snapshots
if not has_valid_move(board):
events.append(("shuffle", reshuffle_until_playable(board, rng)))
return events
Gotchas
- Cascades miss matches → resolution ran once. Loop until no matches (Pattern 1).
- Special piece appears in the wrong cell → specials decided after clearing. Decide from the match shape and the swapped cell first.
- Undo rerolls the refill → RNG state not in the snapshot; players learn to undo for better pieces. Snapshot board, score, counters and RNG state together.
- Visuals desync from the board → animation code reads a half-updated board. Animate the event list; lock or queue input until it finishes.
- Soft-lock with no moves → no deadlock check. Detect and reshuffle (keep piece counts, no free matches) or end the level.
- Unsolvable generated level → random scramble with no check. Generate backwards from the solved state with inverse moves (pull for Sokoban), or generate and solve, with the seed kept.
- Two valid answers in a logic grid → generator never checked uniqueness. Run the solver for a second solution and reject or add a clue.
- Difficulty jumps → levels ordered by designer guess. Order by solver effort and teach one mechanic at a time.
- Box pushed into a dead corner with no hint → no dead-square detection. Precompute dead squares and offer restart or flag them.
References
references/board-and-resolution.md: read when writing match-3 gravity, refill and deadlock code, cascade scoring, Sokoban pushing, logic-grid validity checks, undo strategies, solvable generation and sliding-tile parity, or input locking during animation.
Related: level-design (teaching order), procedural-gen (seeded generators), save-systems
(progress, daily seeds), game-feel (match pops, chain feedback), godot-tilemap or
unity-tilemap-2d (board rendering).
Version notes
Last verified: 2026-11-11.
- 2048 spawn odds:
Math.random() < 0.9 ? 2 : 4in https://github.com/gabrielecirulli/2048/blob/master/js/game_manager.js. - Simon Tatham's Mines "Ensure solubility" option, on by default: https://www.chiark.greenend.org.uk/~sgtatham/puzzles/doc/mines.html.
- Match-3 board size, colour count and hint delay are common practice, not measured.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |