Godot Genre Puzzle Agent Skill
Expert blueprint for puzzle games including undo systems (Command pattern for state reversal), grid-based logic (Sokoban-style mechanics), non-verbal tutorials (teach through level design), win condition checking, state management, and visual feedback (instant confirmation of valid moves). Use for logic puzzles, physics puzzles, or match-3 games. Trigger keywords: puzzle_game, undo_system, command_pattern, grid_logic, non_verbal_tutorial, state_management.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/thedivergentai/GD-Agentic-Skills --skill godot-genre-puzzleThe instruction itself
17 sections, as written by the authorGodot 4.7 Baseline
- Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
- Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
- NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.
Genre: Puzzle
Expert blueprint for puzzle games emphasizing clarity, experimentation, and "Aha!" moments.
NEVER Do (Expert Anti-Patterns)
Design & Player Experience
- NEVER punish experimentation; strictly provide Undo/Reset functionality to allow risk-free hypothesis testing.
- NEVER require pixel-perfect input for logic puzzles; strictly use Grid Snapping or large, forgiving hitboxes.
- NEVER allow undetected Soft-Locks (unsolvable states); strictly notify the player or provide immediate backtracking.
- NEVER hide the rules of the world; strictly ensure visual feedback is instant and unambiguous (e.g., powered wires must glow).
- NEVER skip the Non-Verbal Tutorial phase; strictly introduce mechanics in isolation before combining them.
Grid Logic & State
- NEVER use floating-point numbers (
Vector2) for grid coordinates; strictly use Vector2i to prevent precision drift. - NEVER use
_process()for grid-state or win-condition validation; strictly trigger checks only when a piece moves. - NEVER rely on the
SceneTreestructure as the source of truth; strictly maintain grid data in a separate script/dictionary. - NEVER modify a Dictionary or Array size while iterating over it; strictly use a copy or a separate queue for modifications.
- NEVER calculate heavy recursive solvers in
_process(); strictly cache results or use threaded workers for solve-checks. - NEVER ignore diagonal rules in pathfinding; strictly configure
AStarGrid2D.diagonal_modecorrectly.
Architecture & Performance
- NEVER ship dual undo authorities; strictly use Godot's built-in UndoRedo via puzzle_undo_manager.gd — do not also maintain a hand-rolled Command stack.
- NEVER intermingle "do" and "undo" logic in the same function; strictly maintain separation for predictable rollbacks.
- NEVER use exact floating-point equality (==); strictly use
is_equal_approx()for spatial constraints. - NEVER use
load()for resetting large rooms dynamically; strictly useResourceLoader.load_threaded_request(). - NEVER leave Tween objects unreferenced; strictly kill active tweens before starting new movement on the same object.
🛠 Expert Components (scripts/)
> MANDATORY reads before implementing the matching system:
> 1. puzzle_undo_manager.gd — sole undo authority (UndoRedo)
> 2. grid_manager.gd — Vector2i grid as truth
> 3. puzzle_state_validator.gd — soft-lock / win checks on commit
Original Expert Patterns
- puzzle_undo_manager.gd - Godot
UndoRedowrapper for move do/undo (golden path).
Modular Components
- grid_manager.gd - Vector2i board state decoupled from SceneTree.
- grid_tween_mover.gd - Kill-before-recreate Tweens for piece moves.
- puzzle_state_validator.gd - Win / soft-lock validation after commits.
- grid_input_manager.gd - Snapped grid input.
- match_three_logic.gd - Match-3 resolve / cascade helpers.
- puzzle_pathfinder.gd -
AStarGrid2Dhints (diagonal_mode). - puzzle_saver.gd - Level / snapshot serialization.
- puzzle_validator.gd - Broader solvability checks.
- puzzle_history.gd - Thin UndoRedo action helpers (complements undo manager).
- tile_animator.gd - Tile juice without owning state.
- shuffle_bag.gd - Fair random piece bags.
- perspective_overlay.gd - Perspective / overlay puzzles.
- sleepy_block.gd - Timed / sleeping block mechanic sample.
> Do NOT load command_undo_redo.gd — legacy hand-rolled Command stack superseded by UndoRedo.
Core Loop
- Observe → 2. Hypothesize → 3. Commit move → 4. Validate → 5. Undo/Reset if needed
Decision Trees
Genre → scripts
| Puzzle type | MANDATORY reads |
|-------------|-----------------|
| Sokoban / push grid | grid_manager.gd, grid_tween_mover.gd, puzzle_undo_manager.gd, puzzle_state_validator.gd |
| Match-3 | match_three_logic.gd, grid_tween_mover.gd, puzzle_undo_manager.gd |
| Physics / spatial | Snap on settle → then same undo/validator path; do not treat rigid bodies as truth |
| Hints / solvers | puzzle_pathfinder.gd (AStarGrid2D.diagonal_mode) |
Undo authority
| Need | Action |
|------|--------|
| Player undo/redo | Only puzzle_undo_manager.gd |
| Level editor history | Still UndoRedo — wrap editor actions the same way |
Skill Chain
| Phase | Skills | Purpose |
|-------|--------|---------|
| 1. Data | dictionaries, resources | Grid truth, level .tres |
| 2. Input | godot-input-handling | Snapped moves |
| 3. Motion | godot-tweening | Piece Tweens |
| 4. AI/hints | godot-navigation-pathfinding | A* hints |
| 5. Persist | godot-save-load-systems | Level / progress |
Common Pitfalls
| Pitfall | Solution |
|---------|----------|
| Dual undo APIs | Delete Command-stack path; use UndoRedo manager only |
| Win check in _process | Validate on move commit via state validator |
| Float grid coords | Vector2i only |
> MANDATORY for depth beyond decision trees and script catalog: puzzle-elite-implementations.md. Do NOT Load on first-pass wiring — use bundled scripts/ first.
Architecture Overview
1. Command Pattern (Undo System)
Essential for puzzle games. Never punish testing.
## Godot-Specific Tips
* **Tweens**: Use `create_tween()` for all grid movements. It feels much better than instant snapping.
* **Custom Resources**: Store level data (layout, starting positions) in `.tres` files for easy editing in the Inspector.
* **Signals**: Use signals like `state_changed` to update UI/Visuals decoupled from the logic.
---
## Reference
> Progressive disclosure: open Official Documentation links only when researching a specific API;
> load Related Skills when routing work to a peer domain — do not preload the whole lattice.
### Official Documentation
- [UndoRedo](https://docs.godotengine.org/en/stable/classes/class_undoredo.html) — Built-in action history for do/undo/redo so puzzle experimentation does not require a hand-rolled command stack.
- [AStarGrid2D](https://docs.godotengine.org/en/stable/classes/class_astargrid2d.html) — Uniform-grid pathfinding (`diagonal_mode`, `jumping_enabled`) for hints and reachability on Sokoban-style boards.
- [Tween](https://docs.godotengine.org/en/stable/classes/class_tween.html) — Interruptible `create_tween()` motion for cell-to-cell feedback while logical `Vector2i` state updates immediately.
- [Using TileMaps](https://docs.godotengine.org/en/stable/tutorials/2d/using_tilemaps.html) — TileMapLayer workflows for painting walls/targets while keeping puzzle truth in a separate grid dictionary.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — Persist level progress, stars, and mid-puzzle snapshots without relying on scene reload as save.
- [Using InputEvent](https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html) — Device-agnostic click/drag/action routing for forgiving grid selection and move commits.
- [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Store layouts and starting piece sets as `.tres`/`Resource` data editable in the Inspector.
- [Physics introduction](https://docs.godotengine.org/en/stable/tutorials/physics/physics_introduction.html) — RigidBody sleep, layers, and integration hooks for physics-driven puzzle pieces.
- [Idle and Physics Processing](https://docs.godotengine.org/en/stable/tutorials/scripting/idle_and_physics_processing.html) — Why win/soft-lock checks belong on move commits, not every `_process` frame.
- [Data preferences](https://docs.godotengine.org/en/stable/tutorials/best_practices/data_preferences.html) — Prefer integer grid keys (`Vector2i`) and explicit dictionaries over SceneTree-as-truth.
- [Runtime file loading and saving](https://docs.godotengine.org/en/stable/tutorials/io/runtime_file_loading_and_saving.html) — `FileAccess`/`user://` patterns for custom level JSON and editor export packs.
- [JSON](https://docs.godotengine.org/en/stable/classes/class_json.html) — Serialize compact puzzle boards when splitting `Vector2` fields for portable level files.
### Related Skills
#### Prerequisites
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — Buffered InputEvent/action maps so grid clicks and directional moves stay device-agnostic and forgiving.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — Safe `state_changed` / `level_complete` wiring so UI and VFX stay decoupled from grid truth.
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Autoload/project layout baselines before stacking undo managers, savers, and level packs.
#### Complements
- [godot-tweening](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-tweening/SKILL.md) — Deeper Tween composition when cell moves, match clears, and resets need interruptible juice without logic races.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Progress ownership, versioning, and threaded loads beyond per-level JSON snapshots.
- [godot-tilemap-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-tilemap-mastery/SKILL.md) — TileMapLayer painting, custom data, and terrain patterns that visualize walls while scripts own solvability.
- [godot-navigation-pathfinding](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-navigation-pathfinding/SKILL.md) — Broader Navigation/A* stacks when puzzle hints outgrow a single `AStarGrid2D` region.
- [godot-2d-physics](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-2d-physics/SKILL.md) — RigidBody sleep, layers, and queries for physics puzzles that still need deterministic settle/win checks.
- [godot-state-machine-advanced](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-state-machine-advanced/SKILL.md) — Phase FSMs (observe → move → resolve → win) when puzzles mix animation locks with input gates.
- [godot-camera-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-camera-systems/SKILL.md) — Camera2D/3D framing and unproject helpers for perspective/world-space puzzle overlays.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Minimal undo/reset HUD layouts that stay non-intrusive during non-verbal tutorials.
#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — Sample solvability, move-count distributions, and soft-lock rates so level packs stay fair as mechanics combine.
- [godot-procedural-generation](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-procedural-generation/SKILL.md) — Generate candidate boards that still pass this skill's validators, undo constraints, and win-condition contracts.
- [godot-genre-roguelike](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-roguelike/SKILL.md) — Consumes grid/undo patterns when dungeon runs embed discrete puzzle rooms or locked-door logic.
#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry for discovering this genre skill beside sibling domains.
Other skills for the same job
different authors, same section of the catalogue
A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
Extracts and analyzes competitors' ads from ad libraries (Facebook, LinkedIn, etc.) to understand what messaging, problems, and creative approaches are working. Helps inspire and improve your own ad campaigns.
Identifies high-quality leads for your product or service by analyzing your business, searching for target companies, and providing actionable contact strategies. Perfect for sales, business development, and marketing professionals.
Analyzes your recent Claude Code chat history to identify coding patterns, development gaps, and areas for improvement, curates relevant learning resources from HackerNews, and automatically sends a personalized growth report to your Slack DMs.
Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store
NGS analysis toolkit. BAM to bigWig conversion, QC (correlation, PCA, fingerprints), heatmaps/profiles (TSS, peaks), for ChIP-seq, RNA-seq, ATAC-seq visualization.
Materials science toolkit. Crystal structures (CIF, POSCAR), phase diagrams, band structure, DOS, Materials Project integration, format conversion, for computational materials science.
Transforms vague UI ideas into polished, Stitch-optimized prompts. Enhances specificity, adds UI/UX keywords, injects design system context, and structures output for better generation results.
How to use it
Take thedivergentai/godot-genre-puzzle from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.