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`).

FileKindSize
SKILL.mdskill md6.5 KB
references/board-and-resolution.mdmarkdown6.0 KB

references/board-and-resolution.md

View on GitHub
# Puzzle board models and resolution (depth)

Detail behind `SKILL.md`. Engine-neutral pseudocode. Board coordinates are `(y, x)` with
`(0,0)` top-left and `y` growing downward (matches most tilemaps).

Contents:
1. Match-3 full resolution
2. Deadlock detection and reshuffle
3. Cascade scoring
4. Sokoban and push puzzles
5. Rule-based and logic puzzles
6. Undo strategies
7. Solvable generation and sliding-tile parity
8. Input locking and presentation

## 1. Match-3 full resolution

The resolution loop is: detect matches → score → clear → gravity → refill → repeat until stable.

```python
def apply_gravity(board):
    for x in range(W):
        # Compact non-empty cells downward within each column.
        column = [board[y][x] for y in range(H) if board[y][x] is not EMPTY]
        pad = [EMPTY] * (H - len(column))
        for y in range(H):
            board[y][x] = (pad + column)[y]      # empties on top, pieces settle to the bottom

def refill(board, rng):
    for y in range(H):
        for x in range(W):
            if board[y][x] is EMPTY:
                board[y][x] = random_piece(rng)  # seeded RNG for reproducibility
```

**Avoid spawning matches on refill** if you don't want free cascades: when filling, reject a
color that would immediately complete a line, or resolve those cascades intentionally as part
of scoring.

**Initial board:** generate so there are **no pre-existing matches** but **at least one valid
move** (see deadlocks). A common method: fill randomly, clear any starting matches, then verify
a move exists.

## 2. Deadlock detection and reshuffle (match-3)

A board with no possible matching move is a soft-lock. Detect it and react:

```python
def has_valid_move(board):
    # Try every adjacent swap; if any creates a match, a move exists.
    for y in range(H):
        for x in range(W):
            for dy, dx in ((0, 1), (1, 0)):
                if in_bounds(y+dy, x+dx):
                    swap(board, (y, x), (y+dy, x+dx))
                    ok = bool(find_matches(board))
                    swap(board, (y, x), (y+dy, x+dx))   # swap back
                    if ok: return True
    return False
# If not has_valid_move(board): reshuffle existing pieces (keep counts) until a move exists
# AND find_matches(board) is empty (a reshuffle must not hand out free matches), or end the
# level, depending on your rules. Cap the attempts and fall back to a fresh board.
```

## 3. Cascade scoring

Reward chains so deep setups feel great:

```python
def score_for(matches, chain):
    base = len(matches) * 10
    return base * chain            # linear in chain; or base * 2**(chain-1) for exponential
# Bonus for larger single matches (4 = line-clear piece, 5 = color bomb, etc.) is a common
# layer on top — special pieces created by 4+/5+ matches add strategy.
```

## 4. Sokoban / push puzzles

A different rule family: the player pushes blocks; the goal is to place blocks on targets.
Resolution is a legality check, not a cascade.

```python
def try_push(board, player, dir):
    ahead  = player + dir
    beyond = player + dir * 2
    if is_wall(board, ahead): return False
    if is_block(board, ahead):
        if is_wall(board, beyond) or is_block(board, beyond):
            return False                       # can't push two blocks or into a wall
        move_block(board, ahead, beyond)
    move_player(board, player, ahead)
    return True
# Win when every target cell holds a block. Undo is essential — sokoban is unforgiving.
# Detect dead states (a block pushed into a corner that isn't a target) to hint a restart.
```

## 5. Rule-based / logic puzzles

For logic grids (nonograms, sliding tiles, circuit/flow puzzles), the "resolution" is usually
just **validity + win check** after each move — no cascade. Keep the rule check pure and total:
given a board, return solved / unsolved / invalid. Undo and a clear "current constraints"
display matter more than animation here.

## 6. Undo strategies

| Strategy | Stores | Pros | Cons |
|----------|--------|------|------|
| Snapshot | full board + counters per move | trivial, exact | memory on big boards |
| Command | the move + inverse data | compact | must implement invert per rule |
| Redo stack | future snapshots/commands | redo support | extra bookkeeping |

Whatever you choose, undo must restore **everything** that affects play: board, score, moves
left, RNG state, and any special-piece state. Test undo by hashing full state before a move and
after undo — they must match.

## 7. Solvable generation

Generated levels must be solvable, or players hit unfair dead ends:

- **Generate-and-verify:** make a candidate, run a solver (BFS/DFS/A\* over board states for
  push/slide puzzles; move-existence for match-3); keep it only if solvable within the move/time
  budget. Use a seed so a level is reproducible.
- **Reverse generation:** start from a solved board and apply random *legal inverse* moves; the
  scrambled result is guaranteed solvable by reversing them. Great for sliding/sokoban puzzles
  (for sokoban the inverse move is a *pull*: the player steps back and drags the block).
- **Sliding-tile parity:** placing the tiles of an N×M sliding puzzle in a random order gives an
  unsolvable board exactly half the time. With the blank's goal in the bottom-right corner, count
  *inversions* (pairs of numbered tiles in the wrong order, reading row by row, ignoring the
  blank). Odd width: solvable iff inversions are even. Even width: solvable iff inversions plus
  the blank's row counted from the bottom (1 = bottom row) is odd. If a shuffle fails, swap any
  two numbered tiles to flip the parity.
- Tag each level with its seed and intended difficulty so progression curves are tunable and a
  bad level can be reproduced and fixed.

## 8. Input locking and presentation

The board model resolves instantly; animation plays the resolution out over time. **Lock input
until the board is stable** so the player can't act on a mid-cascade board. Drive visuals from
the sequence of state changes resolution produced (a list of clears/falls/spawns), not by
re-reading a half-updated board.
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: 323kUpdated 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