# Puzzle

Build a puzzle game: grid/board state, move input, rule-based resolution (match-3...

- Repository: https://github.com/gamedev-skills/awesome-gamedev-agent-skills (6445 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill puzzle -g -a claude-code -y`
Codex: `npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill puzzle -g -a codex -y`
Cursor: `npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill puzzle -g -a cursor -y`
Gemini CLI: `npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill puzzle -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add gamedev-skills/awesome-gamedev-agent-skills`

## Description

Build a puzzle game: grid/board state, move input, rule-based resolution (match-3 cascades, sokoban pushes, tile logic), scoring, and undo. Use for a match-3, sokoban, or grid-logic puzzle.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Puzzle

A playbook for grid/board puzzle games, the board model, move input, rule resolution
(matching, pushing, logic), scoring, undo, and level progression. This is a **compositional**
skill: it models board state and rules and presents them through a tilemap/UI. It does not
re-teach tilemaps; it defines the resolution loop and the correctness rules (clean state,
deterministic resolution, undo) that keep a puzzle fair and bug-free.

## When to use

- Use when the game is a **discrete board** the player changes with moves, and the board
  **resolves by rules**: match-3/tile-matching, sokoban/block-pusher, sliding puzzle, logic grid.
- Use when designing match/cascade resolution, undo, level progression, or solvability.

**When *not* to use:** real-time grid action with permadeath → `roguelike`. Card zones/turns →
`card-game`. Physics-based "puzzle platformer" → `platformer` + `physics-tuning`. For the tile
rendering, use `godot-tilemap` / `unity-tilemap-2d`.

## Core loop

**Read the board → plan a move → make the move → the board resolves by its rules (match, push,
fall, fill, cascade) → see progress toward the objective → repeat until solved/failed.** The
fun is the *planning*; the engine's job is to resolve each move **deterministically** and
present it clearly.

## Must-have systems

The rest: https://github.com/gamedev-skills/awesome-gamedev-agent-skills/blob/HEAD/skills/genres/puzzle/SKILL.md