godot-genre-puzzle

绝对禁止事项（专家级反模式）

设计与玩家体验

• 绝不惩罚玩家进行尝试；必须提供 撤销/重置 功能，让玩家能无风险地测试假设。
• 绝不要求玩家在逻辑谜题中进行像素级精准操作；必须使用 网格吸附 或宽松的大型点击区域。
• 绝不允许出现未被发现的 软锁（无解状态）；必须通知玩家或提供即时回退。
• 绝不隐藏世界规则；必须确保视觉反馈即时且明确无误（例如，通电的线路必须发光）。
• 绝不跳过 非语言教程 阶段；必须先单独介绍各项机制，再将它们组合起来。

网格逻辑与状态

• 绝不使用浮点数（Vector2）表示网格坐标；必须使用 Vector2i，以避免精度漂移。
• 绝不使用 _process() 验证网格状态或胜利条件；必须仅在棋子移动时触发检查。
• 绝不将 SceneTree 结构作为事实来源；必须在单独的脚本/字典中维护网格数据。
• 绝不在遍历 Dictionary 或 Array 时修改其大小；必须使用副本或单独的队列进行修改。
• 绝不在 _process() 中计算开销大的递归求解器；必须缓存结果，或使用线程工作器进行求解检查。
• 绝不忽略寻路中的对角线规则；必须正确配置 AStarGrid2D.diagonal_mode。

架构与性能

• 绝不同时使用两套撤销权威机制；必须通过 puzzle_undo_manager.gd 使用 Godot 内置的 UndoRedo — 不要再维护手写的 Command 堆栈。
• 绝不在同一个函数中混合“执行”和“撤销”逻辑；必须将两者分开，以便可靠地回滚。
• 绝不使用浮点数精确相等比较（==）；必须对空间约束使用 is_equal_approx()。
• 绝不使用 load() 动态重置大型房间；必须使用 ResourceLoader.load_threaded_request()。
• 绝不让 Tween 对象处于未引用状态；必须在对同一对象开始新的移动前，终止仍在运行的 tween。

---

🛠 专家组件（scripts/）

实现相应系统前，必须阅读：

1. puzzle_undo_manager.gd — 唯一的撤销权威机制（UndoRedo）
2. grid_manager.gd — 以 Vector2i 网格为事实来源
3. puzzle_state_validator.gd — 提交后进行软锁/胜利检查

原创专家模式

• puzzle_undo_manager.gd - 用于移动执行/撤销的 Godot UndoRedo 封装（推荐范式）。

模块化组件

• grid_manager.gd - 与 SceneTree 解耦的 Vector2i 棋盘状态。
• grid_tween_mover.gd - 棋子移动时先终止现有 Tween，再创建新 Tween。
• puzzle_state_validator.gd - 提交后检查胜利/软锁状态。
• grid_input_manager.gd - 网格吸附输入。
• match_three_logic.gd - 三消判定/连锁辅助工具。
• puzzle_pathfinder.gd - AStarGrid2D 提示（diagonal_mode）。
• puzzle_saver.gd - 关卡/快照序列化。
• puzzle_validator.gd - 更全面的可解性检查。
• puzzle_history.gd - 轻量级 UndoRedo 操作辅助工具（补充撤销管理器）。
• 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
三消	match_three_logic.gd, grid_tween_mover.gd, puzzle_undo_manager.gd
物理 / 空间	物体静止后进行吸附 → 然后沿用相同的撤销/验证流程；不要将刚体视为真实状态
提示 / 求解器	puzzle_pathfinder.gd (AStarGrid2D.diagonal_mode)

撤销权威来源

需求	操作
玩家撤销/重做	仅使用 puzzle_undo_manager.gd
关卡编辑器历史记录	仍使用 UndoRedo — 以相同方式封装编辑器操作

技能链

阶段	技能	用途
1. 数据	dictionaries, resources	网格真实状态、关卡 .tres
2. 输入	godot-input-handling	吸附式移动
3. 动作	godot-tweening	棋子补间动画
4. AI/提示	godot-navigation-pathfinding	A* 提示
5. 持久化	godot-save-load-systems	关卡 / 进度

常见陷阱

陷阱	解决方案
双重撤销 API	删除命令栈路径；仅使用 UndoRedo 管理器
在 _process 中检查胜利	通过状态验证器在提交移动时进行验证
浮点网格坐标	仅使用 Vector2i

必须查阅 puzzle-elite-implementations.md，以了解超出决策树和脚本目录范围的深入内容。首次接线时不要加载 — 先使用随附的 scripts/。

架构概述

1. 命令模式（撤销系统）

对益智游戏至关重要。不要因测试而惩罚玩家。

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