# 游戏目录结构

这个目录用于编写新的游戏。仓库根目录下的 `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`。