Organize project docs and clean local artifacts

2026-06-09 22:25:54 +08:00
parent 3fc9caa80b
commit d353e91f5e
2 changed files with 841 additions and 0 deletions
@@ -4,6 +4,7 @@
 ## Planning
 - `planning/development_plan.md`：横板 2D ACT 清版游戏开发总计划，包含里程碑、玩法阶段、技术阶段和风险。
 - `planning/game_architecture_board.md`：游戏整体架构白板，包含思维导图、模块划分、数据流和阶段路线。
 - `planning/scene_build_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：主角移动和测试地图。