Split game module documentation

2026-06-09 23:11:08 +08:00
parent d41f9d1096
commit 0257c8058e
15 changed files with 647 additions and 88 deletions
@@ -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 支持。