# 影之传说：忍者救公主 · MVP

基于 Cocos Creator 3.8.x + TypeScript 的微信小游戏横版动作 MVP 版本（仅第一章）。

## 项目元信息

| 项 | 值 |
|---|---|
| 游戏引擎 | Cocos Creator **3.8.3** |
| 开发语言 | TypeScript (strict) |
| 运行平台 | 微信小游戏（基础库 2.16.0+） |
| 屏幕方向 | **横屏（Landscape）强制锁定** |
| 设计分辨率 | **960 × 540**（16:9 基准，`FIT_HEIGHT` 策略） |
| 锁帧 | 30 fps |
| 首包上限 | ≤ 4 MB（其余按关卡分包） |
| 音频包上限 | ≤ 500 KB |
| 范围 | 第一章 1-1 ~ 1-5，仅硬核模式 |

## 目录结构

```
.
├── assets/
│   ├── scenes/              # Cocos Creator .scene 文件（需在编辑器内创建）
│   ├── resources/           # runtime-loadable 资源（prefabs/textures/audio/configs）
│   └── scripts/
│       ├── GameBoot.ts      # 启动脚本（横屏/分辨率/锁帧）
│       ├── common/          # 跨层常量与纯工具（平台无关，Jest 可测）
│       ├── data/            # TS 接口、JSON 配置、校验器（task 2.1）
│       ├── logic/           # 游戏逻辑层（任务 4.x ~ 8.x）
│       └── ui/              # UI/HUD/悬浮控件层（任务 3.x、9.x）
├── build-templates/
│   └── wechatgame/
│       └── game.json        # 微信小游戏横屏与分包声明
├── settings/v2/packages/
│   └── project.json         # Cocos Creator 3.8 工程级 project.json
├── profiles/v2/
│   └── project.json         # 预览器配置（横屏 / 960×540 / 30fps）
├── tests/
│   ├── __mocks__/cc.ts      # Jest 下的 cc 模块 mock
│   └── common/              # 与 assets/scripts/common 一一对应的单测
├── tsconfig.json            # strict 模式 + 路径别名
├── .eslintrc.json           # TS + prettier 规则
├── .prettierrc.json         # 4 空格缩进
├── jest.config.js           # ts-jest + 80% 覆盖率门槛
└── package.json             # 脚手架脚本入口
```

## 首次打开与启动

1. **安装 Node 依赖**（用于 lint / test / format）：
   ```bash
   npm install
   ```
2. **在 Cocos Creator 3.8.3 中打开项目根目录**：编辑器会自动补齐 `library/`、`temp/`、`.meta` 文件。
3. **按 `assets/scenes/README.md` 创建 `Boot.scene`**，挂载 `GameBoot` 组件，并在 `Project Settings ▸ Start Scene` 中指定它。
4. 在编辑器顶部选择"模拟器"或"浏览器"点击 `▶` 预览；横屏锁定、30fps、960×540 会由脚本自动应用。

## 脚本

```bash
npm run lint        # ESLint 扫描
npm run lint:fix    # 自动修复可修复问题
npm run format      # Prettier 格式化
npm test            # Jest 运行所有单测
npm run test:coverage  # 带覆盖率报告（门槛 80%）
```

## 需求与任务对照

- 详细需求：[`.codebuddy/plan/kage_legend_mvp/requirements.md`](.codebuddy/plan/kage_legend_mvp/requirements.md)
- 拆解清单：[`.codebuddy/plan/kage_legend_mvp/task-item.md`](.codebuddy/plan/kage_legend_mvp/task-item.md)

当前已完成任务（全部 20 项子任务已交付）：
- [x] 1.1 项目脚手架搭建（横屏锁定 960×540、微信小游戏配置、分层目录、ESLint/Prettier/Jest）
- [x] 1.2 核心基础设施（EventBus / ObjectPool / TimeMgr / StorageMgr / Logger + Jest 单测）
- [x] 2.1 TS 接口与 6 份 JSON 配置表（敌人/道具/武器/关卡/BOSS/剧情，ConfigMgr 校验拒绝轻度模式）
- [x] 3.1 悬浮 UI 与虚拟摇杆（纯 TS `InputModel` + Cocos 视图 `FloatingControlLayer`，45°/135° 识别率 ≥95%）
- [x] 3.2 布局自定义与持久化（`LayoutCustomizer` + 防损坏回退）
- [x] 4.1 `PlayerMotionModel` — AABB 地面检测、红/绿/黄衣移速分档、硬核起跳定型
- [x] 4.2 `JumpController` — 物理跳跃 / 蓄力跳 / 45°抛物线跳 / 150ms 起跳延迟
- [x] 5.1 `AttackController` — 双攻击按钮互斥 / 手里剑 3 连发 / 100ms 组合识别窗
- [x] 5.2 `PlayerStateMachine` — 红↔绿↔黄衣 / 忍者刀格挡 / i-frames / 烟玉火球秒杀
- [x] 6.1 4 种敌人 AI（`QingRenAI` / `ChiRenAI` / `HeiRenAI` / `YaoFangAI`）+ `EnemyManager` 视野外暂停
- [x] 6.2 `DropSystem`（12 击杀水晶玉确定性 / 3赤忍 50% 点术丸）+ `DamageSystem`（fireball/smoke 距离门）
- [x] 7.1 `CameraScroller`（4 层视差 1:2:4:4） + `LevelMgr`（计时 / 目标 / 结算）
- [x] 7.2 第一章 5 关 JSON 配置已落地，`Chapter1Levels.test.ts` 验证 × LevelMgr 全通关
- [x] 8.1 `BossController` — 双幻坊蝴蝶显形 / 一击必杀 / 3 阶段攻击
- [x] 8.2 `ChapterSettlement` — "公主被带走"定格，`BANNED_RESCUE_SEQUENCE` 阻止斩绳解救画面
- [x] 9.1 `StorySceneCtrl` — 3 页打字机过场 / 跳过 / 首次播放持久化
- [x] 9.2 `UIFlowMgr` — 场景路由 / 首次启动剧情门 / **不含难度选择入口**
- [x] 9.3 `TutorialMgr`（1-1/1-2/1-3 三关引导）+ `ScoreSystem`（全套得分规则）
- [x] 10.1 [assets/resources/ASSETS.md](assets/resources/ASSETS.md) 美术 / 音频清单（3 主角 + 4 敌人 + 1 BOSS + 3 场景 + 3 剧情插画 + 5 WAV + 5 BGM）
- [x] 10.2 `PerfMonitor` — 聚合 Logger 指标，对照 req 18 / 20 阈值输出 pass/fail 报告

> **全部 Jest 单元测试可通过 `npm test` 运行**，本次交付共新增 **15 个测试文件、80+ 测试用例**。
> 真正的 `.scene` / `.prefab` / PNG / WAV 等二进制资产需由美术、策划在 Cocos Creator 3.8.3 中按 [assets/scenes/README.md](assets/scenes/README.md) 与 [assets/resources/ASSETS.md](assets/resources/ASSETS.md) 补齐。