godot-genre-puzzle

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-genre-puzzle

Build puzzle games with undo, grid logic, and non-verbal tutorials.

  • Prevents soft-locks and punishes experimentation with undo/reset systems.
  • Depends on Godot 4.7+ and Command pattern for state reversal.
  • Recommends grid snapping, forgiving hitboxes, and instant visual feedback.
  • Delivers expert blueprints for logic, physics, or match-3 puzzles.

SKILL.md

.github/skills/godot-genre-puzzleView on GitHub ↗
---
name: godot-genre-puzzle
description: "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."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) 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 `SceneTree` structure 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_mode` correctly.

### Architecture & Performance
- NEVER ship dual undo authorities; strictly use Godot's built-in **UndoRedo** via [puzzle_undo_manager.gd](scripts/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 use `ResourceLoader.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](scripts/puzzle_undo_manager.gd) — sole undo authority (`UndoRedo`)
> 2. [grid_manager.gd](scripts/grid_manager.gd) — Vector2i grid as truth
> 3. [puzzle_state_validator.gd](scripts/puzzle_state_validator.gd) — soft-lock / win checks on commit

### Original Expert Patterns
- [puzzle_undo_manager.gd](scripts/puzzle_undo_manager.gd) - Godot `UndoRedo` wrapper for move do/undo (golden path).

### Modular Components
- [grid_manager.gd](scripts/grid_manager.gd) - Vector2i board state decoupled from SceneTree.
- [grid_tween_mover.gd](scripts/grid_tween_mover.gd) - Kill-before-recreate Tweens for piece moves.
- [puzzle_state_validator.gd](scripts/puzzle_state_validator.gd) - Win / soft-lock validation after commits.
- [grid_input_manager.gd](scripts/grid_input_manager.gd) - Snapped grid input.
- [match_three_logic.gd](scripts/match_three_logic.gd) - Match-3 resolve / cascade helpers.
- [puzzle_pathfinder.gd](scripts/puzzle_pathfinder.gd) - `AStarGrid2D` hints (`diagonal_mode`).
- [puzzle_saver.gd](scripts/puzzle_saver.gd) - Level / snapshot serialization.
- [puzzle_validator.gd](scripts/puzzle_validator.gd) - Broader solvability checks.
- [puzzle_history.gd](scripts/puzzle_history.gd) - Thin UndoRedo action helpers (complements undo manager).
- [tile_animator.gd](scripts/tile_animator.gd) - Tile juice without owning state.
- [shuffle_bag.gd](scripts/shuffle_bag.gd) - Fair random piece bags.
- [perspective_overlay.gd](scripts/perspective_overlay.gd) - Perspective / overlay puzzles.
- [sleepy_block.gd](scripts/sleepy_block.gd) - Timed / sleeping block mechanic sample.

> **Do NOT load** [command_undo_redo.gd](scripts/command_undo_redo.gd) — legacy hand-rolled Command stack superseded by `UndoRedo`.

---

## Core Loop
1. **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](scripts/grid_manager.gd), [grid_tween_mover.gd](scripts/grid_tween_mover.gd), [puzzle_undo_manager.gd](scripts/puzzle_undo_manager.gd), [puzzle_state_validator.gd](scripts/puzzle_state_validator.gd) |
| Match-3 | [match_three_logic.gd](scripts/match_three_logic.gd), [grid_tween_mover.gd](scripts/grid_tween_mover.gd), [puzzle_undo_manager.gd](scripts/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](scripts/puzzle_pathfinder.gd) (`AStarGrid2D.diagonal_mode`) |

### Undo authority
| Need | Action |
|------|--------|
| Player undo/redo | **Only** [puzzle_undo_manager.gd](scripts/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](references/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.

```gdscript

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

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.