影之传说：忍者救公主 · 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）：

   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 会由脚本自动应用。

脚本

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/task-item.md

当前已完成任务（全部 20 项子任务已交付）：

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