board-rule

# Board Rule

The grid is the game. Paint follows cells; cells never follow paint. Legal first, apply second, settle until quiet, then listen again.

Inspired by gamedev-skills/awesome-gamedev-agent-skills puzzle (Apache-2.0). Original Grok remake. Complements seed-map (world/map procgen — this may mint SOLVABLE puzzle boards, not overworlds), juice-pass (pop/shake/hit-stop after the rule settled), save-slot (level progress / daily seed), hud-stack (score/moves layout), gold-sink (loot — out of scope), tick-mass (physics feel — out of scope; physics-puzzle-platformer is not this), pawn-mind (NPC AI — out of scope), godot-teacher (TileMap / node APIs). Gaming only. Not a Godot tutor.

Read `references/board-rails.md` before you design a rule. Fill the three templates under `templates/`.

## When to use

- Discrete grid puzzles: match-3 / match-N, sokoban pushes, sliding tiles, cascade clear, fall-and-fill
- Board-as-truth design: logic state first, visuals as a projection
- Legal-move gate before mutation; resolve loop until the board stops changing
- Undo that restores board + score + move/life counters (snapshot or invertible command)
- Seeded refill RNG so the same daily/seed yields the same cascade path
- Generated boards with a solvability proof; deadlock / no-legal-move handling
- Input lock while a cascade is still resolving
- Teaching **one** mechanic per level before stacking a second

## When NOT to use

- Roguelike real-time permadeath loops (not turn/grid puzzle rules)
- Card-game zone layouts / hand stacks (different domain)
- Physics-based puzzle platformers → tick-mass + room-flow (discrete cells here, not rigid bodies)
- Seeded world / dungeon / heightmap procgen → seed-map (hand off; solvability for puzzle boards still lives here)
- Match pop, shake, hit-stop on a settled event → juice-pass
- Persist format for level index / daily seed → save-slot
- Score/moves HUD chrome → hud-stack
- Loot tables, shops, sinks → gold-sink
- NPC FSM / pathing → pawn-mind
- Godot/Unity TileMap APIs, copied GDScript/C# → godot-teacher
- Cheat overlays, live-daily brute solvers for leaderboard hacks, aimbots, malware

## Inputs

- Puzzle family in their words (match-3, push boxes, slide-15, cascade clear, mix — name the mix last)
- Grid shape and size (rows × cols, wrap? holes? blockers?)
- Win / lose / soft-fail conditions (target score, clear N, reach exit, out of moves)
- Whether boards are authored, generated, or daily-seeded
- Undo depth they expect (none / one / stack)
- What later systems consume (juice-pass events, hud-stack counters, save-slot seed/progress)

## Procedure

1. Read `references/board-rails.md`. Refuse cheats, daily-brute leaderboard hacks, aimbots, malware, CSAM, copied GDScript/C#, and Godot/Unity API tours. Hand off: seed-map (world procgen), juice-pass (pop/shake), save-slot (persist), hud-stack (HUD), gold-sink (loot), tick-mass (physics), pawn-mind (NPC AI), godot-teacher (node APIs).
2. Fill `templates/board-card.md`. Lock the board as the single source of truth: cell kinds, occupancy, score, move/life counters, and any seeded RNG cursor. Visuals are a read-only projection. If a rule would mutate a sprite without updating a cell, stop and fix that first.
3. Name **one** primary mechanic for this level (match, push, slide, fall, fill — pick one). Extra mechanics wait. A match-3 that also teaches sokoban pushes is two levels, not one card.
4. Define the legal-move predicate *before* apply. Illegal input never mutates the board. Document the predicate on the board card (swap-if-creates-match, push-if-empty-ahead, slide-into-hole, etc.).
5. Fill `templates/resolve-loop.md`. After a legal apply, run match → clear → fall → fill (or push settle, or slide settle) in a fixed order until a full pass makes zero changes. Cap iterations. Lock player input for the whole settle. Emit juice *events* only after each settled step — do not own the pop FX here.
6. Design undo that restores **everything** the player cares about: board cells, score, move/life counters, and the refill RNG cursor (or rebuild from a recorded seed + step). Prefer snapshot stacks for small boards; invertible commands only if every step truly reverses. Partial undo that forgets the score is a bug wearing a feature badge.
7. If boards are generated: require a solvability check (name the method — BFS / IDA* / reverse-play; do not paste a solver dump). Seed the refill RNG. On deadlock / no legal moves: reshuffle under seed policy, soft-fail, or end — pick one. Never leave a silent frozen board.
8. Fill `templates/verify-puzzle.md`. Prove: illegal moves rejected; settle reaches quiet; undo restores board+score+counters; same seed same refill; generated boards pass solvability; input stays locked mid-cascade; one mechanic taught before the next is added.
9. Tiny original engine-neutral notes only if useful. No TileMap API tours. No copied tutorial pseudocode. No cheat solver for a live competitive daily.
10. Deliver the three templates. One closing line: this is a puzzle-rule worksheet; not a Godot tutor or a cheat solver.

## Output format

- Board card (truth state, one mechanic, legal predicate, win/lose)
- Resolve-loop card (ordered steps, quiet test, input lock, juice hand-off)
- Verify-puzzle checklist (legal gate, settle, undo completeness, seed, solvability, deadlock)
- One line: puzzle-rule worksheet; not a Godot tutor or a cheat solver

## Safety

- Follow `references/board-rails.md` with no exceptions.
- Gaming design only. Engine-neutral notes. Not a Godot tutor.
- No cheat overlays, daily-brute leaderboard hacks, aimbots, malware, or exploit kits.
- No CSAM in tile names, flavor text, or mock boards.
- No copied GDScript/C# or vendor tilemap dumps. Tiny original notes only.

## Stop conditions

- Three templates delivered, or refused for cheats / daily-brute solvers / godot-teacher API tours / world procgen (seed-map) / juice FX (juice-pass) / persist schema (save-slot) / HUD layout (hud-stack) / loot (gold-sink) / physics platformer (tick-mass) / NPC AI (pawn-mind) / copied vendor dumps