gamedev-skills/awesome-gamedev-agent-skills

puzzle

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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill puzzle

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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.

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

  1. 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.

  1. 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.

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

python
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 : 4 in

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.
같은 저장소의 Skills

더 많은 Skills

모든 Skills
gamedev-skills
커뮤니티

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24시간 설치 수
433
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24시간 설치 수
431
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24시간 설치 수
365
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24시간 설치 수
360
GitHub Stars
1만
업데이트
11월 12일