first commmit

assets/resources/ASSETS.md

@@ -0,0 +1,169 @@
+# 第一章美术 / 音频资源清单（Chapter 1 Asset Manifest）
+
+> 本清单对应 [task-item.md](../../../.codebuddy/plan/kage_legend_mvp/task-item.md) 中的 **10.1 集成像素美术与音频资源**。
+> 真正的 PNG / WAV / MP3 二进制文件需由美术、音效组按下表规格制作并放入对应目录。
+
+> **当前状态**：所有条目均已用 1×1 纯色 PNG / 0.1s 静音 WAV / 空 MP3 帧**占位**，可通过 `node scripts/gen_placeholder_assets.js` 随时重新生成。占位资产仅保证工程可打开可联调，**不具有任何视觉/听觉效果**，必须由美术/音效替换为正式素材才能发布。
+
+---
+
+## 1. 主角 · 3 形态（参考 `images/影.png`）
+
+| 资源路径 | 形态 | 尺寸 | 帧数 | 备注 |
+|---|---|---|---|---|
+| `textures/characters/kage_red.png`    | 红衣（基础） | 16×32 | idle 2 / run 4 / jump 2 / attack 3 | 初始形态，一击即死 |
+| `textures/characters/kage_green.png`  | 绿衣（+1 水晶玉） | 16×32 | idle 2 / run 4 / jump 2 / attack 3 | 配色采用青叶主题 |
+| `textures/characters/kage_yellow.png` | 黄衣（+2 水晶玉） | 16×32 | idle 2 / run 4 / jump 2 / attack 3 | 移速提升 |
+
+每张 PNG 单独调色板 ≤ 16 色，三形态共用轮廓（便于换色表）。
+
+## 2. 敌人 · 4 种 + 1 BOSS（参考 `images/敌人.png`）
+
+| 资源路径 | 敌人 | 尺寸 | 帧数 | 备注 |
+|---|---|---|---|---|
+| `textures/enemies/qing_ren.png` | 青忍 | 16×16 | idle 1 / run 2 / throw 2 / swing 2 | 双色主题 |
+| `textures/enemies/chi_ren.png`  | 赤忍 | 16×16 | idle 1 / run 2 / throw 2 / jump 2 | 红色忍装 |
+| `textures/enemies/hei_ren.png`  | 黑忍 | 20×24 | idle 2 / run 2 / swing 2 | 掉落魔笛 |
+| `textures/enemies/yao_fang.png` | 妖坊 | 18×20 | idle 1 / cast 3 | 不动，远程火球 |
+| `textures/bosses/shuang_huan_fang.png` | 双幻坊 | 32×32（单体）/ 96×32（双身） | idle 2 / clone 4 / fireball 3 | 蝴蝶伴生对象单独贴图 |
+| `textures/bosses/butterfly.png` | BOSS 蝴蝶 | 16×16 | fly 4 | 命中后变色 2 帧 |
+
+## 3. 场景 · 森林 / 城墙 / 魔城（参考 `images/场景.png`）
+
+每个主题 4 层视差，速度比 1:2:4:4，独立调色板 ≤ 48 色（含角色共用 16 色）。
+
+| 主题 | 层 | 资源路径 |
+|---|---|---|
+| **森林** | 远景 / 中景 / 近景 / 特效 | `textures/scenes/forest/{far,mid,near,fx}.png` |
+| **城墙** | 远景 / 中景 / 近景 / 特效 | `textures/scenes/castle_wall/{far,mid,near,fx}.png` |
+| **魔城** | 远景 / 中景 / 近景 / 特效 | `textures/scenes/demon_castle/{far,mid,near,fx}.png` |
+
+MVP 仅启用青叶配色；红叶 / 雪原调色板预留接口但不纳入 MVP。
+
+## 4. 剧情背景插画（req 19.2）
+
+| 资源路径 | 内容 | 尺寸 |
+|---|---|---|
+| `textures/story/ch1_page1_ninja.png` | 主角忍者身份 | 480×270 |
+| `textures/story/ch1_page2_princess.png` | 公主被青忍掳走 | 480×270 |
+| `textures/story/ch1_page3_depart.png` | 主角启程 | 480×270 |
+
+## 5. 音效 WAV（每段 ≤ 0.5 秒）
+
+| 资源路径 | 触发 | 需求 |
+|---|---|---|
+| `audio/sfx/attack.wav`  | 任意攻击 | req 16.1 |
+| `audio/sfx/jump.wav`    | 跳跃 | req 16.1 |
+| `audio/sfx/hurt.wav`    | 受伤 / 死亡 | req 16.1 |
+| `audio/sfx/pickup.wav`  | 拾取道具 | req 16.1 |
+| `audio/sfx/parry.wav`   | 成功格挡 | req 16.1 |
+
+## 6. 背景音乐 MP3
+
+| 资源路径 | 用途 | 需求 |
+|---|---|---|
+| `audio/bgm/bgm_forest.mp3` | 森林 / 洞穴 | req 16.2 |
+| `audio/bgm/bgm_castle.mp3` | 城墙 / 密道 | req 16.2 |
+| `audio/bgm/bgm_final.mp3`  | 魔城/天守阁 | req 16.2 |
+| `audio/bgm/bgm_boss.mp3`   | BOSS 战 | req 16.3 |
+| `audio/bgm/bgm_story.mp3`  | 背景介绍过场 | req 19.7 |
+
+## 7. 粒子 / 特效
+
+| 特效 | 实现 |
+|---|---|
+| 落叶（青叶配色） | Cocos Creator ParticleSystem2D，`textures/fx/leaf_particle.png` |
+| 飘雪（预留） | 同上 — MVP 不启用 |
+| 跳跃尘 | Cocos Animation 序列帧，`textures/fx/jump_dust.png` |
+| 格挡火花 | 同上，`textures/fx/parry_spark.png` |
+
+---
+
+## 体积预算对照（req 16.5, 18.7）
+
+| 项目 | 预算 | 当前占用 | 备注 |
+|---|---|---|---|
+| **首包** | ≤ 4 MB | TBD | 主角 + 敌人 + UI + 代码 |
+| **音频总包** | ≤ 500 KB | TBD | 5 WAV + 5 MP3 |
+| **内存峰值** | ≤ 200 MB | TBD | 见 10.2 埋点 |
+
+> 填写"当前占用"由 CI 通过 `perf_report.json` 自动写入（见 10.2 PerfMonitor）。
+
+---
+
+## 8. 资源交付跟踪表（Delivery Tracker）
+
+> 状态图例：⬜ 待制作　🟨 占位中（1×1 纯色 / 静音）　🟩 已交付正式版
+> 占位由 `scripts/gen_placeholder_assets.js` 生成，每次跑会刷新所有 🟨 条目。
+
+### 8.1 主角 · 3 形态
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `textures/characters/kage_red.png`    | 🟨 | TBD-美术 | TBD | 16×32 · 11 帧 |
+| `textures/characters/kage_green.png`  | 🟨 | TBD-美术 | TBD | 16×32 · 11 帧 |
+| `textures/characters/kage_yellow.png` | 🟨 | TBD-美术 | TBD | 16×32 · 11 帧 |
+
+### 8.2 敌人 + BOSS
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `textures/enemies/qing_ren.png`        | 🟨 | TBD-美术 | TBD | 16×16 · 7 帧 |
+| `textures/enemies/chi_ren.png`         | 🟨 | TBD-美术 | TBD | 16×16 · 7 帧 |
+| `textures/enemies/hei_ren.png`         | 🟨 | TBD-美术 | TBD | 20×24 · 6 帧 |
+| `textures/enemies/yao_fang.png`        | 🟨 | TBD-美术 | TBD | 18×20 · 4 帧 |
+| `textures/bosses/shuang_huan_fang.png` | 🟨 | TBD-美术 | TBD | 32×32 本体 + 96×32 双身 |
+| `textures/bosses/butterfly.png`        | 🟨 | TBD-美术 | TBD | 16×16 · 4 帧 |
+
+### 8.3 场景视差（3 主题 × 4 层 = 12 张）
+
+| 主题 | far | mid | near | fx | 负责人 | 计划交付 |
+|---|---|---|---|---|---|---|
+| 森林 `textures/scenes/forest/*`           | 🟨 | 🟨 | 🟨 | 🟨 | TBD-美术 | TBD |
+| 城墙 `textures/scenes/castle_wall/*`      | 🟨 | 🟨 | 🟨 | 🟨 | TBD-美术 | TBD |
+| 魔城 `textures/scenes/demon_castle/*`     | 🟨 | 🟨 | 🟨 | 🟨 | TBD-美术 | TBD |
+
+### 8.4 剧情背景插画（req 19.2）
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `textures/story/ch1_page1_ninja.png`    | 🟨 | TBD-美术 | TBD | 480×270 |
+| `textures/story/ch1_page2_princess.png` | 🟨 | TBD-美术 | TBD | 480×270 |
+| `textures/story/ch1_page3_depart.png`   | 🟨 | TBD-美术 | TBD | 480×270 |
+
+### 8.5 粒子特效贴图
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `textures/fx/leaf_particle.png` | 🟨 | TBD-美术 | TBD | 透明底落叶 |
+| `textures/fx/jump_dust.png`     | 🟨 | TBD-美术 | TBD | 透明底尘土 |
+| `textures/fx/parry_spark.png`   | 🟨 | TBD-美术 | TBD | 透明底火花 |
+
+### 8.6 音效 WAV（每段 ≤ 0.5 s，req 16.1）
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `audio/sfx/attack.wav` | 🟨 | TBD-音效 | TBD | 攻击 |
+| `audio/sfx/jump.wav`   | 🟨 | TBD-音效 | TBD | 跳跃 |
+| `audio/sfx/hurt.wav`   | 🟨 | TBD-音效 | TBD | 受伤/死亡 |
+| `audio/sfx/pickup.wav` | 🟨 | TBD-音效 | TBD | 拾取 |
+| `audio/sfx/parry.wav`  | 🟨 | TBD-音效 | TBD | 格挡 |
+
+### 8.7 背景音乐 MP3（req 16.2 / 16.3 / 19.7）
+
+| 资源 | 状态 | 负责人 | 计划交付 | 备注 |
+|---|---|---|---|---|
+| `audio/bgm/bgm_forest.mp3` | 🟨 | TBD-音效 | TBD | 森林 / 洞穴 |
+| `audio/bgm/bgm_castle.mp3` | 🟨 | TBD-音效 | TBD | 城墙 / 密道 |
+| `audio/bgm/bgm_final.mp3`  | 🟨 | TBD-音效 | TBD | 魔城 / 天守阁 |
+| `audio/bgm/bgm_boss.mp3`   | 🟨 | TBD-音效 | TBD | BOSS 战 |
+| `audio/bgm/bgm_story.mp3`  | 🟨 | TBD-音效 | TBD | 背景介绍过场 |
+
+### 8.8 交付流程
+
+1. 美术 / 音效收到任务后把正式素材放到上表对应路径，**覆盖同名占位文件**。
+2. 在本 md 中把对应行的 🟨 改为 🟩，填写负责人与交付日期。
+3. 提交 PR，CI 会对比文件大小与 `ASSETS.md` 预算表 (§ "体积预算对照")。
+4. 所有条目变 🟩 且体积预算达标后，可以撤掉占位脚本的调用。
+
+> **重要**：禁止手动修改 `scripts/gen_placeholder_assets.js` 的输出策略，除非变更点已同步到本 md 的 "当前状态" 段。任何新增资源条目必须**同时**：在上述 § 1~§ 7 规格表中加一行、在 § 8 跟踪表加一行、在脚本 `SPEC` 数组加一条。