117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 游戏目录结构
|
||
|
||
这个目录用于编写新的游戏。仓库根目录下的 `src/` 继续作为软渲染器、数学库、光栅化和平台显示层；`game/` 只放游戏自己的代码、资源、脚本和数据。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
game/
|
||
README.md
|
||
assets/
|
||
sprites/ 运行时使用的 2D 精灵图片。
|
||
textures/ 3D 材质或其他渲染用途的纹理。
|
||
tilesets/ 瓦片图片和瓦片集元数据。
|
||
fonts/ 位图字体或字体图集。
|
||
audio/
|
||
music/ 背景音乐。
|
||
sfx/ 短音效。
|
||
models/ 运行时使用的 3D 模型文件。
|
||
materials/ 模型或精灵使用的材质定义。
|
||
ui/ UI 面板、图标、光标、HUD 资源。
|
||
raw/ 原始素材文件，不建议运行时直接加载。
|
||
scripts/
|
||
gameplay/ 预留给运行时玩法脚本。
|
||
ui/ 预留给运行时 UI 流程脚本。
|
||
tools/ 游戏开发期间使用的小型辅助脚本。
|
||
src/
|
||
app/ 游戏启动、场景切换、主循环衔接代码。
|
||
scenes/ 启动、菜单、游戏、暂停、结算等场景。
|
||
systems/ 输入、渲染、碰撞、动画、AI、音频等系统。
|
||
entities/ 实体定义和实体工厂。
|
||
components/ 系统使用的小型数据组件。
|
||
ui/ HUD 和菜单代码。
|
||
data/
|
||
config/ 分辨率、控制、难度、平台选项等配置。
|
||
balance/ 速度、生命、伤害、分数等数值表。
|
||
localization/ 多语言文本表。
|
||
tools/
|
||
asset_pipeline/ 资产转换、压缩、打包相关工具。
|
||
level_editor/ 可选的关卡编辑工具。
|
||
docs/
|
||
design/ 玩法规则、操作方式、关卡设计说明。
|
||
technical/ 运行时约束和接入说明。
|
||
tests/
|
||
unit/ 纯逻辑单元测试。
|
||
fixtures/ 测试用的小型数据文件。
|
||
```
|
||
|
||
## 边界约定
|
||
|
||
- 仓库根目录的 `src/` 是渲染器和引擎基础层。
|
||
- `game/src/` 可以依赖根目录 `src/`，但根目录 `src/` 不应该反向依赖 `game/`。
|
||
- `game/assets/raw/` 只放可编辑源素材，运行时应加载转换后的资源。
|
||
- `game/assets/sprites/` 放离线转换后的 `.sprite` 文件，PC 测试和 IMX6U 运行时都从这里读取。
|
||
- `game/scripts/gameplay/` 预留给运行时脚本；构建、转换、检查类脚本放在 `game/scripts/tools/` 或 `game/tools/asset_pipeline/`。
|
||
- 平台相关逻辑尽量集中在 `game/src/app/` 或 `game/data/config/`，不要散落到各个玩法模块里。
|
||
|
||
## 精灵资源转换
|
||
|
||
板端运行时不直接解码 PNG。开发时把 PNG 放在 `game/assets/raw/`，再用 PC 端工具转换为 `game/assets/sprites/*.sprite`。
|
||
|
||
`.sprite` 是项目自定义的简单二进制格式：
|
||
|
||
```text
|
||
offset size 内容
|
||
0 4 magic: "SPRT"
|
||
4 4 version: 1, little-endian uint32
|
||
8 4 width, little-endian uint32
|
||
12 4 height, little-endian uint32
|
||
16 4 format: 1 表示 RGBA8888
|
||
20 * width * height 个 RGBA8888 像素，每像素 little-endian uint32
|
||
```
|
||
|
||
像素颜色沿用渲染器约定：`0xRRGGBBAA`，最低 8 位是 alpha。
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
# 构建 PC 端工具
|
||
cmake -B build-win .
|
||
cmake --build build-win --config Release --target SpriteAssetTool
|
||
|
||
# 批量转换当前汤姆猫素材，输出适配 800x480 的板端资源
|
||
cmake --build build-win --config Release --target ConvertTomSprites
|
||
|
||
# 单张转换，保持原尺寸
|
||
./build-win/Release/SpriteAssetTool.exe game/assets/raw/ui-record.png game/assets/sprites/ui-record.sprite
|
||
|
||
# 单张转换并等比缩放到最大范围
|
||
./build-win/Release/SpriteAssetTool.exe game/assets/raw/Tom-stand.png game/assets/sprites/Tom-stand.sprite --fit 560 360
|
||
```
|
||
|
||
Linux PC 构建工具需要 `libsdl2-dev` 和 `libsdl2-image-dev`。ARM framebuffer 构建不会编译 `SpriteAssetTool`，只编译 `.sprite` 加载器。
|
||
|
||
启动汤姆猫资源链路测试：
|
||
|
||
```bash
|
||
./build-win/Release/IMX6U-Game.exe --tom
|
||
```
|
||
|
||
部署到板端时，把可执行文件和转换后的 `game/assets/sprites/` 一起拷贝，保持相对路径即可；也可以放到 `/tmp/game/assets/sprites/` 或 `/usr/local/share/imx6u-game/sprites/`。
|
||
|
||
## 建议优先创建的文件
|
||
|
||
真正开始写游戏逻辑时，建议先从这些文件开始：
|
||
|
||
```text
|
||
game/src/app/GameApp.h
|
||
game/src/app/GameApp.cpp
|
||
game/src/scenes/BootScene.h
|
||
game/src/scenes/BootScene.cpp
|
||
game/src/scenes/PlayScene.h
|
||
game/src/scenes/PlayScene.cpp
|
||
game/data/config/game.json
|
||
```
|
||
|
||
后续可以把现有的 `src/main.cpp` 改成薄启动器：只负责创建显示后端、初始化缓冲区和渲染器，然后把更新和绘制流程交给 `GameApp`。
|