first commmit

README.md

@@ -0,0 +1,97 @@
+# 影之传说：忍者救公主 · 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) 补齐。