Split game module documentation
This commit is contained in:
@@ -0,0 +1,25 @@
|
||||
# Game Modules
|
||||
|
||||
本目录按游戏源码模块拆分说明文档。查具体代码时优先从这里进入；跨模块路线、阶段计划和验收流程仍放在 `../planning/`、`../game_skeleton.md` 和 `../scene_acceptance.md`。
|
||||
|
||||
## 模块索引
|
||||
|
||||
- `core_services.md`：游戏启动、`GameServices`、资源路径、基础配置。
|
||||
- `assets.md`：全局资源槽位、角色资源优先级、地图和 stage 资源落位。
|
||||
- `data_map.md`：`LevelDefinition`、`.map` 加载、地图数据格式。
|
||||
- `stage_rendering.md`：`StageRenderer`、场景分层、贴图/色块 fallback。
|
||||
- `scene_camera.md`：`WhiteboxScene`、摄像机跟随、battle zone 锁镜头。
|
||||
- `movement_collision.md`：`PlatformWorld`、`PlatformMover`、横版基础碰撞。
|
||||
- `actor_player.md`：`PlayerActor`、玩家状态、动画和音效触发。
|
||||
- `input.md`：`InputState`、PC/Switch 输入语义和后续配置计划。
|
||||
- `ui_overlay.md`：`GameUiOverlay`、`UIScene`、`TextSprite` 和 fallback UI。
|
||||
- `audio_save.md`：`GameAudio`、`GameSave`、音频 cue 和 debug 存档。
|
||||
- `debug_tools.md`：`DebugOverlay`、调试开关、可视化范围。
|
||||
- `combat.md`：当前 hitbox 预留和后续战斗模块拆分方向。
|
||||
|
||||
## 维护规则
|
||||
|
||||
- 新增源码模块时，同步新增或更新本目录对应文档。
|
||||
- 单个模块文档只写模块职责、入口文件、数据流、当前状态和下一步。
|
||||
- 跨模块验收结果写到 `../scene_acceptance.md`。
|
||||
- 长期计划写到 `../planning/`，不要塞进模块文档。
|
||||
@@ -0,0 +1,48 @@
|
||||
# Actor and Player
|
||||
|
||||
## 职责
|
||||
|
||||
Actor 模块负责游戏对象。当前已实现玩家，敌人、道具、投射物和特效后续按同样方式扩展。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/actor/player_actor.*`
|
||||
- `game/src/actor/player_animation_assets.*`
|
||||
- `game/src/combat/hitbox.h`
|
||||
|
||||
## `PlayerActor`
|
||||
|
||||
当前能力：
|
||||
|
||||
- 左右移动。
|
||||
- 跳跃。
|
||||
- 普通攻击触发。
|
||||
- idle/run/punch 三个临时状态。
|
||||
- 朝向翻转。
|
||||
- 基础平台碰撞。
|
||||
- 跳跃/攻击音效 cue。
|
||||
|
||||
## 动画资源
|
||||
|
||||
玩家动画加载顺序：
|
||||
|
||||
```text
|
||||
PVF .ani
|
||||
-> NPK IMG
|
||||
-> PNG spritesheet fallback
|
||||
```
|
||||
|
||||
如果使用 PVF `.ani`，由引擎 `Animation` 播放；如果回退 PNG，当前仍保留少量手写帧切换。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 还没有完整 ACT 状态机。
|
||||
- 攻击还没有命中判定。
|
||||
- 受击、击退、血量、硬直未接入。
|
||||
- PNG fallback 的帧数和帧时长仍在 C++ 中。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 把 idle/move/jump/attack/hit/dead 做成互斥状态机。
|
||||
- 从 `Animation::GetCurrentFrameInfo()` 接入 attack box / damage box。
|
||||
- 新增 `EnemyActor` 时复用 Actor、PlatformWorld 和动画资源加载链路。
|
||||
@@ -0,0 +1,58 @@
|
||||
# Assets
|
||||
|
||||
## 职责
|
||||
|
||||
资源模块定义游戏素材落位规则，让代码只引用稳定路径，不关心素材最终来自普通文件、PVF、NPK 还是 SoundPack。
|
||||
|
||||
主要文件：
|
||||
|
||||
- `game/assets/ASSETS.md`
|
||||
- `game/assets/stage/stage_01/ASSETS.md`
|
||||
- `game/src/core/asset_paths.h`
|
||||
- `game/src/data/stage_asset_slots.h`
|
||||
|
||||
## 全局资源槽位
|
||||
|
||||
当前已预留：
|
||||
|
||||
- `assets/fonts/`：UI/debug 字体。
|
||||
- `assets/sounds/`：直接读取的 wav 音效 fallback。
|
||||
- `assets/music/`：直接读取的 ogg 音乐 fallback。
|
||||
- `assets/audio/audio.xml`：音频 cue 表。
|
||||
- `assets/ImagePacks2/`：角色/场景 NPK 图片包。
|
||||
- `assets/SoundPacks/`：SoundPack 音频包。
|
||||
- `assets/Script.pvf`：PVF 脚本和动画资源。
|
||||
|
||||
## 角色资源优先级
|
||||
|
||||
玩家动画加载顺序：
|
||||
|
||||
```text
|
||||
PVF .ani
|
||||
-> NPK IMG
|
||||
-> PNG spritesheet fallback
|
||||
```
|
||||
|
||||
当前 PNG fallback 已能运行；正式素材到位后，优先把 `.ani` 和 `.img` 放到 `asset_paths.h` 约定的路径。
|
||||
|
||||
## Stage 资源
|
||||
|
||||
第一关资源放在：
|
||||
|
||||
```text
|
||||
game/assets/stage/stage_01/
|
||||
```
|
||||
|
||||
目录职责：
|
||||
|
||||
- `background/`：远景、中景背景。
|
||||
- `tiles/`：地面、平台、墙体 tileset。
|
||||
- `props/`：后景/前景装饰。
|
||||
- `effects/`：场景特效。
|
||||
- `audio/`：关卡局部音频素材。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 素材到位后先更新 `ASSETS.md` 的来源和授权。
|
||||
- 地图 tile 化后，把 tileset 路径写入 `.map` 数据。
|
||||
- 如果素材进入 NPK，补 stage layer 的 NPK sprite path 支持。
|
||||
@@ -0,0 +1,53 @@
|
||||
# Audio and Save
|
||||
|
||||
## 职责
|
||||
|
||||
音频和存档模块负责调用引擎已有 `Sound`、`Music`、`AudioDatabase` 和 `SaveSystem`。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/core/game_audio.*`
|
||||
- `game/src/core/game_save.*`
|
||||
- `game/src/core/game_services.*`
|
||||
|
||||
## 音频
|
||||
|
||||
`GameAudio` 支持：
|
||||
|
||||
- `PlaySoundCue(cueId)`
|
||||
- `PlayMusicCue(cueId)`
|
||||
|
||||
路径解析优先级：
|
||||
|
||||
```text
|
||||
AudioDatabase cue
|
||||
-> assets/sounds/<cue>.wav
|
||||
-> assets/music/<cue>.ogg
|
||||
```
|
||||
|
||||
当前已接入 cue：
|
||||
|
||||
- `stage_01`
|
||||
- `player_jump`
|
||||
- `player_attack`
|
||||
- `battle_zone_enter`
|
||||
|
||||
缺音频资源时直接跳过，不影响场景运行。
|
||||
|
||||
## 存档
|
||||
|
||||
`GameSave` 当前用 `SaveSystem` slot `0` 保存 debug overlay 开关。
|
||||
|
||||
保存内容：
|
||||
|
||||
- debug 总开关。
|
||||
- 碰撞/网格显示。
|
||||
- 玩家包围盒。
|
||||
- battle zone/camera bounds。
|
||||
- spawn point。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 正式设置、进度、角色成长继续走 `SaveSystem`。
|
||||
- 正式音频资源到位后补 `assets/audio/audio.xml`。
|
||||
- 根据 Switch 实机行为确认 save root 和权限。
|
||||
@@ -0,0 +1,47 @@
|
||||
# Combat
|
||||
|
||||
## 职责
|
||||
|
||||
战斗模块负责攻击、命中、受击、伤害、击退和状态互斥。当前只做了最小预留，还未进入正式玩法实现。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/combat/hitbox.h`
|
||||
- `game/src/actor/player_actor.*`
|
||||
|
||||
## 当前状态
|
||||
|
||||
已有：
|
||||
|
||||
- 玩家攻击输入。
|
||||
- punch 动画状态。
|
||||
- 攻击音效 cue。
|
||||
- `hitbox.h` 预留。
|
||||
|
||||
未完成：
|
||||
|
||||
- 攻击 hitbox。
|
||||
- hurtbox。
|
||||
- 命中检测。
|
||||
- 伤害数值。
|
||||
- 受击硬直。
|
||||
- 击退。
|
||||
- 血量。
|
||||
- 怪物受击和死亡。
|
||||
|
||||
## 后续拆分建议
|
||||
|
||||
优先保持轻量，不急着做复杂战斗框架：
|
||||
|
||||
- `HitboxComponent`：攻击框、受击框。
|
||||
- `CombatStats`：血量、伤害、防御等固定数值。
|
||||
- `CombatResolver`：命中判定和伤害结算。
|
||||
- `HitReaction`：硬直、击退、受伤状态。
|
||||
|
||||
## 接入顺序
|
||||
|
||||
1. 从玩家 punch 状态产生一帧或多帧 hitbox。
|
||||
2. DebugOverlay 显示 hitbox/hurtbox。
|
||||
3. 新增一个最小 `EnemyActor`。
|
||||
4. 完成玩家攻击命中敌人的闭环。
|
||||
5. 再接 battle zone 清场。
|
||||
@@ -0,0 +1,45 @@
|
||||
# Core Services
|
||||
|
||||
## 职责
|
||||
|
||||
核心模块负责游戏启动后的基础服务接入，不承载具体玩法逻辑。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/main.cpp`
|
||||
- `game/src/core/game_config.h`
|
||||
- `game/src/core/game_services.*`
|
||||
- `game/src/core/asset_paths.h`
|
||||
- `game/src/core/debug_flags.h`
|
||||
|
||||
## 当前接入
|
||||
|
||||
`Application::init()` 由引擎负责初始化：
|
||||
|
||||
- `Asset` 工作目录和资源路径。
|
||||
- `SaveSystem`。
|
||||
- SDL video/events/controller。
|
||||
- Window、Renderer、Camera。
|
||||
- PixelArt2D 渲染风格和虚拟分辨率。
|
||||
- `TaskSystem`。
|
||||
|
||||
`GameServices` 只做项目级可选服务：
|
||||
|
||||
- 初始化 `AudioSystem`。
|
||||
- 初始化 `FontManager`，尝试注册 `debug` 字体。
|
||||
- 探测并打开 `Script.pvf`。
|
||||
- 初始化 `NpkArchive`。
|
||||
- 初始化 `SoundPackArchive`。
|
||||
- 探测并加载 `AudioDatabase`。
|
||||
- 记录 `SaveSystem` 状态。
|
||||
|
||||
## 运行原则
|
||||
|
||||
- 缺少 PVF、NPK、SoundPack、字体或音频表时，游戏必须继续启动。
|
||||
- 游戏层只记录服务状态，不重新实现引擎服务。
|
||||
- Windows 和 Switch 通过同一个 `main.cpp` 入口进入游戏，平台差异放在编译分支和引擎平台层。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加项目级日志分类，区分资源、地图、输入、场景和战斗。
|
||||
- 将 debug/service 状态接入更完整的调试面板。
|
||||
@@ -0,0 +1,66 @@
|
||||
# Data and Map
|
||||
|
||||
## 职责
|
||||
|
||||
数据模块负责把外部关卡数据转换成游戏运行时使用的 `LevelDefinition`。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/data/level_definition.h`
|
||||
- `game/src/data/stage_map_resource.*`
|
||||
- `game/src/data/stage_map_loader.*`
|
||||
- `game/src/data/whitebox_level.cpp`
|
||||
- `game/assets/map/stage_01.map`
|
||||
|
||||
## 数据流
|
||||
|
||||
```text
|
||||
stage_01.map
|
||||
-> StageMapResource
|
||||
-> StageMapLoader
|
||||
-> LevelDefinition
|
||||
-> WhiteboxScene / StageRenderer / DebugOverlay
|
||||
```
|
||||
|
||||
读取优先级：
|
||||
|
||||
1. `Asset` 普通文本资源：`map/stage_01.map`
|
||||
2. `Asset` fallback：`assets/map/stage_01.map`
|
||||
3. `PvfArchive` 二进制脚本：`map/stage_01.map`
|
||||
4. `PvfArchive` 文本内容：`map/stage_01.map`
|
||||
|
||||
## `LevelDefinition`
|
||||
|
||||
当前包含：
|
||||
|
||||
- 世界宽高。
|
||||
- 玩家出生点。
|
||||
- 摄像机边界。
|
||||
- 平台碰撞世界。
|
||||
- 场景视觉层。
|
||||
- battle zone。
|
||||
- enemy spawn point。
|
||||
|
||||
## `.map` 当前命令
|
||||
|
||||
```text
|
||||
map <id>
|
||||
world <width> <height>
|
||||
camera <x> <y> <width> <height>
|
||||
player_spawn <x> <y>
|
||||
collision <x> <y> <width> <height>
|
||||
layer <id> <BackgroundFar|BackgroundMid|LevelVisual|PropsBack|PropsFront> <parallax>
|
||||
rect <x> <y> <width> <height> <r> <g> <b> <a>
|
||||
rect_sprite <x> <y> <width> <height> <r> <g> <b> <a> <texture>
|
||||
rect_sprite_src <x> <y> <width> <height> <r> <g> <b> <a> <texture> <sx> <sy> <sw> <sh>
|
||||
endlayer
|
||||
battle_zone <id> <trigger_x> <trigger_y> <trigger_w> <trigger_h> <camera_x> <camera_y> <camera_w> <camera_h>
|
||||
spawn <id> <x> <y>
|
||||
endbattle_zone
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 给 `.map` 增加 tileset/tile entry。
|
||||
- 增加重复 block、空 layer、battle zone 无 spawn、tile 引用不存在等错误日志。
|
||||
- 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。
|
||||
@@ -0,0 +1,38 @@
|
||||
# Debug Tools
|
||||
|
||||
## 职责
|
||||
|
||||
调试模块负责白盒/灰盒阶段的可视化和开发开关。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/debug/debug_overlay.*`
|
||||
- `game/src/core/debug_flags.h`
|
||||
- `game/docs/controls.md`
|
||||
|
||||
## 当前显示项
|
||||
|
||||
- 场景碰撞。
|
||||
- 场景网格。
|
||||
- 玩家包围盒。
|
||||
- battle zone 触发框。
|
||||
- battle zone camera bounds。
|
||||
- enemy spawn point。
|
||||
|
||||
## 快捷键
|
||||
|
||||
快捷键统一维护在 `../controls.md`。
|
||||
|
||||
当前 debug 开关会通过 `GameSave` 保存，下次启动后恢复。
|
||||
|
||||
## 约束
|
||||
|
||||
- 调试绘制继续使用引擎 `Renderer::drawQuad`。
|
||||
- 不单独实现 debug render backend。
|
||||
- 正式版本需要能关闭或剥离开发快捷键。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加输入状态显示。
|
||||
- 增加 hitbox/hurtbox 显示。
|
||||
- 增加地图加载错误和资源缺失提示面板。
|
||||
@@ -0,0 +1,34 @@
|
||||
# Input
|
||||
|
||||
## 职责
|
||||
|
||||
输入模块负责把 PC、SDL 手柄和 Switch 输入统一成游戏语义。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/core/input_state.*`
|
||||
- `game/docs/controls.md`
|
||||
|
||||
## 当前语义
|
||||
|
||||
`InputState` 只暴露游戏需要的动作：
|
||||
|
||||
- `moveX`：水平输入，范围 `-1.0` 到 `1.0`。
|
||||
- `jumpPressed`：跳跃按下瞬间。
|
||||
- `attackPressed`：攻击按下瞬间。
|
||||
|
||||
## 当前映射
|
||||
|
||||
详细按键见 `../controls.md`。
|
||||
|
||||
原则：
|
||||
|
||||
- 角色逻辑只消费 `InputState`。
|
||||
- PC/Switch 差异只存在于 `InputStateProvider`。
|
||||
- 跳跃和攻击使用“按下瞬间”，避免长按每帧触发。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加 `InputConfig`，并通过 `Asset` 或 PVF 读取。
|
||||
- 分离 gameplay 输入和 debug 输入。
|
||||
- 增加输入状态 debug 显示。
|
||||
@@ -0,0 +1,42 @@
|
||||
# Movement and Collision
|
||||
|
||||
## 职责
|
||||
|
||||
移动碰撞模块负责横版基础移动和平台碰撞，是玩家、敌人和可移动物体共用的底层玩法能力。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/movement/platform_world.*`
|
||||
- `game/src/data/level_definition.h`
|
||||
- `game/src/actor/player_actor.*`
|
||||
|
||||
## 当前能力
|
||||
|
||||
- 地面和平台矩形碰撞。
|
||||
- 重力。
|
||||
- 水平移动。
|
||||
- 落地检测。
|
||||
- 防止玩家穿过平台。
|
||||
- 平台数据来自 `LevelDefinition::collision`。
|
||||
|
||||
## 当前使用方式
|
||||
|
||||
`WhiteboxScene` 把关卡碰撞世界传给 `PlayerActor`：
|
||||
|
||||
```text
|
||||
LevelDefinition.collision -> PlayerActor::SetMovementWorld()
|
||||
```
|
||||
|
||||
`PlayerActor` 只提交移动意图，最终位置由 `PlatformMover` 约束。
|
||||
|
||||
## 约束
|
||||
|
||||
- 碰撞数据和视觉数据分离。
|
||||
- 不让 `StageRenderer` 反推碰撞。
|
||||
- 后续敌人也应复用 `PlatformWorld`，不要另写一套地形碰撞。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加墙体/左右边界碰撞语义。
|
||||
- 增加防卡地形和异常状态重置。
|
||||
- 扩展成可服务敌人 AI 的移动查询接口。
|
||||
@@ -0,0 +1,51 @@
|
||||
# Scene and Camera
|
||||
|
||||
## 职责
|
||||
|
||||
场景模块负责局内生命周期、关卡装配、摄像机和 battle zone 流程。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/scene/whitebox_scene.*`
|
||||
- `game/src/scene/camera_controller.*`
|
||||
|
||||
## `WhiteboxScene`
|
||||
|
||||
当前负责：
|
||||
|
||||
- 加载 `LevelDefinition`。
|
||||
- 创建玩家。
|
||||
- 配置摄像机。
|
||||
- 驱动 battle zone 状态。
|
||||
- 调用 `StageRenderer`。
|
||||
- 调用 `DebugOverlay`。
|
||||
- 推入 `GameUiOverlay`。
|
||||
- 播放关卡 BGM 和 battle zone 进入音效。
|
||||
- 保存 debug 开关。
|
||||
|
||||
## 摄像机
|
||||
|
||||
`CameraController` 当前支持：
|
||||
|
||||
- 玩家横向跟随。
|
||||
- dead zone。
|
||||
- 平滑移动。
|
||||
- 世界边界 clamp。
|
||||
- battle zone 临时 camera bounds。
|
||||
|
||||
进入/离开 battle zone 时，camera bounds 通过短过渡平滑切换，避免硬切瞬移。
|
||||
|
||||
## Battle Zone
|
||||
|
||||
当前 battle zone 还是场景骨架阶段：
|
||||
|
||||
- 玩家进入触发区后激活。
|
||||
- 摄像机锁定到 zone camera bounds。
|
||||
- `F2` debug 清场后解除锁定。
|
||||
- enemy spawn point 只做 debug 显示，暂不刷敌。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 用敌人清空结果替代 `F2` debug 清场。
|
||||
- 给 battle zone 增加入口/出口锁定数据。
|
||||
- 把场景切换、重置、加载/卸载流程独立成 SceneFlow 模块。
|
||||
@@ -0,0 +1,46 @@
|
||||
# Stage Rendering
|
||||
|
||||
## 职责
|
||||
|
||||
Stage 渲染模块负责把 `LevelDefinition` 的视觉层画出来，不处理玩法规则。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/stage/stage_renderer.*`
|
||||
- `game/src/data/level_definition.h`
|
||||
|
||||
## 当前分层
|
||||
|
||||
```text
|
||||
BackgroundFar
|
||||
BackgroundMid
|
||||
LevelVisual
|
||||
PropsBack
|
||||
Actors
|
||||
PropsFront
|
||||
UI
|
||||
```
|
||||
|
||||
`StageRenderer::Render()` 绘制 actor 之前的层；`RenderForeground()` 绘制 actor 之后的前景遮挡层。
|
||||
|
||||
## 当前能力
|
||||
|
||||
- 支持背景色。
|
||||
- 支持远景/中景/地面/平台/props 分层。
|
||||
- 支持 parallax。
|
||||
- 支持色块占位。
|
||||
- 支持普通 PNG texture path。
|
||||
- 支持 source rect。
|
||||
- 资源缺失时回退色块，不阻断场景运行。
|
||||
|
||||
## 约束
|
||||
|
||||
- 渲染继续使用引擎 `Renderer`。
|
||||
- `StageRenderer` 不直接解析 `.map`。
|
||||
- 碰撞和视觉分离，视觉 tile 不直接决定碰撞。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加 tile entry 绘制路径。
|
||||
- 把 `level_visual` 长色块逐步替换为 tile。
|
||||
- 如果引擎提供统一 Texture cache，再迁移当前局部贴图缓存。
|
||||
@@ -0,0 +1,38 @@
|
||||
# UI Overlay
|
||||
|
||||
## 职责
|
||||
|
||||
UI 模块负责局内 HUD、状态显示和调试面板。当前只有最小 overlay。
|
||||
|
||||
主要源码：
|
||||
|
||||
- `game/src/ui/game_ui_overlay.*`
|
||||
|
||||
## 当前能力
|
||||
|
||||
`GameUiOverlay` 继承引擎 `UIScene`，通过 `SceneManager` 进入 UI scene stack。
|
||||
|
||||
有字体时：
|
||||
|
||||
- 使用 `TextSprite` 显示游戏状态。
|
||||
- 显示 debug 状态、battle zone、音频、存档、PVF、NPK、AudioDB 状态。
|
||||
|
||||
缺字体时：
|
||||
|
||||
- 使用 `Renderer::drawQuad` 画 fallback 色条。
|
||||
- 不因字体缺失阻断 PC/Switch 启动。
|
||||
|
||||
## 资源
|
||||
|
||||
字体候选：
|
||||
|
||||
```text
|
||||
assets/fonts/debug.ttf
|
||||
assets/fonts/ui.ttf
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 增加血量、连击、联机状态等 gameplay HUD。
|
||||
- 增加 debug 面板，替代部分 F 键调试。
|
||||
- 确认 Switch 字体资源进入 RomFS 后再启用正式文字 UI。
|
||||
Reference in New Issue
Block a user