# 实施计划 — 《影之传说：忍者救公主》MVP（仅第一章，横屏）

> 以下任务基于 [requirements.md](./requirements.md) 中的 20 条需求，按"自底向上 + 可独立验证"的顺序组织。每一个子任务均为可执行的编码步骤，可独立提交与测试。
>
> **核心约束**：横屏（Landscape）锁定、设计分辨率 960×540、Cocos Creator 3.8.x + TypeScript、微信小游戏、首包 ≤4MB、锁帧 30fps、仅硬核模式、MVP 仅第一章 5 关。

---

- [ ] 1. 项目脚手架与分层架构搭建
- [ ] 1.1 初始化 Cocos Creator 3.8.x + TypeScript 项目（横屏）
  - 创建项目骨架：`assets/scripts/{ui,logic,data,common}`、`assets/scenes`、`assets/resources/{prefabs,textures,audio,configs}`
  - 配置微信小游戏构建选项（基础库 2.16.0+，锁帧 30fps）
  - **在 Cocos Project Settings + `game.json` 中强制横屏**（`deviceOrientation: landscape`），设计分辨率 960×540，Canvas Fit Height 适配策略
  - 接入 ESLint + Prettier + tsconfig 严格模式
  - _需求：技术栈约束、18.1 ~ 18.7_
- [ ] 1.2 建立核心基础设施模块
  - 实现 `EventBus`（全局事件）、`ObjectPool`（对象池）、`TimeMgr`（暂停/恢复）、`StorageMgr`（封装 `wx.setStorageSync` + 读取失败回退）
  - 定义 `Logger` 与分级打点接口，预留性能埋点入口
  - 为上述模块补充单元测试（Jest），覆盖率 ≥ 80%
  - _需求：17.1 ~ 17.6、18.4 ~ 18.5、20.1 ~ 20.6_

- [ ] 2. 数据驱动配置与类型系统
- [ ] 2.1 定义 TS 接口与 JSON 配置表（仅硬核）
  - 编写 `IEnemyConfig`、`IWeaponConfig`、`IItemConfig`、`ILevelConfig`、`IBossConfig`、`IStorySceneConfig` 等接口
  - 输出第一章 5 关 + 4 种敌人 + 1 个 BOSS（双幻坊）+ 5 种道具（水晶玉/点丸/术丸/魔笛/增丸）+ 2 种武器 + 剧情背景 3 页配置的 JSON
  - 实现 `ConfigMgr` 异步加载与校验（缺失字段报错），**不加载任何轻度模式配置分支**
  - _需求：6.1 ~ 6.7、7.1 ~ 7.6、8.1 ~ 8.5、9.1 ~ 9.6、13.1 ~ 13.6、19.2_

- [ ] 3. 悬浮操作 UI 系统（横屏布局 + 多点触控）
- [ ] 3.1 实现悬浮 UI 图层与虚拟摇杆（横屏基线 960×540）
  - 创建独立 UI Canvas（层级高于游戏场景），按横屏布局渲染摇杆（左下 Ø120px）、跳跃键（摇杆右上方 Ø90px）、手里剑（右下偏左 Ø90px）、忍者刀（右下偏右 Ø90px），默认透明度 70%
  - 保证左右两组按钮分别落在屏幕**左右 1/3 安全区**，不遮挡战斗视野
  - 实现摇杆死区（10px）、区域外点击方向向量识别、45°/135° 抛物线角度识别区与轨迹预览光效
  - 支持横屏安全区自适应（16:9 / 18:9 / 19.5:9 / 20:9，识别**左右两侧**刘海/听筒/Home Indicator），≥3 点多点触控、按钮区优先、非按钮区事件穿透
  - _需求：1.1 ~ 1.8、2.5 ~ 2.6、18.6、20.1、20.3_
- [ ] 3.2 实现布局自定义与持久化
  - 长按进入布局设置模式，允许拖拽按钮位置、调整大小与透明度
  - 将布局写入 `StorageMgr`，下次启动自动还原；读取失败使用横屏默认布局
  - _需求：1.6、17.2、17.6_

- [ ] 4. 角色移动与物理跳跃系统
- [ ] 4.1 实现地面检测与横向移动
  - 基于简化 AABB 碰撞实现地面/空中状态机，暴露 `isGrounded` 属性
  - 摇杆左右方向 → 100/150px/秒移动（红衣/绿衣/黄衣分档）
  - _需求：2.1、5.1 ~ 5.2_
- [ ] 4.2 实现物理跳跃与抛物线跳跃
  - 实现标准垂直跳（250px）、长按蓄力高跳（375px）、黄衣跳跃（300px）
  - 摇杆在 45°/135° + 跳跃按下 → 抛物线轨迹跳跃；空中禁用跳跃按钮并半透明反馈
  - 起跳前插入 ≈150ms 下蹲延迟；硬核模式下跳跃过程中禁止横向轨迹调整
  - _需求：2.2 ~ 2.8、13.3 ~ 13.5、20.2、20.5_

- [ ] 5. 攻击与状态系统（双按钮互斥 + 自动升级）
- [ ] 5.1 实现双攻击按钮互斥与组合操作
  - 点击任一攻击按钮激活对应武器（手里剑 0.3/0.25 s，忍者刀 0.5 s），另一按钮半透明未激活；同时按下以最先按下的为准
  - 支持长按手里剑 3 连发；跳跃+攻击（100ms 内）识别为跳跃攻击组合；允许"移动+跳跃+攻击"三合一与组合光效叠加
  - _需求：3.1 ~ 3.6、3.9、4.1 ~ 4.5、20.4_
- [ ] 5.2 实现忍者刀攻防一体与角色状态机
  - 忍者刀判定帧内对 `shuriken/sword` 类型攻击成功格挡（播放特效+音效），对 `fireball/smoke_bomb` 不格挡
  - 角色状态机：红衣 ↔ 绿衣 ↔ 黄衣，拾取水晶玉自动升级，被普攻命中立即降回红衣并清零强化；烟玉/火球直接死亡
  - _需求：3.7 ~ 3.8、5.1 ~ 5.6、10.2 ~ 10.5_

- [ ] 6. 敌人 AI、道具与碰撞伤害系统
- [ ] 6.1 实现 4 种敌人 AI
  - 青忍（远程十字镖 + 近战刀斩，2.0 s 间隔）、赤忍（120px/s + 烟玉 1.5 s + 主动拦截跳跃）
  - 黑忍（城壁关卡掉落魔笛卷物，死亡后不再刷新）、妖坊（3.0 s 直线火球，秒杀）
  - 摄像机视野外敌人暂停 AI 更新，进入视野恢复；敌人/子弹统一走对象池
  - _需求：6.1 ~ 6.7、18.5_
- [ ] 6.2 实现道具掉落与碰撞伤害判定
  - 森林 12 击杀计数 → 水晶玉确定性生成，13~20 s 或移出视野后销毁
  - 3 赤忍击杀 → 50% 掉落点丸/术丸；魔笛秒杀全屏；增丸 +1 命
  - 统一 `DamageSystem`：无敌帧 → 忍者刀格挡 → 攻击类型/距离判定 → 扣血；火球 <100px、烟玉 <80px 致命
  - _需求：7.1 ~ 7.6、10.1 ~ 10.6_

- [ ] 7. 关卡、场景与视差滚动系统
- [ ] 7.1 实现 4 层视差场景与关卡框架（按 16:9 横屏基准标定）
  - 抽象 `LevelBase`，加载关卡配置 → 摄像机卷轴（横向/左右/垂直）→ 4 层视差滚动（1:2:4:4）
  - **按 16:9 横屏可视宽度重新标定卷轴速度与关卡长度**，保证 30fps 稳定渲染
  - 场景互动：树木/石柱遮挡子弹、草丛短暂隐身、藤蔓可攀爬、绳索需挥刀斩断
  - _需求：8.8 ~ 8.9、15.4 ~ 15.5、18.1 ~ 18.3_
- [ ] 7.2 实现第一章 5 关内容（1-1 ~ 1-5）
  - 按配置表完成 1-1 森林（3 妖坊/75s）、1-2 森林深处（红妖珠坊/85s）、1-3 洞穴水路（10 青忍/100s）、1-4 城壁垂直（顶层/95s）
  - 1-5 魔城天守阁：进入双幻坊 BOSS 战房间；保证时限、通关条件、场景切换稳定
  - _需求：8.1 ~ 8.5、14.5_

- [ ] 8. BOSS 战（双幻坊 蝴蝶显形）与第一章结局叙事
- [ ] 8.1 实现蝴蝶显形与一击必杀机制
  - BOSS 战关卡生成环绕蝴蝶对象，未命中前 BOSS 无敌；命中蝴蝶 → 变色并触发 BOSS 显形
  - 双幻坊 3 种攻击模式（双人夹击 / 火球喷射 / 分身迷惑）按血量 1/3 阶段切换
  - 显形后任一有效命中 → BOSS 死亡；玩家被火球命中立即死亡
  - _需求：9.1 ~ 9.6、13.4_
- [ ] 8.2 实现"公主被带走"过场与章节结算
  - BOSS 血量 ≤ 1/2 时触发 ≤3s "公主被青忍带走"短过场（战斗不暂停）
  - 击败双幻坊 → ≤2s 定格画面 → 无缝进入第一章结算界面；全程不得出现"斩断绳索解救成功"画面
  - 过场与结算期间支持"跳过"按钮直达结算
  - _需求：8.6 ~ 8.7、14.1 ~ 14.5_

- [ ] 9. 基础 UI 流程、剧情背景、新手引导与得分结算
- [ ] 9.1 实现剧情背景介绍系统（正式进关前的背景交代）
  - 新建 `StorySceneCtrl`：按配置加载 3 页像素插画 + 打字机文案，分页推进；右下角"跳过"、左下角"下一页"指示
  - 点击屏幕任意区域加速打字显现；点击"跳过"立即终止过场并加载 1-1，无二次确认
  - 仅**首次**从主菜单点击"开始游戏"或首次进入 1-1 时自动播放；首次完成/跳过后写入 `StorageMgr`，下次启动默认跳过
  - 设置界面提供"重新观看背景介绍"入口、结算界面"重玩第一章"按钮触发状态重置
  - 播放专属 `bgm_story`，遵循 BGM/音效音量；960×540 横屏布局下文字避开左右安全区
  - 过场结束无缝衔接新手引导（需求 11.1），不引入额外点击等待
  - _需求：19.1 ~ 19.9、17.5_
- [ ] 9.2 实现主流程 UI 场景（横屏布局）
  - 主菜单（开始游戏/设置/关卡选择）→ 关卡选择（依据本地解锁状态）→ 游戏内 HUD（命数/得分/计时）→ 结算界面（本关得分/总分/连击/无伤）→ 失败界面（重试/返回）
  - 设置界面：BGM/音效音量、悬浮按钮布局重置、重置新手引导、**重新观看背景介绍**；**不得出现任何难度选择入口**
  - 所有场景均按 960×540 设计，横屏下对刘海/听筒区进行黑边或偏移处理
  - _需求：12.7 ~ 12.8、13.1、17.1 ~ 17.6、18.6_
- [ ] 9.3 实现新手引导与得分系统
  - 1-1 高亮引导：攻击按钮 → 摇杆 → 跳跃按钮；1-2 引导：抛物线跳跃/互斥按钮/格挡/跳跃攻击/自动升级；1-3 引导：蝴蝶显形/BOSS 攻击识别/一击必杀
  - 引导完成状态持久化；得分规则：忍者刀 ×2、手里剑 ×1、完美格挡 ×3、5 连刃接触 +1500、无伤 ×3、剩余时间折分
  - _需求：11.1 ~ 11.5、12.1 ~ 12.6_

- [ ] 10. 美术音效资源、性能优化与体验埋点
- [ ] 10.1 集成像素美术与音频资源
  - 按 `images/影.png`、`images/敌人.png`、`images/场景.png` 产出主角 3 形态（16×32）、4 敌人、1 BOSS 及森林/城墙/魔城 3 场景（每场景 ≤48 色）
  - 产出剧情背景介绍的 3 页像素插画（主角身份/公主被掳/启程使命）
  - 接入 5 类 WAV 音效（attack/jump/hurt/pickup/parry）与 5 首 MP3 BGM（forest/castle/final/boss/story），总音频 ≤500KB
  - 实现季节调色板切换（青叶/红叶/雪原）与落叶/飘雪粒子（MVP 仅启用青叶，其余保留接口）
  - _需求：15.1 ~ 15.5、16.1 ~ 16.5、19.7_
- [ ] 10.2 性能优化与埋点验证
  - 对象池复用敌人/子弹/特效；关卡切换清理资源，内存峰值 ≤200MB；首包 ≤4MB（其余按关卡分包）
  - 横屏异形屏适配（左右两侧安全区识别），低端机可关闭粒子特效，帧率 ≥25fps
  - 埋点：触控响应 <50ms、跳跃状态切换 <50ms、45°/135° 识别 ≥95%、组合识别 <100ms、空中跳跃禁用执行率 ≥99%，并输出流畅度评分统计
  - _需求：18.1 ~ 18.7、20.1 ~ 20.6_