Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/genres/puzzle

puzzle

Verified

Designs 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

  1. 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 animates events.
  2. Write the rule resolver for the family (below) and loop until stable where rules cascade.
  3. 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.
  4. 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.
  5. 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.
  6. 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

FamilyRules that matterStarting numbers
Match-34 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 unsolvablecheck inversion parity (refs §7)
Merge (2048)slide, merge equal neighbours once per move, then spawnthe original spawns a 2 with 90% chance and a 4 with 10%
Logic gridsexactly one solution, reachable by deduction alonegrade 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 checkstest 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.

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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall