AI 时代快速了解自己感兴趣的计算机辅助的“制作工艺”管线

你是我的 Godot 游戏开发导师、Claude Code 编程代理、项目文档维护者。

我想用 Godot 4.x 制作一个类似《火焰纹章：封印之剑》风格的 2D 回合制 SRPG 单关 vertical slice。
这个项目的核心目的不是做完整商业游戏，而是通过一个可玩的单关原型，帮我熟悉完整游戏开发管线，以及常见游戏开发概念。

请你同时完成三件事：

1. 写代码，实现一个可玩的 Godot SRPG 单关。
2. 像导师一样解释每个阶段涉及的游戏开发概念。
3. 每个阶段结束后，写一份 Markdown 学习文档，总结这一阶段学到了什么、实现了什么、如何测试、常见坑是什么。

---

# 一、项目总体目标

使用 Godot 4.x 制作一个 2D 网格战棋 SRPG 单关。

最小可玩目标：

* 只做一关。
* 地图大约 16x12 或 20x15。
* 我方 3 个单位。
* 敌方 4 个单位。
* 支持玩家回合和敌方回合。
* 支持移动、攻击、等待。
* 支持单位死亡。
* 支持胜利和失败。
* 胜利条件：击败 Boss 或全灭敌人。
* 失败条件：主角死亡。
* 最后可以导出 Web 或桌面版本。

不要追求美术精致，优先使用占位素材、纯色方块、简单像素图或程序生成的 placeholder。

不要使用任何受版权保护的火焰纹章原版素材。

---

# 二、学习目标

这个项目要刻意覆盖这些游戏开发常见概念，并在对应阶段解释它们：

## 地图与关卡

* TileMap
* TileSet
* TileMapLayer
* 地形数据
* 地图坐标 grid position
* 世界坐标 world position
* local_to_map
* map_to_local

## 碰撞与检测

* 物理碰撞
* 逻辑碰撞
* CharacterBody2D
* StaticBody2D
* Area2D
* CollisionShape2D
* collision layer
* collision mask
* 战棋游戏里的不可通行格子
* 单位阻挡
* 攻击范围检测

## 2D 图像与动画

* Sprite 精灵图
* Sprite Sheet 精灵表
* AnimatedSprite2D
* SpriteFrames
* idle / walk / attack / hurt / death 动画
* 像素图导入设置
* Nearest filter
* AnimationPlayer

## 骨骼动画

* Skeleton2D
* Bone2D
* 骨骼动画和精灵表动画的区别
* Boss cut-in 演出
* 立绘呼吸动画或挥刀动画

## 玩法系统

* 状态机 State Machine
* 回合制 Turn Manager
* BFS 移动范围
* AStarGrid2D 路径寻路
* 战斗计算
* 敌人 AI
* 胜负条件
* 游戏流程闭环

## UI / Audio / Export

* CanvasLayer
* 行动菜单
* 角色面板
* 战斗预览
* 血条
* 音效反馈
* 背景音乐
* 导出发布
* README
* 项目文档

---

# 三、项目结构

请创建并维护类似下面的结构：

res://
playgrounds/
tilemap/
TileMapPlayground.tscn
TileMapPlayground.gd
collision/
CollisionPlayground.tscn
CollisionPlayground.gd
spritesheet/
SpriteSheetPlayground.tscn
SpriteSheetPlayground.gd
skeleton/
SkeletonPlayground.tscn
SkeletonPlayground.gd

game/
scenes/
Main.tscn
Chapter01.tscn
Unit.tscn
Cursor.tscn
UI/
CommandMenu.tscn
UnitInfoPanel.tscn
BattlePreview.tscn
ResultPanel.tscn

scripts/
  core/
    GameState.gd
    TurnManager.gd
    Grid.gd
  map/
    BattleMap.gd
    Terrain.gd
    MapData.gd
  unit/
    Unit.gd
    UnitStats.gd
  combat/
    CombatResolver.gd
    DamageFormula.gd
  ai/
    EnemyAI.gd
  ui/
    CommandMenu.gd
    RangeOverlay.gd
    UnitInfoPanel.gd
    BattlePreview.gd

data/
  chapter01.json
  units.json
  weapons.json
  terrain.json

assets/
tiles/
units/
portraits/
boss_parts/
ui/
sfx/
music/

docs/
00_project_overview.md
01_tilemap_playground.md
02_collision_playground.md
03_spritesheet_playground.md
04_skeleton_playground.md
05_chapter01_map_and_cursor.md
06_unit_system.md
07_movement_and_pathfinding.md
08_action_menu_and_combat.md
09_turn_system.md
10_enemy_ai.md
11_win_lose_audio_cutscene.md
12_export_and_wrapup.md
glossary.md
devlog.md
troubleshooting.md

---

# 四、重要开发方式

请严格分阶段推进。

不要一次性生成完整项目。

每个阶段开始前，先输出：

1. 当前阶段名称。
2. 本阶段目标。
3. 本阶段涉及的游戏开发概念。
4. 本阶段将创建或修改的文件。
5. 本阶段完成后应该能看到什么效果。

然后再实现代码。

每个阶段结束后必须停下来，不要自动进入下一阶段。
等待我在 Godot 中运行验证后，再继续下一阶段。

---

# 五、每阶段文档要求

每个阶段结束后，必须在 docs/ 下写一篇 Markdown 文档。

每篇阶段文档必须包含这些部分：

```markdown
# 阶段标题

## 1. 本阶段目标

说明这一阶段要解决什么问题。

## 2. 最终效果

说明运行后应该看到什么。

## 3. 涉及的游戏开发概念

用初学者能理解的方式解释概念。

## 4. 本阶段创建或修改的文件

列出文件路径，并说明每个文件负责什么。

## 5. 核心实现思路

解释实现方案，不要只贴代码。

## 6. 关键代码说明

摘录关键函数或关键逻辑，并解释它们。

## 7. 如何运行和测试

给出 Godot 编辑器里的测试步骤。

## 8. 常见问题和坑

列出本阶段可能遇到的问题，比如坐标错位、碰撞层没设置、像素图发糊、动画不播放等。

## 9. 这一阶段对应真实游戏开发管线的哪一环

例如：关卡编辑、角色导入、动画制作、玩法原型、UI 接入、AI 调试、打包发布等。

## 10. 下一阶段要做什么

说明下一阶段目标。

---

# 六、额外文档要求

除了每阶段文档，还需要维护以下长期文档：

## docs/00_project_overview.md

记录：

* 项目目标
* 最小可玩范围
* 当前完成进度
* 如何运行项目
* 项目结构说明
* 当前已实现功能
* 后续计划

## docs/glossary.md

维护游戏开发术语表。
每次遇到新概念，都追加到这里。

格式：

`markdown
## TileMap

一句话解释：

在本项目中的作用：

Godot 中相关节点或 API：
`

需要记录的术语至少包括：

* TileMap
* TileSet
* TileMapLayer
* Sprite
* Sprite Sheet
* AnimatedSprite2D
* AnimationPlayer
* Skeleton2D
* Bone2D
* Collision
* CharacterBody2D
* StaticBody2D
* Area2D
* CollisionShape2D
* State Machine
* Turn Manager
* BFS
* AStarGrid2D
* UI
* CanvasLayer
* AudioStreamPlayer
* Export

## docs/devlog.md

每阶段结束后追加开发日志。

格式：

`

# Devlog

## 阶段 N：标题

日期：
完成内容：
遇到的问题：
解决方式：
下一步：

## docs/troubleshooting.md

记录开发中遇到的问题和解决方法。

格式：

`
## 问题标题

现象：

原因：

解决方法：

相关文件：
`

---

# 七、阶段计划

请按下面阶段实现。

---

## 阶段 0：项目检查与初始化

目标：

* 检查当前目录是否已有 Godot 项目。
* 如果没有，创建推荐项目结构。
* 创建 docs 目录。
* 创建 00_project_overview.md、glossary.md、devlog.md、troubleshooting.md。
* 确认 Godot 版本。
* 确认项目入口场景。

要解释：

* Godot 项目结构。
* res:// 的含义。
* 场景和脚本的关系。
* 为什么要先建文档。

阶段结束文档：

* docs/00_project_overview.md
* docs/devlog.md
* docs/glossary.md

完成后停下来。

---

## 阶段 1：TileMap Playground

目标：

* 创建 TileMapPlayground。
* 使用 TileMapLayer 创建一张小地图。
* 支持鼠标悬停格子。
* 显示当前格子坐标和地形类型。
* 尝试使用 tile custom data 或代码映射地形数据。

要解释：

* TileMap
* TileSet
* TileMapLayer
* grid 坐标
* world 坐标
* local_to_map
* map_to_local
* 地形数据

阶段结束文档：

* docs/01_tilemap_playground.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 2：Collision Playground

目标：

* 创建一个 CharacterBody2D 小人。
* 创建 StaticBody2D 墙壁。
* 小人不能穿墙。
* 创建 Area2D 陷阱区域。
* 进入陷阱后显示提示或打印日志。
* 演示 collision layer 和 collision mask 的基本作用。

要解释：

* 物理碰撞
* 逻辑碰撞
* CharacterBody2D
* StaticBody2D
* Area2D
* CollisionShape2D
* collision layer
* collision mask
* 为什么 SRPG 主玩法大多用逻辑碰撞

阶段结束文档：

* docs/02_collision_playground.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 3：Sprite Sheet Playground

目标：

* 创建 SpriteSheetPlayground。
* 使用 AnimatedSprite2D。
* 创建或导入临时 sprite sheet。
* 支持 idle、walk、attack、hurt、death 动画。
* 使用按键切换动画。
* 如果没有素材，就用程序生成的占位帧或简单色块帧。

要解释：

* Sprite
* Sprite Sheet
* AnimatedSprite2D
* SpriteFrames
* FPS
* 循环动画
* 非循环动画
* 像素图导入设置
* Nearest filter

阶段结束文档：

* docs/03_spritesheet_playground.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 4：Skeleton Playground

目标：

* 创建 SkeletonPlayground。
* 使用 Skeleton2D、Bone2D、AnimationPlayer。
* 用简单图形或拆分图片模拟 Boss 立绘。
* 做一个待机呼吸动画或挥刀动画。
* 不要求美术好看，只要求理解骨骼动画流程。

要解释：

* Skeleton2D
* Bone2D
* 骨骼动画
* 精灵表动画和骨骼动画的区别
* AnimationPlayer 如何驱动骨骼

阶段结束文档：

* docs/04_skeleton_playground.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 5：Chapter01 地图与光标

目标：

* 创建主战斗场景 Chapter01。
* 使用 TileMapLayer 制作 16x12 或 20x15 战棋地图。
* 创建 Cursor。
* 支持键盘移动光标。
* 光标移动时显示当前格子的地形信息。
* 引入 terrain.json。

要解释：

* 主玩法场景结构。
* 地图层、单位层、UI 层。
* Cursor 的作用。
* grid_pos 和 world_pos。
* 为什么战棋游戏必须统一坐标系统。

阶段结束文档：

* docs/05_chapter01_map_and_cursor.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 6：单位系统

目标：

* 创建 Unit.tscn。
* 创建 Unit.gd 和 UnitStats.gd。
* 使用 units.json 配置单位。
* 加载 3 个我方单位和 4 个敌方单位。
* 单位显示在正确格子。
* 选中单位时显示 UnitInfoPanel。
* 单位要保存 grid_pos，不要只依赖 Node2D.position。

要解释：

* 场景实例化。
* 数据驱动。
* 单位数据和单位表现分离。
* Sprite/AnimatedSprite2D 在角色中的作用。
* 为什么 grid_pos 是玩法状态，position 是画面表现。

阶段结束文档：

* docs/06_unit_system.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 7：移动范围与寻路

目标：

* 选中我方单位后，用 BFS 显示移动范围。
* 根据地形 move_cost 计算移动消耗。
* 墙、水、敌方单位阻挡移动。
* 友方单位不可停留。
* 点击可移动格子后，单位沿路径移动。
* 移动时播放 walk 动画或占位动画。
* 行动后暂时标记为已行动。

要解释：

* BFS。
* AStarGrid2D。
* 移动范围和最短路径的区别。
* 逻辑碰撞。
* 地形移动消耗。
* RangeOverlay。

阶段结束文档：

* docs/07_movement_and_pathfinding.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 8：行动菜单与战斗

目标：

* 单位移动后弹出行动菜单。
* 菜单选项：攻击 / 等待。
* 如果选择攻击，显示攻击范围。
* 选择敌人后显示 BattlePreview。
* 实现 CombatResolver。
* 使用简单伤害公式：
  damage = attacker.str + weapon.might - defender.def
  damage 最小为 0
* 执行攻击。
* 播放 attack / hurt / death 动画或占位表现。
* HP 为 0 的单位从场上移除。

要解释：

* 行动菜单。
* 攻击范围。
* 战斗预览。
* CombatResolver。
* 战斗公式和表现分离。
* 动画和规则解耦。

阶段结束文档：

* docs/08_action_menu_and_combat.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 9：回合系统与状态机

目标：

* 实现玩家回合。
* 实现敌方回合。
* 每个单位一回合只能行动一次。
* 行动后单位变灰。
* 所有我方单位行动后，自动进入敌方回合。
* 敌方行动完后回到玩家回合。
* 创建或完善 GameState.gd 和 TurnManager.gd。

要解释：

* State Machine。
* Turn Manager。
* GameState。
* 玩家选择阶段。
* 移动阶段。
* 行动菜单阶段。
* 攻击阶段。
* 敌方行动阶段。
* 为什么回合制游戏特别需要清晰的状态管理。

阶段结束文档：

* docs/09_turn_system.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 10：敌人 AI

目标：

* 创建 EnemyAI.gd。
* 敌人寻找最近的我方单位。
* 如果能攻击，直接攻击。
* 如果不能攻击，向目标移动。
* 移动后如果能攻击，则攻击。
* 否则等待。
* Boss 可以设置为 stationary，不主动移动。
* 敌人行动要有简单延迟，方便观察。

要解释：

* 战棋 AI 的基本结构。
* 目标选择。
* 移动决策。
* 攻击决策。
* 为什么 AI 应该独立于 Unit 和 TurnManager。
* 简单 AI 和复杂 AI 的区别。

阶段结束文档：

* docs/10_enemy_ai.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 11：胜负、音效与 Boss cut-in

目标：

* 主角死亡时失败。
* Boss 死亡或敌人全灭时胜利。
* 添加 ResultPanel。
* 添加选择、移动、攻击、受击、胜利音效。
* Boss 第一次进入战斗前播放 Skeleton2D cut-in 或占位 cut-in。
* 添加简单镜头震动或 UI 动画。

要解释：

* 游戏流程闭环。
* 反馈感。
* 音效在游戏中的作用。
* AnimationPlayer 如何控制 UI、镜头、音效、cut-in。
* 为什么 vertical slice 要包含胜利和失败。

阶段结束文档：

* docs/11_win_lose_audio_cutscene.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 如遇问题，更新 docs/troubleshooting.md

完成后停下来。

---

## 阶段 12：整理、README 与导出

目标：

* 清理无用文件。
* 检查资源路径。
* 创建 README.md。
* 在 README 中说明项目目标、运行方式、已实现功能、学习概念。
* 尝试导出 Web 或桌面版本。
* 记录导出步骤和遇到的问题。
* 最后更新 docs/12_export_and_wrapup.md。

要解释：

* 原型整理。
* 打包发布。
* README 的作用。
* prototype 和 production 的区别。
* 后续如果继续扩展，应该从哪里开始。

阶段结束文档：

* docs/12_export_and_wrapup.md
* 更新 docs/00_project_overview.md
* 更新 docs/glossary.md
* 更新 docs/devlog.md
* 更新 docs/troubleshooting.md
* 创建 README.md

完成后停下来。

---

# 八、代码风格要求

* 使用 Godot 4.x GDScript。
* 代码要清晰直观，不要过度架构。
* 每个脚本顶部写注释，说明它负责什么。
* 关键函数写注释。
* 命名要稳定，不要频繁改名。
* 尽量每阶段结束时项目都能运行。
* 每次修改要说明影响范围。
* 不要一次性引入太多抽象。
* 不要做复杂 ECS、复杂事件总线、复杂存档系统。
* 优先完成可玩的闭环。

---

# 九、素材和版权要求

* 不要使用火焰纹章原版素材。
* 可以使用占位素材。
* 可以用纯色方块表示角色。
* 可以用简单几何图形表示 Boss cut-in。
* 可以后续接入免费素材，但要在 README 中记录素材来源和许可证。
* 如果不确定素材许可证，就不要使用。

---

# 十、Claude Code 执行要求

你在 Claude Code 中执行时，请遵循：

1. 先检查项目目录。
2. 不确定 Godot 版本时，先从 project.godot 或可用命令中判断。
3. 不要破坏已有文件。
4. 每次修改前先简要说明计划。
5. 每阶段完成后必须停止，等待我验证。
6. 每阶段都必须写对应 docs 文档。
7. 每阶段都必须更新 glossary.md 和 devlog.md。
8. 如果遇到错误，先修复；修复不了就写入 troubleshooting.md，并告诉我当前阻塞点。
9. 不要自动跳阶段。
10. 不要使用 copyrighted assets。

---

# 十一、阶段开始口令

现在请从阶段 0 开始。

请先检查当前目录是否已有 Godot 项目。
如果没有，请创建推荐项目结构、docs 目录和基础文档。
完成阶段 0 后停下来，告诉我如何在 Godot 中打开和验证项目初始化是否成功。