From d353e91f5e235ac5c0aac6ef99aec1e2907bdf06 Mon Sep 17 00:00:00 2001
From: 1165565692-lang <1165565692@qq.com>
Date: Tue, 9 Jun 2026 22:25:54 +0800
Subject: [PATCH] Organize project docs and clean local artifacts

---
 game/docs/README.md                    |   1 +
 game/docs/planning/development_plan.md | 840 +++++++++++++++++++++++++
 2 files changed, 841 insertions(+)
 create mode 100644 game/docs/planning/development_plan.md

diff --git a/game/docs/README.md b/game/docs/README.md
index 47c4bd0..20c35f2 100644
--- a/game/docs/README.md
+++ b/game/docs/README.md
@@ -4,6 +4,7 @@
 
 ## Planning
 
+- `planning/development_plan.md`：横板 2D ACT 清版游戏开发总计划，包含里程碑、玩法阶段、技术阶段和风险。
 - `planning/game_architecture_board.md`：游戏整体架构白板，包含思维导图、模块划分、数据流和阶段路线。
 - `planning/scene_build_plan.md`：第一关场景搭建计划，包含素材清单、场景分层和验收标准。
 
diff --git a/game/docs/planning/development_plan.md b/game/docs/planning/development_plan.md
new file mode 100644
index 0000000..6d700f9
--- /dev/null
+++ b/game/docs/planning/development_plan.md
@@ -0,0 +1,840 @@
+# 横板 2D ACT 清版游戏开发计划
+
+本文档用于规划基于 Frostbite2D-Engine 制作一款横板 2D ACT 清版游戏的开发路线。当前题材未确定，因此计划先围绕核心玩法、技术验证和内容管线推进，题材、美术风格和世界观在玩法原型稳定后再定。
+
+## 1. 项目目标
+
+### 1.1 游戏定位
+
+- 类型：横板 2D ACT / 清版动作
+- 视角：侧视角
+- 核心体验：移动、跳跃、闪避、近战连段、技能释放、清理成组敌人、阶段推进
+- 目标平台：Windows PC 优先，Nintendo Switch 可运行验证
+- 引擎基础：项目内 Frostbite2D-Engine
+
+### 1.2 第一阶段目标
+
+先做一个可玩的垂直切片，而不是直接扩展完整游戏。
+
+垂直切片应包含：
+
+- 一个可控制角色
+- 基础移动、跳跃、冲刺、攻击
+- 至少 2 种敌人
+- 一个小关卡
+- 基础血量、受击、死亡、胜利条件
+- 简单 UI
+- PC 可运行 exe
+- Switch 可运行 nro
+
+### 1.3 长期目标
+
+在垂直切片验证后，逐步扩展为完整清版 ACT：
+
+- 多关卡流程
+- 多种敌人和精英敌人
+- Boss 战
+- 角色成长或技能解锁
+- 存档
+- 音效、音乐、打击反馈
+- PC / Switch 双平台发布构建
+
+## 2. 开发原则
+
+### 2.1 先玩法，后题材
+
+题材未定时，不提前锁死美术和剧情。先用占位图和简单音效验证：
+
+- 操作是否顺手
+- 攻击距离是否舒服
+- 敌人压力是否合理
+- 受击、硬直、闪避是否清晰
+- 清版节奏是否有爽感
+
+### 2.2 小步快跑
+
+每个阶段都要产出可运行版本。避免长期只写底层系统但没有可玩内容。
+
+### 2.3 PC 优先，Switch 持续验证
+
+PC 端开发效率高，主循环先在 PC 上跑通。Switch 每完成一个重要阶段就编译并运行一次，避免最后集中处理平台问题。
+
+### 2.4 数据驱动
+
+角色、敌人、攻击、关卡尽量用配置数据驱动，减少硬编码。
+
+优先数据化：
+
+- 角色基础参数
+- 攻击判定框
+- 敌人参数
+- 掉落物
+- 关卡对象
+- 音效绑定
+
+## 3. 技术基础阶段
+
+### 3.1 编译链路确认
+
+当前已经验证：
+
+- Windows 静态库：`build/windows/x64/release/Frostbite2D.lib`
+- Windows 测试 exe：`build/windows/x64/release/Frostbite2DWindowsSmoke.exe`
+- Switch 静态库：`build/switch/aarch64/release/libFrostbite2D.a`
+- Switch 测试 nro：`build/switch/aarch64/release/switch_smoke/Frostbite2D_smoke_meta.nro`
+
+后续需要维护：
+
+- `BUILD.md` 中的 PC / Switch 编译命令
+- Windows DLL 复制流程
+- Switch NACP / icon 打包流程
+
+### 3.2 项目结构整理
+
+建议后续把游戏项目和引擎分层：
+
+```text
+Frostbite2D-Engine/
+├── Frostbite2D/              # 引擎源码
+├── examples/                 # smoke test
+├── game/                     # 游戏源码，后续新增
+│   ├── src/
+│   ├── include/
+│   ├── assets/
+│   └── docs/
+├── BUILD.md
+├── engine.lua
+└── xmake.lua
+```
+
+第一版游戏可以先放在：
+
+```text
+game/src
+game/assets
+```
+
+等项目变大后再拆分模块。
+
+### 3.3 引擎能力检查
+
+需要确认和补齐这些能力：
+
+- 窗口和渲染初始化
+- Sprite 渲染
+- 动画播放
+- 批量渲染
+- 输入系统
+- 场景管理
+- 音频播放
+- 资源读取
+- 存档系统
+- 碰撞检测
+- 简单 UI
+- PC / Switch 条件编译
+
+其中碰撞、ACT 战斗、关卡对象系统可能需要在游戏层实现，必要时再下沉到引擎。
+
+## 4. 玩法原型阶段
+
+### 4.1 角色控制
+
+目标：做出一个手感可调的主角。
+
+功能：
+
+- 左右移动
+- 地面加速和减速
+- 空中移动
+- 跳跃
+- 可变跳高
+- 下落重力
+- 落地检测
+- 冲刺或闪避
+- 面向方向切换
+
+需要可调参数：
+
+- 最大移动速度
+- 地面加速度
+- 地面摩擦
+- 空中加速度
+- 跳跃初速度
+- 重力
+- 最大下落速度
+- 冲刺速度
+- 冲刺时间
+- 冲刺冷却
+
+验收标准：
+
+- 角色能在测试地形上稳定移动
+- 跳跃不会穿地
+- 手柄和键盘都能控制
+- 参数可以快速修改
+
+### 4.2 基础物理和碰撞
+
+横板 ACT 不需要复杂真实物理，优先做稳定的盒体碰撞。
+
+功能：
+
+- AABB 碰撞盒
+- 地面碰撞
+- 墙体碰撞
+- 单向平台，视需求后置
+- 角色 hurtbox
+- 攻击 hitbox
+- 敌人 hurtbox
+- 触发器区域
+
+验收标准：
+
+- 角色不会穿墙穿地
+- 攻击命中能稳定检测
+- 敌人和角色的受击框可以调试显示
+
+### 4.3 基础攻击
+
+目标：实现 ACT 清版的最小战斗闭环。
+
+功能：
+
+- 普通攻击 3 连段
+- 攻击前摇、 active、后摇
+- 攻击命中敌人
+- 敌人扣血
+- 命中停顿
+- 简单击退
+- 攻击期间限制移动
+- 攻击取消规则，先简单实现
+
+可调参数：
+
+- 每段攻击伤害
+- 每段攻击持续时间
+- 攻击判定框位置
+- 攻击判定框大小
+- 击退距离
+- 命中停顿帧数
+- 连段输入缓冲时间
+
+验收标准：
+
+- 玩家能完成三段普通攻击
+- 攻击判定可视化
+- 敌人被击中有明显反馈
+
+### 4.4 受击和生命
+
+功能：
+
+- 角色生命值
+- 敌人生命值
+- 受击硬直
+- 无敌时间
+- 死亡状态
+- 击飞或击退
+- 受击闪白
+
+验收标准：
+
+- 敌人能被打死
+- 玩家能被敌人打死
+- 受击反馈清晰
+- 不会重复多次扣血，除非设计允许
+
+## 5. 敌人系统阶段
+
+### 5.1 敌人基础框架
+
+敌人需要状态机：
+
+- Idle
+- Patrol
+- Chase
+- Attack
+- Hitstun
+- Knockback
+- Dead
+
+基础字段：
+
+- 血量
+- 移动速度
+- 攻击力
+- 视野范围
+- 攻击范围
+- 碰撞盒
+- 受击盒
+- 掉落表
+
+### 5.2 第一种敌人：近战杂兵
+
+行为：
+
+- 玩家进入范围后接近
+- 到达攻击范围后攻击
+- 被攻击时硬直
+- 死亡后消失
+
+验收标准：
+
+- 能追踪玩家
+- 能攻击玩家
+- 能被连段压制
+
+### 5.3 第二种敌人：远程或盾兵
+
+建议二选一：
+
+- 远程兵：保持距离，发射投射物
+- 盾兵：正面减伤，需要绕后或破防
+
+目的：
+
+- 让清版战斗不只是站桩连打
+- 验证玩家移动、闪避、攻击选择
+
+### 5.4 敌人生成器
+
+功能：
+
+- 关卡中放置敌人生成点
+- 进入触发区域后生成一波敌人
+- 当前波次清完后打开出口
+- 支持多波次
+
+验收标准：
+
+- 一个房间能刷出 2 到 3 波敌人
+- 清完敌人后进入下一段
+
+## 6. 关卡系统阶段
+
+### 6.1 测试关卡
+
+先做一个灰盒关卡：
+
+- 起点
+- 平台
+- 墙体
+- 2 到 3 个战斗房间
+- 终点
+
+使用简单矩形和占位贴图即可。
+
+### 6.2 摄像机
+
+功能：
+
+- 跟随玩家
+- 平滑移动
+- 限制在关卡边界内
+- 战斗房间锁定，视需求实现
+
+验收标准：
+
+- 玩家移动时镜头稳定
+- 不露出关卡外区域
+- 战斗中镜头不乱晃
+
+### 6.3 关卡数据格式
+
+初期可以用 JSON：
+
+```json
+{
+  "player_spawn": { "x": 100, "y": 300 },
+  "bounds": { "x": 0, "y": 0, "w": 3200, "h": 720 },
+  "solids": [],
+  "enemy_spawns": [],
+  "triggers": []
+}
+```
+
+后续可以考虑接入 Tiled，或者制作自定义简单编辑器。
+
+## 7. 动画和美术阶段
+
+### 7.1 占位动画
+
+先用简单色块或临时素材完成：
+
+- Idle
+- Run
+- Jump
+- Fall
+- Dash
+- Attack1
+- Attack2
+- Attack3
+- Hit
+- Death
+
+敌人至少需要：
+
+- Idle
+- Move
+- Attack
+- Hit
+- Death
+
+### 7.2 动画事件
+
+ACT 游戏需要动画事件：
+
+- 第几帧开启攻击判定
+- 第几帧关闭攻击判定
+- 第几帧播放音效
+- 第几帧允许连段输入
+- 第几帧允许取消
+
+建议设计一个简单事件表：
+
+```json
+{
+  "attack_1": {
+    "events": [
+      { "frame": 3, "type": "hitbox_on", "id": "slash_1" },
+      { "frame": 6, "type": "hitbox_off", "id": "slash_1" },
+      { "frame": 8, "type": "combo_window_on" }
+    ]
+  }
+}
+```
+
+## 8. 战斗体验阶段
+
+### 8.1 打击反馈
+
+优先级很高。
+
+需要实现：
+
+- 命中停顿
+- 角色/敌人闪白
+- 屏幕轻微震动
+- 击退
+- 命中特效
+- 命中音效
+- 飘字，视风格决定
+
+### 8.2 连段和技能
+
+第一版：
+
+- 轻攻击 3 连
+- 重攻击 1 个
+- 闪避
+- 跳跃攻击
+
+第二版：
+
+- 上挑
+- 空中追击
+- 破防
+- 特殊技能
+- 能量条
+
+### 8.3 战斗规则
+
+需要明确：
+
+- 玩家是否有精力条
+- 闪避是否有无敌帧
+- 敌人攻击是否可打断
+- 是否有浮空
+- 是否有倒地
+- 是否有处决或终结技
+- 是否有防御或格挡
+
+建议垂直切片先不做太复杂：
+
+- 闪避有短暂无敌
+- 普通敌人可被打断
+- 精英敌人部分攻击霸体
+- Boss 攻击不可轻易打断
+
+## 9. UI 和流程阶段
+
+### 9.1 游戏内 UI
+
+第一版：
+
+- 玩家血条
+- 敌人血条，精英和 Boss 显示
+- 当前关卡目标
+- 暂停菜单
+
+第二版：
+
+- 技能冷却
+- 能量条
+- 道具栏
+- 伤害数字
+
+### 9.2 菜单流程
+
+最小流程：
+
+- 启动
+- 主菜单
+- 开始游戏
+- 暂停
+- 继续
+- 退出
+- 游戏结束
+
+## 10. 音频阶段
+
+### 10.1 音效
+
+优先实现：
+
+- 普通攻击挥砍
+- 命中
+- 受击
+- 跳跃
+- 落地
+- 闪避
+- 敌人死亡
+- UI 确认/取消
+
+### 10.2 音乐
+
+垂直切片：
+
+- 一个关卡 BGM
+- 一个战斗 BGM，视需求
+- Boss BGM，后置
+
+## 11. 存档和配置阶段
+
+### 11.1 配置保存
+
+需要保存：
+
+- 分辨率
+- 全屏
+- 音量
+- 键位
+- 语言
+
+### 11.2 游戏存档
+
+垂直切片可先只保存：
+
+- 当前关卡
+- 玩家生命上限
+- 已解锁技能
+
+完整版本再扩展：
+
+- 收集品
+- 关卡进度
+- 难度
+- 游玩时间
+
+## 12. 平台适配阶段
+
+### 12.1 Windows
+
+需要持续验证：
+
+- Debug / Release 构建
+- EXE 启动
+- DLL 打包
+- 窗口和全屏切换
+- Xbox 手柄输入
+- 中文路径兼容
+
+### 12.2 Switch
+
+需要持续验证：
+
+- `.a` 静态库构建
+- `.nro` 生成
+- NACP / icon 元数据
+- Ryujinx 启动
+- 真机启动，后续条件允许再测
+- 手柄输入
+- 性能和内存
+
+## 13. 工具和调试
+
+### 13.1 调试显示
+
+必须尽早做：
+
+- 碰撞盒显示
+- 攻击判定显示
+- 敌人状态显示
+- FPS 显示
+- 当前场景名
+- 玩家坐标
+
+### 13.2 参数热重载
+
+中期目标：
+
+- 角色参数 JSON 热重载
+- 敌人参数 JSON 热重载
+- 攻击判定 JSON 热重载
+
+这样能大幅提高调手感效率。
+
+### 13.3 简单关卡编辑流程
+
+初期可手写 JSON。
+
+中期可选择：
+
+- 接入 Tiled
+- 写一个简单内部编辑器
+- 使用 CSV / JSON + 调试可视化
+
+## 14. 题材方向备选
+
+题材暂不确定，但可以先保留几个方向：
+
+### 14.1 现代都市异能
+
+优点：
+
+- 动作设计自由
+- 敌人类型丰富
+- 场景容易做成街道、地铁、工厂
+
+风险：
+
+- 美术需要统一风格
+
+### 14.2 东方奇幻
+
+优点：
+
+- 武器、技能、怪物设计空间大
+- 适合夸张打击效果
+
+风险：
+
+- 素材工作量较大
+
+### 14.3 科幻废土
+
+优点：
+
+- 机械敌人、枪械、近战都能兼容
+- 关卡可做工厂、飞船、遗迹
+
+风险：
+
+- 需要较强美术设定
+
+### 14.4 暗黑童话
+
+优点：
+
+- 视觉记忆点强
+- Boss 和敌人设计有特色
+
+风险：
+
+- 氛围和动作爽感需要平衡
+
+题材决策建议放在第一版战斗原型完成之后。
+
+## 15. 阶段里程碑
+
+### Milestone 0：构建基线
+
+状态：已基本完成。
+
+内容：
+
+- Windows 引擎库可编译
+- Windows smoke exe 可运行
+- Switch 引擎库可编译
+- Switch smoke nro 可运行
+- 编译文档完成
+
+### Milestone 1：角色可控
+
+目标：
+
+- 游戏项目入口
+- 主角可移动、跳跃、冲刺
+- 测试地图
+- 摄像机跟随
+- PC 可运行
+
+完成标准：
+
+- 能在测试关卡里稳定跑跳
+- 操作参数可调
+
+### Milestone 2：战斗闭环
+
+目标：
+
+- 普通攻击 3 连
+- 攻击判定
+- 敌人受击
+- 敌人死亡
+- 玩家受击
+
+完成标准：
+
+- 可以打死敌人
+- 敌人可以打死玩家
+- 打击反馈初步成立
+
+### Milestone 3：清版房间
+
+目标：
+
+- 关卡触发器
+- 敌人波次
+- 房间封锁和解锁
+- 简单胜利条件
+
+完成标准：
+
+- 玩家进入房间后刷敌
+- 清完敌人后进入下一段
+
+### Milestone 4：垂直切片
+
+目标：
+
+- 一个完整小关卡
+- 两种敌人
+- 一个小 Boss 或精英敌人
+- UI
+- 音效
+- PC exe
+- Switch nro
+
+完成标准：
+
+- 从开始到结束可完整游玩
+- 没有阻断流程的崩溃
+- PC 和 Ryujinx 都能启动
+
+### Milestone 5：题材确定
+
+目标：
+
+- 选定世界观
+- 确定主角设定
+- 确定敌人阵营
+- 确定美术风格
+- 确定第一章关卡主题
+
+完成标准：
+
+- 有一页核心设定文档
+- 有主角和敌人参考图或风格板
+- 不再使用完全抽象占位方向
+
+### Milestone 6：内容扩展
+
+目标：
+
+- 3 到 5 个普通敌人
+- 1 到 2 个 Boss
+- 3 个以上关卡
+- 技能成长
+- 存档
+
+完成标准：
+
+- 游戏可玩 20 到 30 分钟
+- 形成基本内容节奏
+
+## 16. 近期任务清单
+
+### 第 1 周
+
+- 新增 `game` 目录和游戏 target
+- 做 Windows 游戏入口
+- 做 Switch 游戏入口
+- 显示一个空场景
+- 加载一张占位贴图
+- 显示 FPS / 调试信息
+
+### 第 2 周
+
+- 实现玩家移动
+- 实现跳跃
+- 实现地面碰撞
+- 实现摄像机跟随
+- 搭建灰盒测试关卡
+
+### 第 3 周
+
+- 实现普通攻击
+- 实现 hitbox / hurtbox
+- 实现敌人基础类
+- 实现第一种近战敌人
+- 加入调试碰撞框显示
+
+### 第 4 周
+
+- 实现受击硬直
+- 实现击退
+- 实现生命和死亡
+- 加入命中停顿
+- 加入基础音效
+- 做第一版战斗房间
+
+## 17. 风险和注意事项
+
+### 17.1 引擎仍在早期
+
+当前引擎已经能编译 PC / Switch，但完整游戏开发中可能会继续暴露：
+
+- 渲染接口平台差异
+- 资源路径问题
+- 音频格式兼容问题
+- 输入差异
+- 存档路径差异
+
+需要每个里程碑都做 PC 和 Switch smoke 验证。
+
+### 17.2 清版 ACT 对手感要求高
+
+如果移动和攻击手感不好，后续内容越多越难改。前期要优先调：
+
+- 移动速度
+- 攻击前后摇
+- 命中停顿
+- 击退
+- 敌人硬直
+- 闪避无敌
+
+### 17.3 美术工作量不可低估
+
+横板 ACT 需要大量动画。题材确定前不要过早制作大量正式动画，先用占位素材验证。
+
+### 17.4 Switch 性能要早测
+
+清版游戏可能有大量敌人、特效和贴图。Switch 上要关注：
+
+- 批量渲染是否稳定
+- 贴图大小
+- 同屏敌人数
+- 粒子数量
+- 音频内存
+
+## 18. 下一步
+
+最合理的下一步是创建真正的游戏 target：
+
+- `Frostbite2DGame` Windows exe
+- `Frostbite2DGame` Switch elf/nro
+- `game/src/main.cpp`
+- `game/assets/`
+
+然后进入 Milestone 1：主角移动和测试地图。