IMX6U-Game/game

游戏目录结构

这个目录用于编写新的游戏。仓库根目录下的 src/ 继续作为软渲染器、数学库、光栅化和平台显示层；game/ 只放游戏自己的代码、资源、脚本和数据。

目录结构

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 是项目自定义的简单二进制格式：

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。

常用命令：

# 构建 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 加载器。

启动汤姆猫资源链路测试：

./build-win/Release/IMX6U-Game.exe --tom

部署到板端时，把可执行文件和转换后的 game/assets/sprites/ 一起拷贝，保持相对路径即可；也可以放到 /tmp/game/assets/sprites/ 或 /usr/local/share/imx6u-game/sprites/。

建议优先创建的文件

真正开始写游戏逻辑时，建议先从这些文件开始：

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。