docs: 添加Frostbite2D开发文档
添加详细的Frostbite2D引擎开发文档，包含仓库结构、构建运行说明、核心架构、资源系统、事件系统等内容，为维护者和协作开发者提供快速入门指南
This commit is contained in:
648
docs/开发文档.md
Normal file
648
docs/开发文档.md
Normal file
@@ -0,0 +1,648 @@
|
||||
# Frostbite2D 开发文档
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
这份文档面向 Frostbite2D 的维护者和协作开发者，目标是帮助你快速理解仓库结构、运行主线、模块职责、资源链路和当前开发约定。
|
||||
|
||||
仓库目前由两部分组成：
|
||||
|
||||
- `Frostbite2D/`：引擎核心代码与公开头文件。
|
||||
- `Game/`：示例入口与资源目录，用来验证引擎能力和联调内容管线。
|
||||
|
||||
当前项目更像“引擎 + 集成示例”的单仓库结构，而不是严格拆分的引擎库/游戏仓库。
|
||||
|
||||
## 2. 仓库结构
|
||||
|
||||
### 2.1 顶层目录
|
||||
|
||||
```text
|
||||
Frostbite2D/
|
||||
├─ Frostbite2D/ # 引擎源码与头文件
|
||||
├─ Game/ # 示例程序与资源
|
||||
├─ platform/ # XMake 平台配置
|
||||
├─ docs/ # 项目文档
|
||||
├─ xmake.lua # 根构建入口
|
||||
└─ README.md # 项目简介
|
||||
```
|
||||
|
||||
### 2.2 引擎目录分层
|
||||
|
||||
```text
|
||||
Frostbite2D/
|
||||
├─ include/frostbite2D/
|
||||
│ ├─ 2d/ # Actor、Sprite、TextSprite 等 2D 对象
|
||||
│ ├─ animation/ # 动画数据与播放对象
|
||||
│ ├─ audio/ # 音频系统与音频资源
|
||||
│ ├─ base/ # RefObject、RefPtr、对象注册
|
||||
│ ├─ core/ # Application、Window
|
||||
│ ├─ event/ # 输入/窗口事件定义
|
||||
│ ├─ graphics/ # Renderer、Batch、Camera、Texture、Shader
|
||||
│ ├─ platform/ # 平台相关接口
|
||||
│ ├─ resource/ # Asset、NPK/PVF/SoundPack 等资源系统
|
||||
│ ├─ scene/ # Scene、SceneManager
|
||||
│ ├─ script/ # SquirrelVM
|
||||
│ ├─ types/ # 数学类型、颜色、UUID、别名
|
||||
│ └─ utils/ # 通用工具
|
||||
└─ src/frostbite2D/ # 对应实现
|
||||
```
|
||||
|
||||
### 2.3 示例层目录
|
||||
|
||||
- `Game/src/main.cpp`：当前主入口，也是理解引擎接入方式的最佳起点。
|
||||
- `Game/assets/`：示例资源，包括字体、着色器、图片、音频、脚本、NPK/PVF 相关内容。
|
||||
|
||||
## 3. 构建与运行
|
||||
|
||||
## 3.1 构建系统
|
||||
|
||||
项目使用 XMake，根入口在 `xmake.lua`。根脚本只负责：
|
||||
|
||||
- 设置项目名、版本、编码和语言标准；
|
||||
- 根据 `plat` 选择 `platform/<target>.lua`；
|
||||
- 将平台相关依赖、工具链和构建规则下放到平台脚本。
|
||||
|
||||
当前已配置的平台脚本：
|
||||
|
||||
- `platform/mingw.lua`
|
||||
- `platform/linux.lua`
|
||||
- `platform/switch.lua`
|
||||
|
||||
Windows 平台最终会映射到 `mingw` 配置。
|
||||
|
||||
## 3.2 常用命令
|
||||
|
||||
```bash
|
||||
xmake build
|
||||
xmake clean
|
||||
xmake build -m debug
|
||||
xmake build -m release
|
||||
xmake build -p windows
|
||||
xmake build -p linux
|
||||
xmake build -p switch
|
||||
```
|
||||
|
||||
查看当前配置：
|
||||
|
||||
```bash
|
||||
xmake f -c
|
||||
```
|
||||
|
||||
## 3.3 依赖概览
|
||||
|
||||
从平台脚本看，当前主要依赖包括：
|
||||
|
||||
- SDL2
|
||||
- SDL2_image
|
||||
- SDL2_mixer
|
||||
- SDL2_ttf
|
||||
- GLM
|
||||
- zlib
|
||||
- Squirrel
|
||||
- Glad（源码随仓库提供）
|
||||
|
||||
Nintendo Switch 平台使用 devkitPro/libnx/portlibs 工具链与库。
|
||||
|
||||
## 3.4 构建产物与资源复制
|
||||
|
||||
`mingw` 和 `linux` 平台都会在构建后执行 `after_build`：
|
||||
|
||||
- 复制 `Game/assets` 到目标输出目录下的 `assets/`；
|
||||
- Windows 额外尝试复制 SDL 及相关动态库；
|
||||
- Switch 平台还会生成 `nro` 相关产物，并复制 `assets`。
|
||||
|
||||
这意味着示例程序默认依赖“输出目录旁边有 `assets/`”这一约定。
|
||||
|
||||
## 3.5 运行与验证
|
||||
|
||||
仓库当前没有自动化测试框架，验证方式以手动运行构建产物为主。
|
||||
|
||||
建议的最小验证流程：
|
||||
|
||||
1. `xmake build`
|
||||
2. 运行生成的二进制
|
||||
3. 观察窗口是否正常创建
|
||||
4. 观察字体、精灵、动画是否正常显示
|
||||
5. 观察脚本、资源包、输入事件日志是否符合预期
|
||||
|
||||
## 4. 启动流程总览
|
||||
|
||||
当前主入口位于 `Game/src/main.cpp`，可以把启动过程概括为：
|
||||
|
||||
1. 创建 `AppConfig`
|
||||
2. 初始化 `Application`
|
||||
3. 初始化脚本系统和资源归档
|
||||
4. 创建场景并压入 `SceneManager`
|
||||
5. 创建文本、动画、精灵、测试 Actor
|
||||
6. 调用 `Application::run()`
|
||||
7. 退出时调用 `Application::shutdown()`
|
||||
|
||||
一个简化后的运行主线如下：
|
||||
|
||||
```text
|
||||
main
|
||||
-> Application::init
|
||||
-> 平台初始化
|
||||
-> initCoreModules
|
||||
-> Asset 工作目录
|
||||
-> SDL 初始化
|
||||
-> Window 创建
|
||||
-> Renderer 初始化
|
||||
-> Camera 创建并绑定 Renderer
|
||||
-> 初始化 SquirrelVM / PvfArchive / NpkArchive / FontManager
|
||||
-> SceneManager::PushScene
|
||||
-> 创建 Sprite / TextSprite / Animation / Actor
|
||||
-> Application::run
|
||||
-> 可选执行 SquirrelVM::run
|
||||
-> 主循环
|
||||
-> SDL_PollEvent
|
||||
-> SDL 事件转换为引擎事件
|
||||
-> SceneManager::Update
|
||||
-> SceneManager::Render
|
||||
-> Window::swap
|
||||
-> Application::shutdown
|
||||
```
|
||||
|
||||
## 5. 核心架构
|
||||
|
||||
## 5.1 Application
|
||||
|
||||
`Application` 是运行时总控单例，职责包括：
|
||||
|
||||
- 保存 `AppConfig`；
|
||||
- 初始化平台与核心模块；
|
||||
- 维护主循环状态；
|
||||
- 计算 `deltaTime`、总运行时间和 FPS；
|
||||
- 从 SDL 轮询事件并转换成 Frostbite2D 事件；
|
||||
- 将更新和渲染委托给 `SceneManager`；
|
||||
- 在退出时按顺序释放场景、渲染器、音频和资源归档。
|
||||
|
||||
关键接口：
|
||||
|
||||
- `Application::get()`
|
||||
- `init()` / `init(const AppConfig&)`
|
||||
- `run()`
|
||||
- `quit()`
|
||||
- `shutdown()`
|
||||
- `getWindow()`
|
||||
- `getRenderer()`
|
||||
- `deltaTime()`
|
||||
- `fps()`
|
||||
|
||||
需要注意的实现细节：
|
||||
|
||||
- `initCoreModules()` 内部会先设置 `Asset` 工作目录，再做 SDL/窗口/渲染器初始化。
|
||||
- `run()` 会在主循环前检查 `SquirrelVM` 是否已初始化，如果已初始化则先执行 `SquirrelVM::run()`。
|
||||
- `shutdown()` 中会清空场景栈、关闭渲染器、关闭音频系统、关闭归档系统，然后销毁窗口。
|
||||
|
||||
## 5.2 Window
|
||||
|
||||
`Window` 是 SDL 窗口与 OpenGL 上下文的包装层，负责：
|
||||
|
||||
- 创建/销毁窗口；
|
||||
- 交换缓冲区；
|
||||
- 设置标题、大小、位置、全屏和 VSync；
|
||||
- 管理光标状态；
|
||||
- 暴露 resize/close/focus 回调。
|
||||
|
||||
窗口配置由 `WindowConfig` 提供，常用字段包括：
|
||||
|
||||
- `width`
|
||||
- `height`
|
||||
- `title`
|
||||
- `resizable`
|
||||
- `fullscreen`
|
||||
- `multisamples`
|
||||
- `vsync`
|
||||
|
||||
当前 `Application` 在窗口尺寸变化时会同步更新：
|
||||
|
||||
- `Renderer::setViewport`
|
||||
- `Camera::setViewport`
|
||||
|
||||
## 5.3 Renderer / Camera / Batch
|
||||
|
||||
渲染子系统由 `Renderer` 统一对外，内部组合了：
|
||||
|
||||
- `ShaderManager`
|
||||
- `Batch`
|
||||
- `Camera`
|
||||
|
||||
`Renderer` 当前职责：
|
||||
|
||||
- 初始化渲染状态；
|
||||
- 控制帧开始/结束；
|
||||
- 设置清屏色和视口；
|
||||
- 绑定相机；
|
||||
- 提供 `drawQuad`、`drawSprite` 等基础绘制接口；
|
||||
- 在合适时机 `flush()` 批处理。
|
||||
|
||||
`Camera` 当前由 `Application` 创建并设置到 `Renderer`。初始化时会：
|
||||
|
||||
- 设置视口尺寸；
|
||||
- 打开 `flipY`，使 `(0, 0)` 更符合 2D 左上角坐标习惯。
|
||||
|
||||
## 5.4 SceneManager / Scene
|
||||
|
||||
场景系统采用栈式管理：
|
||||
|
||||
- `PushScene`：旧场景 `onExit()`，新场景入栈后 `onEnter()`
|
||||
- `PopScene`：当前场景 `onExit()` 后弹出，若还有上层场景则重新 `onEnter()`
|
||||
- `ReplaceScene`：本质上是 `PopScene() + PushScene()`
|
||||
- `ClearAll`：退出时清空所有场景
|
||||
|
||||
更新和渲染只作用于栈顶场景：
|
||||
|
||||
- `SceneManager::Update(deltaTime)`
|
||||
- `SceneManager::Render()`
|
||||
|
||||
`Scene` 继承自 `Actor`，默认行为很薄：
|
||||
|
||||
- `Update()` 直接更新子节点
|
||||
- `Render()` 直接渲染子节点
|
||||
- `OnEvent()` 先处理自身，再向子节点分发
|
||||
|
||||
## 5.5 Actor 树
|
||||
|
||||
`Actor` 是 2D 对象树的基础节点，也是当前最重要的扩展点之一。
|
||||
|
||||
核心能力包括：
|
||||
|
||||
- 父子层级管理：`AddChild` / `RemoveChild`
|
||||
- 变换管理：位置、旋转、缩放、尺寸、锚点
|
||||
- 世界变换缓存：懒更新 `localTransform_` / `worldTransform_`
|
||||
- 可见性与透明度控制
|
||||
- `zOrder` 排序插入
|
||||
- 事件监听与派发
|
||||
- UUID 注册到 `ObjectRegistry`
|
||||
|
||||
当前节点树是更新/渲染/事件分发的基础：
|
||||
|
||||
- `UpdateChildren()` 只更新可见子节点
|
||||
- `RenderChildren()` 只渲染可见子节点
|
||||
- `SetZOrder()` 会触发父节点内重新插入排序
|
||||
|
||||
需要注意：
|
||||
|
||||
- `Scene` 也是 `Actor`，所以场景本身就是树根节点。
|
||||
- `AddChild()` 时会把子节点的 `scene_` 设为当前节点的 `scene_`。
|
||||
- `markTransformDirty()` 会递归标脏所有子节点。
|
||||
|
||||
## 6. 事件系统
|
||||
|
||||
## 6.1 SDL 到引擎事件
|
||||
|
||||
`Application::convertSDLEvent()` 负责把 SDL 事件转换为引擎事件对象。当前已覆盖：
|
||||
|
||||
- 窗口事件：关闭、尺寸变化、焦点变化、最小化、最大化、恢复
|
||||
- 键盘事件：按下、抬起、文本输入
|
||||
- 鼠标事件：移动、按键、滚轮
|
||||
- 触摸事件
|
||||
- 手柄事件：按钮与摇杆轴
|
||||
|
||||
转换完成后，`Application::dispatchEvent()` 会把事件交给当前场景：
|
||||
|
||||
```text
|
||||
SDL_Event -> Event -> CurrentScene->OnEvent()
|
||||
```
|
||||
|
||||
## 6.2 Actor 事件处理模型
|
||||
|
||||
`Actor` 提供两类事件扩展方式：
|
||||
|
||||
- 注册监听器：`AddEventListener(EventType, callback)`
|
||||
- 继承覆写：`OnKeyDown`、`OnMouseDown`、`OnJoystickAxis` 等虚函数
|
||||
|
||||
事件是否会进入某个节点，取决于：
|
||||
|
||||
- 是否启用了 `EnableEventReceive()`
|
||||
- 是否启用了 `EnableEventIntercept()`
|
||||
- 当前场景对子节点按 `eventPriority` 排序后的分发结果
|
||||
|
||||
当前分发规则大致为：
|
||||
|
||||
- `Scene::OnEvent()` 先尝试自身处理；
|
||||
- 再筛选启用了事件接收的子节点；
|
||||
- 根据 `eventPriority` 排序；
|
||||
- 开启拦截的节点直接 `OnEvent()`；
|
||||
- 未开启拦截的节点通过 `DispatchEvent()` 递归向下派发。
|
||||
|
||||
这一套模型适合做 UI 控件、输入代理、全局拦截节点等。
|
||||
|
||||
## 7. 资源系统
|
||||
|
||||
## 7.1 Asset
|
||||
|
||||
`Asset` 是底层文件系统包装器，主要职责：
|
||||
|
||||
- 维护工作目录与资源根目录；
|
||||
- 处理路径拼接、规范化和绝对路径解析；
|
||||
- 提供文本/二进制文件读写；
|
||||
- 提供目录创建、删除、遍历；
|
||||
- 提供文件信息、扩展名、父路径等辅助能力。
|
||||
|
||||
运行时最关键的约定是：
|
||||
|
||||
- `Application::initCoreModules()` 会把 `SDL_GetBasePath()` 作为默认工作目录；
|
||||
- 构建后 `assets/` 会被复制到输出目录；
|
||||
- 因此多数相对路径资源访问都会基于运行产物目录工作。
|
||||
|
||||
如果资源定位异常，优先检查：
|
||||
|
||||
1. 构建输出目录下是否存在 `assets/`
|
||||
2. `Asset` 当前工作目录是否符合预期
|
||||
3. 平台差异下路径分隔符或编码问题是否被绕开
|
||||
|
||||
## 7.2 NpkArchive
|
||||
|
||||
`NpkArchive` 面向图片包资源，当前示例中通过：
|
||||
|
||||
```cpp
|
||||
NpkArchive::get().setImagePackDirectory("assets/ImagePacks2");
|
||||
NpkArchive::get().setDefaultImg("sprite/interface/base.img", 0);
|
||||
NpkArchive::get().init();
|
||||
```
|
||||
|
||||
可以把它理解为“图像资源索引与缓存层”，当前职责包括：
|
||||
|
||||
- 扫描 NPK 文件；
|
||||
- 解析 img 引用；
|
||||
- 根据帧索引取图像帧；
|
||||
- 管理缓存大小与驱逐逻辑；
|
||||
- 提供默认 img 回退。
|
||||
|
||||
`Sprite::createFromNpk()` 依赖这套系统工作。
|
||||
|
||||
## 7.3 PvfArchive
|
||||
|
||||
`PvfArchive` 面向 PVF 资源包，当前职责包括：
|
||||
|
||||
- 打开 PVF 文件；
|
||||
- 解析头部并建立文件索引；
|
||||
- 加载 `stringtable.bin`；
|
||||
- 加载 `n_string.lst`；
|
||||
- 提供文件内容、原始字节和字符串查询能力；
|
||||
- 为脚本解析、动画数据读取等模块提供底层数据。
|
||||
|
||||
示例初始化方式：
|
||||
|
||||
```cpp
|
||||
auto& pvf = PvfArchive::get();
|
||||
if (pvf.open("assets/Script.pvf")) {
|
||||
pvf.init();
|
||||
}
|
||||
```
|
||||
|
||||
当前动画系统和脚本解析系统都依赖 PVF。
|
||||
|
||||
## 7.4 ScriptParser
|
||||
|
||||
`ScriptParser` 用于解析 PVF 中的二进制脚本数据，支持：
|
||||
|
||||
- 从 `RawData` 或字节数组构造；
|
||||
- 顺序读取值；
|
||||
- 回退一个指令；
|
||||
- 一次性 `parseAll()`；
|
||||
- 根据 PVF 字符串表进行解码。
|
||||
|
||||
它更像“底层解析器”，通常不会直接在游戏逻辑层大范围使用，而是作为资源模块或工具模块的实现基础。
|
||||
|
||||
## 7.5 SoundPackArchive / AudioDatabase
|
||||
|
||||
音频资源目前分成两层：
|
||||
|
||||
- `SoundPackArchive`：面向音频包内容；
|
||||
- `AudioDatabase`：面向 `audio.xml` 这种逻辑名到文件路径的映射。
|
||||
|
||||
`Game/src/main.cpp` 中已经保留了典型接入方式，但部分代码仍处于注释状态，说明这部分还在联调或验证阶段。
|
||||
|
||||
## 8. 图形与内容对象
|
||||
|
||||
## 8.1 Sprite
|
||||
|
||||
`Sprite` 是最基础的图形节点之一，当前至少支持两种常见来源：
|
||||
|
||||
- 从普通文件创建
|
||||
- 从 NPK 资源创建
|
||||
|
||||
典型流程：
|
||||
|
||||
```cpp
|
||||
auto sprite = Sprite::createFromNpk("sprite/newtitle/nangua.img", 0);
|
||||
if (sprite) {
|
||||
sprite->SetPosition(220, 10);
|
||||
scene->AddChild(sprite);
|
||||
}
|
||||
```
|
||||
|
||||
它继承自 `Actor`，因此天然具备层级、变换、透明度和事件能力。
|
||||
|
||||
## 8.2 TextSprite / FontManager
|
||||
|
||||
文字显示由 `TextSprite` 与 `FontManager` 协作完成，当前流程是：
|
||||
|
||||
1. `FontManager::init()`
|
||||
2. `registerFont(name, path, size)`
|
||||
3. `TextSprite::create(text, fontName)`
|
||||
4. 设置颜色、位置等属性
|
||||
5. 加入场景树
|
||||
|
||||
示例中已经验证：
|
||||
|
||||
- 字体从 `assets/Fonts/` 加载
|
||||
- 中文文本可以进入显示链路
|
||||
|
||||
## 8.3 Animation / AnimationData
|
||||
|
||||
动画系统当前与 PVF 资源紧密耦合。示例中通过：
|
||||
|
||||
```cpp
|
||||
auto ani = MakePtr<Animation>(
|
||||
"monster/event/bluemarble/goblin/animation_goblin2/move.ani");
|
||||
```
|
||||
|
||||
可以推断当前能力包括：
|
||||
|
||||
- 从 PVF 路径解析 `.ani`
|
||||
- 关联 `.als` 或其他描述文件
|
||||
- 生成可加入场景树的动画对象
|
||||
|
||||
这一块是项目里较有特色的内容链路，后续扩展新动画能力时，应优先梳理 `Animation`、`AnimationData` 与 `PvfArchive` 的数据流。
|
||||
|
||||
## 9. 脚本系统
|
||||
|
||||
脚本运行时由 `SquirrelVM` 单例管理，当前公开能力包括：
|
||||
|
||||
- 设置脚本目录
|
||||
- 打开/关闭 VM
|
||||
- 加载脚本文件
|
||||
- 执行脚本
|
||||
- 控制 debug 模式
|
||||
|
||||
示例中的接入顺序：
|
||||
|
||||
```cpp
|
||||
SquirrelVM::get().setScriptDirectory("assets/scripts");
|
||||
SquirrelVM::get().init();
|
||||
```
|
||||
|
||||
随后在 `Application::run()` 中，如果 VM 已初始化，会先执行 `SquirrelVM::run()`。
|
||||
|
||||
这意味着脚本系统目前是“可选启动模块”，而不是 `Application::init()` 的强制步骤。
|
||||
|
||||
## 10. 音频系统
|
||||
|
||||
音频播放能力由以下对象协作：
|
||||
|
||||
- `AudioSystem`：全局初始化、音量控制、暂停/恢复/停止
|
||||
- `Music`：背景音乐
|
||||
- `Sound`：音效
|
||||
- `SoundPackArchive`：音频资源包
|
||||
- `AudioDatabase`：逻辑名到实际资源路径的映射
|
||||
|
||||
从现有代码看，典型接入顺序应是：
|
||||
|
||||
1. `AudioSystem::init()`
|
||||
2. 配置主音量、音效音量、音乐音量
|
||||
3. 初始化 `SoundPackArchive`
|
||||
4. 加载 `AudioDatabase`
|
||||
5. 通过 `Music` 或 `Sound` 加载并播放
|
||||
|
||||
不过示例中的音频演示代码大部分仍是注释状态，因此目前更适合把它视为“已具备基础设施，正在逐步验证的模块”。
|
||||
|
||||
## 11. 示例程序现状
|
||||
|
||||
`Game/src/main.cpp` 目前承担三类职责：
|
||||
|
||||
- 展示引擎最小启动路径；
|
||||
- 验证资源包、动画、文本、事件等模块是否正常联动；
|
||||
- 作为日常回归测试入口。
|
||||
|
||||
示例里当前已经体现的能力包括：
|
||||
|
||||
- 设置窗口尺寸和标题
|
||||
- 初始化脚本目录与 SquirrelVM
|
||||
- 打开 PVF 并初始化字符串资源
|
||||
- 初始化 NPK 图像包
|
||||
- 创建并压入场景
|
||||
- 注册字体并创建文本节点
|
||||
- 创建动画节点
|
||||
- 创建测试 Actor 并监听手柄事件
|
||||
- 从 NPK 中创建精灵并加入场景
|
||||
|
||||
因此，阅读示例时建议优先关注“启动顺序”和“模块初始化顺序”，而不是把它当成最终游戏逻辑模板。
|
||||
|
||||
## 12. 推荐阅读路径
|
||||
|
||||
第一次接手这个项目，建议按下面顺序看代码：
|
||||
|
||||
1. `Game/src/main.cpp`
|
||||
2. `Frostbite2D/include/frostbite2D/core/application.h`
|
||||
3. `Frostbite2D/src/frostbite2D/core/application.cpp`
|
||||
4. `Frostbite2D/include/frostbite2D/scene/scene.h`
|
||||
5. `Frostbite2D/include/frostbite2D/2d/actor.h`
|
||||
6. `Frostbite2D/include/frostbite2D/resource/asset.h`
|
||||
7. `Frostbite2D/include/frostbite2D/resource/npk_archive.h`
|
||||
8. `Frostbite2D/include/frostbite2D/resource/pvf_archive.h`
|
||||
9. `Frostbite2D/include/frostbite2D/graphics/renderer.h`
|
||||
10. `Frostbite2D/include/frostbite2D/script/squirrel_vm.h`
|
||||
|
||||
这样能先建立运行主线，再理解渲染、资源和扩展系统。
|
||||
|
||||
## 13. 开发约定与维护建议
|
||||
|
||||
### 13.1 已观察到的代码风格
|
||||
|
||||
- 类名使用 PascalCase
|
||||
- 方法名大量使用大写开头的引擎风格命名，如 `SetPosition`、`GetScene`
|
||||
- 成员变量普遍使用尾随下划线
|
||||
- 单例模式被广泛使用
|
||||
- 错误处理倾向于返回 `bool` 和 SDL 日志，而不是异常
|
||||
|
||||
需要注意：仓库规范文档里建议方法使用 camelCase，但现有代码中同时存在 `SetPosition` / `GetCurrentScene` / `PushScene` 这类风格，后续维护应优先保持同模块内一致性。
|
||||
|
||||
### 13.2 初始化顺序很重要
|
||||
|
||||
当前模块间存在明显依赖顺序：
|
||||
|
||||
- 必须先有 `Application`，再有窗口和渲染器；
|
||||
- 必须先初始化资源系统，再读取 PVF/NPK；
|
||||
- 必须先注册字体，再创建 `TextSprite`；
|
||||
- 若要在启动时跑脚本，需先初始化 `SquirrelVM`；
|
||||
- 若要播放音频，必须先初始化 `AudioSystem`。
|
||||
|
||||
排查问题时，优先确认是不是初始化顺序错误。
|
||||
|
||||
### 13.3 路径与资源问题
|
||||
|
||||
项目强依赖运行目录和资源复制行为：
|
||||
|
||||
- 不要假设 IDE 工作目录一定正确；
|
||||
- 尽量通过 `Asset` 统一处理路径；
|
||||
- 构建后若缺 `assets`，资源系统基本都会失效；
|
||||
- Windows 下中文路径和 UTF-8 问题应优先通过 `Asset` 和统一路径处理规避。
|
||||
|
||||
### 13.4 当前测试策略
|
||||
|
||||
目前没有单元测试或集成测试框架，项目依赖：
|
||||
|
||||
- 编译通过
|
||||
- 示例启动成功
|
||||
- 场景与资源肉眼验证
|
||||
- SDL 日志辅助定位问题
|
||||
|
||||
如果后续要提高可维护性，优先值得补的是：
|
||||
|
||||
- 资源解析层的离线测试
|
||||
- 数学/路径/解析器这类无图形依赖模块的单元测试
|
||||
- 示例程序的最小化 smoke test
|
||||
|
||||
## 14. 当前已知边界
|
||||
|
||||
在写功能或继续扩展前，建议先接受这些现状：
|
||||
|
||||
- 当前仓库主产物是一个二进制程序，而不是独立分发的静态/动态引擎库。
|
||||
- `Game` 不只是 demo，也承载了不少联调职责。
|
||||
- 音频系统虽然已有接口，但示例联调还不完整。
|
||||
- 文档和代码注释里存在部分编码显示异常，不影响源码结构判断，但会影响阅读体验。
|
||||
- 自动化测试缺失，因此回归成本主要落在手动验证上。
|
||||
|
||||
## 15. 一个最小接入模板
|
||||
|
||||
如果要快速新建一个最小实验入口，可以参考下面的初始化顺序：
|
||||
|
||||
```cpp
|
||||
AppConfig config = AppConfig::createDefault();
|
||||
config.windowConfig.width = 1280;
|
||||
config.windowConfig.height = 720;
|
||||
config.windowConfig.title = "My Frostbite2D App";
|
||||
|
||||
Application& app = Application::get();
|
||||
if (!app.init(config)) {
|
||||
return -1;
|
||||
}
|
||||
|
||||
auto scene = MakePtr<Scene>();
|
||||
SceneManager::get().PushScene(scene);
|
||||
|
||||
app.run();
|
||||
app.shutdown();
|
||||
```
|
||||
|
||||
如果要继续接入资源、文字或动画，再按需补：
|
||||
|
||||
- `SquirrelVM::init()`
|
||||
- `PvfArchive::open()` + `init()`
|
||||
- `NpkArchive::setImagePackDirectory()` + `init()`
|
||||
- `FontManager::init()` + `registerFont()`
|
||||
|
||||
## 16. 后续文档扩展建议
|
||||
|
||||
这份文档适合作为总览文档，后续可以继续拆出专题文档：
|
||||
|
||||
- 渲染系统设计说明
|
||||
- NPK/PVF 资源格式接入说明
|
||||
- 动画系统数据流说明
|
||||
- Squirrel 脚本桥接说明
|
||||
- 平台移植说明
|
||||
|
||||
如果未来要对外开放引擎 API，再补一份按模块组织的 API 参考手册会更合适。
|
||||
Reference in New Issue
Block a user