jakciehan
98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
# 影之传说：忍者救公主 · 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) 补齐。
|