Organize game planning docs
This commit is contained in:
@@ -0,0 +1,420 @@
|
||||
# 游戏整体架构计划：思维导图与白板
|
||||
|
||||
目标：把项目从“能跑的白盒 Demo”推进为可持续扩展的横板 2D ACT 清版游戏工程。本文先作为整体架构白板，后续每个模块再拆成独立任务文档。
|
||||
|
||||
## 思维导图
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
root((横板 2D ACT 游戏))
|
||||
核心体验
|
||||
横向推进
|
||||
清版战斗
|
||||
平台移动
|
||||
近战连段
|
||||
关卡节奏
|
||||
游戏循环
|
||||
进入关卡
|
||||
探索与移动
|
||||
触发战斗区域
|
||||
击败敌人
|
||||
解锁推进
|
||||
结算与升级
|
||||
角色系统
|
||||
玩家
|
||||
输入
|
||||
移动
|
||||
跳跃
|
||||
攻击
|
||||
受击
|
||||
动画状态机
|
||||
敌人
|
||||
巡逻
|
||||
追击
|
||||
攻击
|
||||
受击硬直
|
||||
死亡
|
||||
NPC与可交互物
|
||||
对话
|
||||
机关
|
||||
可破坏物
|
||||
战斗系统
|
||||
Hitbox
|
||||
Hurtbox
|
||||
伤害结算
|
||||
击退
|
||||
霸体
|
||||
连击窗口
|
||||
命中特效
|
||||
调试显示
|
||||
关卡系统
|
||||
场景数据
|
||||
碰撞数据
|
||||
视觉层
|
||||
战斗区域
|
||||
敌人出生点
|
||||
镜头限制
|
||||
出入口
|
||||
渲染与资源
|
||||
Sprite
|
||||
Tileset
|
||||
背景视差
|
||||
前景遮挡
|
||||
特效
|
||||
音频
|
||||
资源清单
|
||||
数据驱动
|
||||
动画表
|
||||
角色参数
|
||||
敌人配置
|
||||
关卡配置
|
||||
攻击配置
|
||||
掉落配置
|
||||
工具与调试
|
||||
白盒编辑
|
||||
碰撞可视化
|
||||
战斗区域可视化
|
||||
Hitbox可视化
|
||||
帧率与日志
|
||||
构建文档
|
||||
NS平台构建
|
||||
```
|
||||
|
||||
## 白板总览
|
||||
|
||||
```text
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| Game Loop | ---> | Scene | ---> | Stage |
|
||||
| 关卡进入/推进/结算 | | 场景编排与生命周期 | | 关卡数据与视觉层 |
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| | |
|
||||
v v v
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| Actor | ---> | Movement | ---> | Collision |
|
||||
| 玩家/敌人/道具/物体 | | 重力/速度/平台移动 | | 地面/平台/边界 |
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| |
|
||||
v v
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| Combat | ---> | Animation | ---> | Render |
|
||||
| Hitbox/伤害/击退 | | 状态机/帧表/过渡 | | Sprite/Tile/特效 |
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
|
|
||||
v
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
| Data | ---> | Debug | ---> | Build |
|
||||
| 配置表/关卡/参数 | | 可视化/日志/测试 | | PC/Switch/资源复制 |
|
||||
+----------------------+ +----------------------+ +----------------------+
|
||||
```
|
||||
|
||||
## 模块白板
|
||||
|
||||
### 1. Core
|
||||
|
||||
职责：
|
||||
|
||||
- 管理游戏级常量、资源路径、输入快照、运行配置。
|
||||
- 隔离 SDL 等底层输入细节，让角色逻辑只消费 `InputState`。
|
||||
- 为后续手柄、Switch Joy-Con、键位配置留接口。
|
||||
|
||||
已有：
|
||||
|
||||
- `core/game_config.h`
|
||||
- `core/asset_paths.h`
|
||||
- `core/input_state.*`
|
||||
- `core/debug_flags.h`
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `GameContext`，统一传递全局服务。
|
||||
- 输入层支持键盘和手柄统一映射。
|
||||
|
||||
### 2. Scene
|
||||
|
||||
职责：
|
||||
|
||||
- 管理场景生命周期。
|
||||
- 装载关卡数据。
|
||||
- 创建玩家、敌人、道具和场景对象。
|
||||
- 控制镜头、战斗区域、关卡推进。
|
||||
|
||||
已有：
|
||||
|
||||
- `scene/whitebox_scene.*`
|
||||
|
||||
下一步：
|
||||
|
||||
- 抽象 `GameplayScene` 作为通用玩法场景基类。
|
||||
- `WhiteboxScene` 只保留第一关测试内容。
|
||||
- 引入 battle zone 触发逻辑。
|
||||
|
||||
### 3. Stage
|
||||
|
||||
职责：
|
||||
|
||||
- 表达关卡世界：碰撞、视觉层、背景、道具、出生点、镜头范围。
|
||||
- 将白盒数据逐步替换为 tileset 和 props。
|
||||
|
||||
已有：
|
||||
|
||||
- `data/level_definition.h`
|
||||
- `data/whitebox_level.cpp`
|
||||
- `movement/platform_world.*`
|
||||
- `stage/stage_renderer.*`
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `StageLayer` 数据结构。
|
||||
- 关卡宽度扩展到 2400 到 3200 像素。
|
||||
- 引入远景/中景/地面三层绘制。
|
||||
|
||||
### 4. Actor
|
||||
|
||||
职责：
|
||||
|
||||
- 表达游戏对象：玩家、敌人、道具、投射物、可破坏物。
|
||||
- 每个 Actor 只处理自身状态，不直接管理全局流程。
|
||||
|
||||
已有：
|
||||
|
||||
- `actor/player_actor.*`
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `EnemyActor`。
|
||||
- 增加 `BreakablePropActor`。
|
||||
- 抽出 `CharacterActor` 作为玩家和敌人的共同基类。
|
||||
- 将玩家动画切换改为数据驱动。
|
||||
|
||||
### 5. Movement
|
||||
|
||||
职责：
|
||||
|
||||
- 处理速度、重力、平台落地、边界限制。
|
||||
- 后续支持斜坡、墙体、击退、空中状态。
|
||||
|
||||
已有：
|
||||
|
||||
- `MovementBody`
|
||||
- `PlatformWorld`
|
||||
- `PlatformMover`
|
||||
|
||||
下一步：
|
||||
|
||||
- 支持水平墙体阻挡。
|
||||
- 支持击退速度覆盖。
|
||||
- 支持落地事件。
|
||||
- 支持移动调试可视化。
|
||||
|
||||
### 6. Combat
|
||||
|
||||
职责：
|
||||
|
||||
- 管理攻击盒、受击盒、伤害结算、击退、硬直、命中特效。
|
||||
- 保证战斗逻辑不散落在 Actor 内部。
|
||||
|
||||
已有：
|
||||
|
||||
- `combat/hitbox.h`
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `CombatSystem`。
|
||||
- 每帧收集 active hitbox / hurtbox。
|
||||
- 支持 team 过滤、重复命中过滤、伤害事件。
|
||||
- 增加 debug hitbox 绘制。
|
||||
|
||||
### 7. Animation
|
||||
|
||||
职责：
|
||||
|
||||
- 管理 spritesheet 帧、动画状态、播放速度、循环和过渡。
|
||||
- 避免每个 Actor 手写帧切换。
|
||||
|
||||
当前状态：
|
||||
|
||||
- `PlayerActor` 内部硬编码 idle/run/punch 动画。
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `AnimationClip`。
|
||||
- 增加 `SpriteAnimator`。
|
||||
- 增加动画配置表。
|
||||
- 攻击动画和 hitbox active frame 绑定。
|
||||
|
||||
### 8. Data
|
||||
|
||||
职责：
|
||||
|
||||
- 将玩法参数从 C++ 硬编码逐步迁移到数据。
|
||||
- 支持关卡、敌人、动画、攻击、掉落配置。
|
||||
|
||||
当前状态：
|
||||
|
||||
- 关卡仍由 `CreateWhiteboxLevel()` 硬编码。
|
||||
|
||||
下一步：
|
||||
|
||||
- 先用 C++ struct 稳定字段。
|
||||
- 再迁移到 JSON 或编辑器导出格式。
|
||||
- 资源路径统一记录，避免散落字符串。
|
||||
|
||||
### 9. Render 与资源
|
||||
|
||||
职责：
|
||||
|
||||
- 绘制角色、关卡、背景、道具、特效和调试图形。
|
||||
- 管理资源目录和运行时拷贝。
|
||||
|
||||
已有：
|
||||
|
||||
- `game/assets/character/male/`
|
||||
- `game/assets/shaders/`
|
||||
- `xmake.lua` 自动复制 `game/assets`
|
||||
|
||||
下一步：
|
||||
|
||||
- 增加 `game/assets/stage/stage_01/`。
|
||||
- 引入 tileset、背景、props。
|
||||
- 增加视差背景绘制。
|
||||
- 建立素材来源和授权记录。
|
||||
|
||||
### 10. Debug 与工具
|
||||
|
||||
职责：
|
||||
|
||||
- 提供开发时必要的可视化和状态观察。
|
||||
- 降低调试碰撞、战斗和关卡触发的成本。
|
||||
|
||||
下一步：
|
||||
|
||||
- `debug/debug_overlay.*` 已经提供碰撞和玩家包围盒绘制。
|
||||
- `F1` 切换 debug overlay。
|
||||
- 绘制平台碰撞。
|
||||
- 绘制 battle zone。
|
||||
- 绘制 spawn point。
|
||||
- 绘制 hitbox / hurtbox。
|
||||
- 输出当前场景、角色状态、FPS。
|
||||
|
||||
### 11. Platform
|
||||
|
||||
职责：
|
||||
|
||||
- 保持 PC 和 NS 共用游戏逻辑。
|
||||
- 只在入口、构建、资源部署、平台输入处做差异化。
|
||||
|
||||
已有：
|
||||
|
||||
- `game/src/main.cpp`：统一游戏入口，通过 `__SWITCH__` 区分 Windows/PC 与 Switch/NS。
|
||||
- `Frostbite2DGame`：Windows 游戏目标。
|
||||
- `Frostbite2DGameSwitch`：Switch 游戏目标，生成 `NSUnknownGame.nro`。
|
||||
- Switch NRO 已内嵌 `game/` 为 RomFS，运行时优先读取 `romfs:/assets`。
|
||||
|
||||
下一步：
|
||||
|
||||
- 将 Switch Joy-Con 输入接入 `InputStateProvider`。
|
||||
- 在 Ryujinx 或真机上验证主循环、shader 和角色纹理。
|
||||
- 如果 RomFS 不可用，再补 SD 卡外部资源部署脚本。
|
||||
|
||||
## 数据流白板
|
||||
|
||||
```text
|
||||
输入
|
||||
SDL Keyboard / Controller
|
||||
-> InputStateProvider
|
||||
-> InputState
|
||||
-> PlayerActor
|
||||
|
||||
移动
|
||||
PlayerActor / EnemyActor
|
||||
-> MovementBody
|
||||
-> PlatformMover
|
||||
-> PlatformWorld
|
||||
-> 更新 Actor position / grounded
|
||||
|
||||
战斗
|
||||
Actor 当前攻击状态
|
||||
-> 生成 Hitbox
|
||||
-> CombatSystem
|
||||
-> Hurtbox 匹配
|
||||
-> DamageEvent
|
||||
-> Actor 受击/击退/死亡
|
||||
|
||||
关卡
|
||||
LevelDefinition
|
||||
-> Scene 创建 Actor
|
||||
-> StageRenderer 绘制视觉层
|
||||
-> PlatformWorld 提供碰撞
|
||||
-> BattleZone 控制推进
|
||||
|
||||
渲染
|
||||
Scene::Render
|
||||
-> StageRenderer
|
||||
-> Actor::Render
|
||||
-> Effects
|
||||
-> DebugOverlay
|
||||
```
|
||||
|
||||
## 开发路线白板
|
||||
|
||||
### Milestone 1：白盒玩法闭环
|
||||
|
||||
目标：验证 ACT 基础手感。
|
||||
|
||||
- 玩家移动、跳跃、出拳稳定。
|
||||
- 第一关横向推进可从头跑到尾。
|
||||
- battle zone 可触发、锁镜头、解锁。
|
||||
- 有 1 种敌人占位。
|
||||
- 有 hitbox/hurtbox debug。
|
||||
|
||||
### Milestone 2：灰盒战斗验证
|
||||
|
||||
目标：验证清版节奏。
|
||||
|
||||
- 玩家 2 到 3 段基础连击。
|
||||
- 敌人追击、攻击、受击、死亡。
|
||||
- 每个 battle zone 有敌人波次。
|
||||
- 有简单掉落或奖励。
|
||||
- 关卡能完整结算。
|
||||
|
||||
### Milestone 3：第一关美术测试
|
||||
|
||||
目标：替换白盒视觉。
|
||||
|
||||
- 场景有 2 到 3 层视差背景。
|
||||
- 地面和平台使用 tileset。
|
||||
- props 丰富空间轮廓。
|
||||
- 保留 debug overlay。
|
||||
- 记录素材来源和授权。
|
||||
|
||||
### Milestone 4：数据化
|
||||
|
||||
目标：降低后续扩展成本。
|
||||
|
||||
- 动画配置数据化。
|
||||
- 攻击参数数据化。
|
||||
- 敌人参数数据化。
|
||||
- 关卡数据逐步外部化。
|
||||
|
||||
## 当前优先级
|
||||
|
||||
下一步建议按这个顺序做：
|
||||
|
||||
1. `BattleZone`：做清版推进的核心框架。
|
||||
2. `SwitchInput`：把 Joy-Con/手柄输入接入 `InputStateProvider`。
|
||||
3. `EnemyActor`：做第一个敌人占位。
|
||||
4. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。
|
||||
5. `SpriteAnimator`：把玩家动画从硬编码改成组件。
|
||||
6. `StageLayer`：把白盒视觉层扩展为背景、tiles 和 props。
|
||||
|
||||
## 素材协作提示
|
||||
|
||||
你找素材时优先找：
|
||||
|
||||
- 横版 tileset：地面、平台、墙面。
|
||||
- 远景/中景背景：可以横向拼接。
|
||||
- props：箱子、桶、路障、门、灯、标牌。
|
||||
- 敌人临时素材：有 idle/run/attack/hurt/death 最好。
|
||||
- 特效：命中火花、尘土、落地、破坏碎片。
|
||||
|
||||
素材回来后先不急着追求最终题材，先按 `stage_01` 做一个可玩的美术测试关。
|
||||
@@ -0,0 +1,210 @@
|
||||
# 场景搭建计划
|
||||
|
||||
目标：先把第一关从白盒推进到可替换素材的灰盒/美术测试场景。当前游戏方向暂定为横板 2D ACT 清版，因此场景需要服务于移动、跳跃、攻击判定、敌人刷出、镜头推进和战斗节奏。
|
||||
|
||||
## 1. 当前起点
|
||||
|
||||
已有内容：
|
||||
|
||||
- `WhiteboxScene`：当前白盒场景入口。
|
||||
- `CreateWhiteboxLevel()`：第一版关卡数据，包含平台碰撞和白盒装饰块。
|
||||
- `PlatformWorld` / `PlatformMover`：基础平台碰撞和重力移动。
|
||||
- `PlayerActor`：玩家移动、跳跃、出拳和基础动画。
|
||||
- `Frostbite2DGame`：Windows 游戏目标，可直接构建运行。
|
||||
|
||||
当前白盒只解决“能跑、能跳、能看到关卡结构”。下一步要把场景拆成数据层、视觉层和玩法层。
|
||||
|
||||
## 2. 第一关场景目标
|
||||
|
||||
第一关不急着做最终题材，先做通用 ACT 测试关：
|
||||
|
||||
- 横向推进，总宽度先控制在 2400 到 3200 像素。
|
||||
- 主要视口仍用 1280x720。
|
||||
- 地面以平路为主，加入 2 到 3 段平台高低差。
|
||||
- 至少预留 3 个战斗区域，每个区域宽度 480 到 720 像素。
|
||||
- 每个战斗区域有明确的入口、站位空间、敌人刷出点和退出方向。
|
||||
- 保留一个跳跃测试段，用来验证移动手感。
|
||||
- 保留一个窄平台/边缘段，用来验证镜头和碰撞。
|
||||
|
||||
## 3. 场景分层
|
||||
|
||||
后续场景按以下层拆：
|
||||
|
||||
```text
|
||||
background_far 远景天空、城市、山体、洞窟深处等，不参与碰撞
|
||||
background_mid 中景建筑、树、墙面、远处平台，不参与碰撞
|
||||
level_collision 地面、平台、墙体，只负责碰撞
|
||||
level_visual 和碰撞对齐的地面/墙面贴图
|
||||
props_back 柱子、牌子、箱子、草丛等后景装饰
|
||||
actors 玩家、敌人、道具、投射物
|
||||
props_front 前景遮挡物、栏杆、近景草等
|
||||
effects 攻击特效、命中特效、尘土、碎片
|
||||
ui HUD、提示、调试信息
|
||||
```
|
||||
|
||||
白盒阶段先实现：
|
||||
|
||||
- `level_collision`
|
||||
- `level_visual`
|
||||
- `props_back`
|
||||
- `actors`
|
||||
|
||||
前景遮挡和特效后面再加。
|
||||
|
||||
## 4. 素材寻找清单
|
||||
|
||||
你先找这些素材，优先像素风，尺寸最好能和 128x128 角色兼容。
|
||||
|
||||
### 必需素材
|
||||
|
||||
- 地面 tileset：至少包含平地、左边缘、右边缘、平台中段。
|
||||
- 墙面或背景 tileset：用于挡板、台阶、平台侧面。
|
||||
- 远景背景：一张或多张可横向拼接背景。
|
||||
- 中景背景：建筑、树、管线、洞窟墙等可以做视差的图层。
|
||||
- 基础装饰物：箱子、桶、路灯、告示牌、碎石、草丛等。
|
||||
- 关卡边界标识：门、路障、出口牌、传送门等任选。
|
||||
|
||||
### ACT 玩法相关素材
|
||||
|
||||
- 敌人站位/出生点可用的临时标记图。
|
||||
- 可破坏物：木箱、罐子、障碍物。
|
||||
- 攻击命中特效：小型 hit spark。
|
||||
- 落地/跑步尘土：小型 dust effect。
|
||||
|
||||
### 可选素材
|
||||
|
||||
- 前景遮挡：栏杆、柱子、近景树叶。
|
||||
- 光照叠加图：窗口光、路灯光、火光等。
|
||||
- 环境动画：旗子、火焰、流水、机器灯。
|
||||
- 背景音乐和环境音。
|
||||
|
||||
## 5. 素材规格建议
|
||||
|
||||
角色当前是 128x128 帧，场景素材建议：
|
||||
|
||||
- tileset 单格优先 `32x32`、`48x48` 或 `64x64`。
|
||||
- 平台碰撞块可以和视觉块分离，不要求每张图都精准碰撞。
|
||||
- 背景图宽度最好大于 1280，或能无缝横向重复。
|
||||
- PNG 优先，透明背景用于 props 和 effects。
|
||||
- 同一套素材尽量保持统一像素密度。
|
||||
- 文件名使用英文小写和下划线，例如 `factory_floor_tiles.png`。
|
||||
|
||||
建议素材目录：
|
||||
|
||||
```text
|
||||
game/assets/stage/stage_01/
|
||||
├─ background/
|
||||
├─ tiles/
|
||||
├─ props/
|
||||
├─ effects/
|
||||
└─ audio/
|
||||
```
|
||||
|
||||
## 6. 工程实现步骤
|
||||
|
||||
### Step 1：扩展关卡数据结构
|
||||
|
||||
把 `LevelDefinition` 从纯白盒数据扩展为：
|
||||
|
||||
- 世界宽高。
|
||||
- 碰撞平台列表。
|
||||
- 视觉 tile/prop 列表。
|
||||
- 玩家出生点。
|
||||
- 敌人出生点。
|
||||
- 战斗区域触发范围。
|
||||
- 镜头限制范围。
|
||||
|
||||
### Step 2：实现 StageRenderer
|
||||
|
||||
新增 `scene` 或 `stage` 模块，负责绘制：
|
||||
|
||||
- 背景色。
|
||||
- 远景背景。
|
||||
- 中景背景。
|
||||
- tile 层。
|
||||
- prop 层。
|
||||
- debug 碰撞层。
|
||||
|
||||
第一版可以继续用 `Renderer::drawQuad` 和 `Sprite`，不急着做 tilemap 优化。
|
||||
|
||||
### Step 3：替换白盒视觉
|
||||
|
||||
保持碰撞数据不变，先把地面和平台换成 tileset。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 玩家仍然能正常落地和跳跃。
|
||||
- 视觉地面和碰撞地面误差不超过 4 像素。
|
||||
- 镜头移动时背景不黑屏、不闪烁。
|
||||
|
||||
### Step 4：加入视差背景
|
||||
|
||||
远景和中景随相机不同速度移动：
|
||||
|
||||
- 远景速度：相机速度的 20% 到 35%。
|
||||
- 中景速度：相机速度的 45% 到 65%。
|
||||
- 地面和角色速度：100%。
|
||||
|
||||
### Step 5：加入战斗区域数据
|
||||
|
||||
在关卡中标出 3 个 battle zone：
|
||||
|
||||
- `zone_01_intro`
|
||||
- `zone_02_platform`
|
||||
- `zone_03_exit`
|
||||
|
||||
每个区域包含：
|
||||
|
||||
- 触发矩形。
|
||||
- 敌人刷出点。
|
||||
- 镜头锁定范围。
|
||||
- 清场后解锁出口。
|
||||
|
||||
第一版可以只画 debug 框，不立刻做敌人。
|
||||
|
||||
### Step 6：加入 debug 显示开关
|
||||
|
||||
需要能显示/隐藏：
|
||||
|
||||
- 碰撞矩形。
|
||||
- 玩家 hurtbox。
|
||||
- 攻击 hitbox。
|
||||
- 敌人出生点。
|
||||
- battle zone。
|
||||
|
||||
建议先用键盘 `F1` 切换。
|
||||
|
||||
## 7. 第一版验收标准
|
||||
|
||||
第一阶段完成时应该达到：
|
||||
|
||||
- 能启动 `Frostbite2DGame`。
|
||||
- 第一关宽度至少 2400 像素。
|
||||
- 玩家可以从起点跑到终点。
|
||||
- 至少 5 个平台/地面碰撞块。
|
||||
- 至少 2 层背景。
|
||||
- 至少 8 个装饰物。
|
||||
- 至少 3 个 battle zone debug 标记。
|
||||
- 场景资源路径集中在 `game/assets/stage/stage_01/`。
|
||||
- 文档记录已使用素材来源和授权信息。
|
||||
|
||||
## 8. 素材回来后的落地顺序
|
||||
|
||||
素材准备好后按这个顺序处理：
|
||||
|
||||
1. 整理素材到 `game/assets/stage/stage_01/`。
|
||||
2. 记录素材来源和授权。
|
||||
3. 先接背景图，验证相机移动。
|
||||
4. 再接地面/平台 tiles，验证碰撞对齐。
|
||||
5. 再接 props，丰富场景轮廓。
|
||||
6. 最后接 effects 和音频。
|
||||
|
||||
## 9. 下一轮建议任务
|
||||
|
||||
你找到素材后，下一轮优先做：
|
||||
|
||||
- 创建 `stage_01` 资源目录。
|
||||
- 新增 `StageRenderer`。
|
||||
- 扩展 `LevelDefinition`。
|
||||
- 把当前白盒平台替换成第一版 tile 视觉。
|
||||
- 保留 debug 碰撞显示。
|
||||
Reference in New Issue
Block a user