godot-genre-puzzle

絶対に避けること（熟練者が陥りがちなアンチパターン）

設計とプレイヤー体験

• 実験を絶対に罰しないでください。リスクなしで仮説を試せるよう、Undo/Reset 機能を必ず用意してください。
• ロジックパズルでピクセル単位の正確な入力を絶対に要求しないでください。必ず グリッドスナップ を使用するか、許容範囲の広い大きなヒットボックスを用意してください。
• 検出できない ソフトロック（解決不能な状態）を絶対に許さないでください。必ずプレイヤーに通知するか、すぐに元に戻せるようにしてください。
• 世界のルールを絶対に隠さないでください。視覚的なフィードバックが即座に、明確に伝わるよう徹底してください（例：通電中のワイヤーは光らせる必要があります）。
• 非言語チュートリアルの段階を絶対に省略しないでください。仕組みを組み合わせる前に、それぞれを個別に導入してください。

グリッドロジックと状態

• グリッド座標に浮動小数点数（Vector2）を絶対に使わないでください。精度のずれを防ぐため、必ず Vector2i を使用してください。
• グリッド状態や勝利条件の検証に _process() を絶対に使わないでください。必ずピースが動いたときだけチェックを実行してください。
• 真実の情報源として SceneTree の構造に絶対に依存しないでください。グリッドデータは必ず別のスクリプト／辞書で管理してください。
• 反復処理中に Dictionary や Array のサイズを絶対に変更しないでください。変更には必ずコピーまたは別のキューを使用してください。
• 負荷の高い再帰的なソルバーを _process() で絶対に計算しないでください。解答チェックの結果をキャッシュするか、必ずスレッドワーカーを使用してください。
• 経路探索で斜め移動のルールを絶対に無視しないでください。AStarGrid2D.diagonal_mode を必ず適切に設定してください。

アーキテクチャとパフォーマンス

• Undo の権限を二重に持たせて絶対にリリースしないでください。puzzle_undo_manager.gd を通じて Godot 組み込みの UndoRedo を必ず使用し、独自実装の Command スタックも併用しないでください。
• 「実行」と「Undo」のロジックを同じ関数に絶対に混在させないでください。予測可能なロールバックのため、必ず分離してください。
• 浮動小数点数の完全一致（==）を絶対に使わないでください。空間的な制約には必ず is_equal_approx() を使用してください。
• 大きな部屋を動的にリセットする際に load() を絶対に使わないでください。必ず ResourceLoader.load_threaded_request() を使用してください。
• Tween オブジェクトを参照されない状態で絶対に残さないでください。同じオブジェクトで新たな移動を開始する前に、必ず実行中の Tween を停止してください。

---

🛠 熟練者向けコンポーネント（scripts/）

必須：対応するシステムを実装する前に、以下を読んでください。

1. puzzle_undo_manager.gd — 唯一の Undo 管理機構（UndoRedo）
2. grid_manager.gd — Vector2i グリッドを真実の情報源として使用
3. puzzle_state_validator.gd — コミット時のソフトロック／勝利チェック

オリジナルの熟練者向けパターン

• puzzle_undo_manager.gd - 移動の実行／Undo を扱う Godot UndoRedo ラッパー（推奨パターン）。

モジュール式コンポーネント

• grid_manager.gd - SceneTree から切り離された Vector2i の盤面状態。
• grid_tween_mover.gd - ピースの移動時に Tween を停止してから再作成。
• puzzle_state_validator.gd - コミット後の勝利／ソフトロック検証。
• grid_input_manager.gd - グリッドにスナップする入力。
• match_three_logic.gd - マッチ3の解決／連鎖処理ヘルパー。
• puzzle_pathfinder.gd - AStarGrid2D のヒント（diagonal_mode）。
• puzzle_saver.gd - レベル／スナップショットのシリアライズ。
• puzzle_validator.gd - より広範な解決可能性のチェック。
• puzzle_history.gd - UndoRedo アクションの簡易ヘルパー（Undo 管理機能を補完）。
• tile_animator.gd - 状態を管理せずにタイルの演出を追加。
• shuffle_bag.gd - 公平なランダムピースの袋。
• perspective_overlay.gd - パースペクティブ／オーバーレイパズル。
• sleepy_block.gd - 時限式／スリープ状態のブロックの仕組みを示すサンプル。

command_undo_redo.gd は読み込まないでください。UndoRedo に置き換えられた、独自実装のレガシー Command スタックです。

---

コアループ

1. 観察する → 2. 仮説を立てる → 3. 手を打つ → 4. 検証する → 5. 必要に応じて 元に戻す／リセットする

判断ツリー

ジャンル → スクリプト

パズルの種類	必須の読み込み対象
倉庫番／押し動かすグリッド	grid_manager.gd, grid_tween_mover.gd, puzzle_undo_manager.gd, puzzle_state_validator.gd
マッチ3	match_three_logic.gd, grid_tween_mover.gd, puzzle_undo_manager.gd
物理／空間	停止時にスナップしてから、同じ Undo／バリデーターの経路を使用します。リジッドボディを真実として扱わないでください
ヒント／ソルバー	puzzle_pathfinder.gd（AStarGrid2D.diagonal_mode）

Undo の管理元

要件	対応
プレイヤーの Undo／Redo	puzzle_undo_manager.gd のみ
レベルエディターの履歴	引き続き UndoRedo を使用します。同じ方法でエディターの操作をラップしてください

スキルチェーン

フェーズ	スキル	目的
1. データ	dictionaries, resources	グリッドの真の状態、レベル .tres
2. 入力	godot-input-handling	スナップされた移動
3. モーション	godot-tweening	ピースの Tween
4. AI／ヒント	godot-navigation-pathfinding	A* ヒント
5. 永続化	godot-save-load-systems	レベル／進行状況

よくある落とし穴

落とし穴	解決策
Undo API が二重にある	Command スタックの経路を削除し、UndoRedo マネージャーのみを使用します
_process 内で勝利判定する	ステートバリデーターを使い、手の確定時に検証します
グリッド座標が浮動小数点数	Vector2i のみを使用します

判断ツリーとスクリプトカタログの範囲を超えて詳しく知る場合は、必ず puzzle-elite-implementations.md を参照してください。初回の配線時には読み込まないでください。まず同梱の scripts/ を使用してください。

アーキテクチャの概要

1. コマンドパターン（Undo システム）

パズルゲームに不可欠です。テストをためらわせる設計にしないでください。

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