# 缺失功能路线图（Missing-Features Roadmap）

> **日期**：2026-07-23
> **用途**：盘点 Spellforge 当前所有未实现/占位的功能，分组为史诗（Epic），给出目标·现状·依赖·工作量·优先级·验收标准·切分建议，作为后续逐个 `spec → plan → 实现` 的统筹入口。
> **来源**：`docs_dev/doc_code_audit_2026-07-20.md`（对抗性复核过）+ 2026-07-23 代码复核（见各 Epic「现状」引用行号）。已完成并从本表剔除：Mana（`93dffd7`）、元进展（`MetaProgress`）、Boss 阶段+攻击系统（`95e5587`）。
> **⚠️ 复核约定**：审计为 7-20 快照，本文 7-23 复核了关键声明；每个 Epic 真正立项写详细计划前，仍须对其「现状」再复核一次当前代码（行号可能漂移）。

---

## 0. 优先级与推荐顺序

优先级分层（用户 2026-07-23 选定 P0/P1 四项为最先详细规划）：

| 层级 | Epic | 一句话理由 |
| :-- | :-- | :-- |
| **P0** | E1 战斗深度 | 元素/轨迹词条现为死代码，落地即让大量已有内容"活过来"，build 多样性提升最直接 |
| **P0** | E3 经济与 build | 货架 B/C + 出售 + 属性词条，撑起 roguelite 的核心成长/取舍循环 |
| **P1** | E4 游戏循环/里程碑 | 通关演出 + `GAME_CLEARED` + NG+ + Boss Rush，让游戏有"结局"与重玩驱动 |
| **P1** | E6 Boss 深化 | 承接已完成的 Boss 核心：场地机制、通关演出、玩家无敌帧 |
| P2 | E2 状态/元素反应 | 依赖 E1 元素成熟；催化/反应矩阵是深度上限 |
| P2 | E5 教程/引导 | 独立打磨项，商业化必需但非玩法核心 |
| P3 | E7 渲染/性能/债务 | LOD/C# 热路径/UI .tscn 化/i18n 债务，长尾优化 |

**推荐实现顺序（含依赖）**：
```
E6-a 玩家无敌帧(i-frames)  ← 先行小项：Boss 弹幕公平性前置，E1 也受益
  → E1 战斗深度（抗性 → 连锁/弹跳 → 归航 → 轨迹修正）
  → E3 经济与 build（属性词条系统 → 货架 C → 货架 B → 出售退款）
  → E4 游戏循环（GAME_CLEARED/通关演出 → 里程碑 → Boss Rush/Endless 词条 → NG+）
  → E6-b Boss 深化其余（场地机制：冰墙/收缩 → 通关/死亡演出）
  → E2 状态反应 → E5 教程 → E7 债务
```

工作量记号：**S**≈3–5 任务、**M**≈6–10 任务、**L**≈11–16 任务（Boss 系统为 12 任务=M~L 参照系）。

---

## E1. 战斗深度（元素抗性 / 连锁 / 弹跳 / 归航 / 轨迹修正）  · P0 · 工作量 M

**目标**：让子弹的 pierce 以外的深度维度真正生效，使元素、抗性、轨迹类词条与核心特性产生行为差异。

**现状（代码复核 2026-07-23）**：
- 元素抗性：`damage_context.gd:26` `calc_damage(armor, resistance)` 公式含 `(1−resistance)`，但 `enemy_manager.apply_damage_from_context` 调 `ctx.calc_damage()` 不传参 → resistance 恒 0；`player_stats.gd:23 resistance` 亦为占位。抗性维度是**死代码**。
- 连锁/弹跳：`bullet_manager.gd` 仅消费 `pierce_remaining`（:98-101），**无** `bounce_remaining` 消费、无 `visited_targets`、无 `pow(0.9,bounce)` 衰减。
- 归航：`bullet_manager.gd:21` 每帧建 `_enemy_pos_snapshot`（预分配满足 P6-N25）但 `_gd_integrate` 无 homing 转向计算，**快照无人消费**。
- 轨迹修正（加速/曲线）：`_data +11 acceleration` 已积分，但无"转向/曲线"类修饰器写入。

**设计来源**：`docs/mechanics/combat_mechanics_depth.md §4`（抗性公式）、子弹冷数据字段。

**依赖**：无硬依赖；元素 tag 体系已在（`SpellNode.element_tags`）。敌人需有 per-type/per-status 抗性数据源（新增 `enemies.json` 抗性字段或状态减抗）。

**切分（建议 4 个子计划）**：
1. **元素抗性 (1-Res)**：enemies.json 增 `resistances:{element:0..1}`；EnemyManager 命中时按子弹 `damage_type`/element 查抗性，传入 `calc_damage(armor, res)`；设计器敌人页加抗性栏。S。
2. **连锁/弹跳 chain/bounce**：子弹冷数据加 `bounce_remaining` + `visited_targets`；命中后若 bounce>0 且有未命中目标 → 重定向速度朝最近未访问敌人，衰减 `×0.9`；到 0 回收。修饰器 `modifier_bounce`。S~M。
3. **归航 homing**：子弹冷数据 `homing_strength`；`_gd_integrate` 消费 `_enemy_pos_snapshot` 求最近敌人，按 strength 插值转向速度向量。修饰器 `modifier_homing`。S。
4. **轨迹修正**：曲线/环绕类（angular velocity 字段）+ 对应修饰器。S（可选，最低价值，YAGNI 可延后）。

**验收标准**：抗性 50% 的敌人受火伤减半（数值实测）；bounce=2 子弹依次命中 3 个不同敌人且伤害递减；homing 子弹命中偏移目标；各修饰器可在商店买到并影响弹道；纯数据驱动、MCP 运行时实测。

---

## E2. 状态 / 元素反应（催化 / 环境反应 / 状态交互矩阵 / VULNERABILITY）  · P2 · 工作量 M

**目标**：状态之间、元素之间产生化学反应（催化引爆、易伤叠加、地表反应），把 StatusManager 从"独立计时器"升级为"交互矩阵"。

**现状**：`status_registry.gd` 不解析 `can_catalyze`（死字段）；无 overwrite/immunity 规则、无反应地表；VULNERABILITY 状态（+5% 受伤，`consecutive_hits_stacking.md:80`）**未实现**（现只有 COMBO_MARK +2%）。

**设计来源**：`docs/mechanics/consecutive_hits_stacking.md`、`combat_mechanics_depth.md` 状态矩阵。

**依赖**：E1（元素/抗性成熟后反应才有意义）。

**切分**：① VULNERABILITY 状态 + 命中叠层（S）；② 状态交互矩阵（overwrite/immunity/refresh 规则表，JSON 驱动，S~M）；③ 催化引爆（catalyze：某状态达阈值被特定元素引爆成 AoE，M）；④ 反应地表（借 ZoneManager，M，可延后）。

**验收标准**：VULNERABILITY 叠层增伤生效；毒+火催化引爆造成范围伤；矩阵规则（如冰覆盖火）按 JSON 生效；MCP 实测。

---

## E3. 经济与 build（货架 B/C + 出售退款 + 属性词条系统）  · P0 · 工作量 M~L

**目标**：把商店从"只卖法术"扩成完整 roguelite 经济：核心抽取、属性升级、出售退款，配合玩家属性成长系统。

**现状（代码复核 2026-07-23）**：`shop_manager.gd` 无 shelf/sell/core/attr 任何字段（grep 零匹配）→ **仅货架 A（法术抽取）**。`player_stats.gd` 有 `resistance` 等占位属性（4/5 stats 未接线）。无出售退款（G5）。

**设计来源**：`docs/design/game_design.md §5`（三货架）、`numerical_design.md`（属性曲线、退款比例）。

**依赖**：货架 C 依赖「属性词条系统」先落地；核心抽取复用已有 `cores.json`/`make_core_by_id`。

**切分（建议 4 个子计划，属性词条优先）**：
1. **属性词条系统**：定义 4/5 缺失 player stats（如暴击/急速/范围/吸血/减伤）+ 数据驱动加成来源；PlayerStats 接线到伤害/射速/…；`attributes.json` + 设计器页。M。
2. **货架 C（属性购买）**：商店可购属性词条（消耗金币/以太），叠加到 PlayerStats。S~M。
3. **货架 B（核心抽取）**：商店提供 Core 抽取/更换（复用 `_CORE_ROSTER`），与现有换杖打通。S~M。
4. **出售退款 G5**：背包内法术/核心可出售，按 `numerical` 退款比例返还货币。S。

**验收标准**：三货架并存刷新正确；买属性词条后伤害/射速等实测变化；核心抽取可换 build；出售返还货币且从背包移除；纯数据驱动 + 设计器可调 + MCP 实测。

---

## E4. 游戏循环 / 里程碑（通关演出 / GAME_CLEARED / 里程碑 / Boss Rush / Endless 词条 / NG+）  · P1 · 工作量 L

**目标**：给游戏一个"结局"与重玩驱动：W20 通关演出 + `GAME_CLEARED` 事件、里程碑奖励、Boss Rush/Endless 全局词条、NG+（Phase4）。

**现状（代码复核 2026-07-23）**：`scripts/` 无 `GAME_CLEARED`/`NG_PLUS`/`boss_rush`/`milestone` 任何引用（grep 零匹配）。游戏**只能靠死亡结束**；Boss 死亡已发 `BOSS_KILLED=30`（E4 可挂钩），但无通关流程。

**设计来源**：`docs/design/game_design.md §8`。

**依赖**：Boss 系统（已完成，`BOSS_KILLED` 可作通关触发）；存档系统（已在，NG+ 需扩 schema）。

**切分（建议 5 个子计划）**：
1. **通关演出 + `GAME_CLEARED` 事件**：W20 Boss 死 → `GAME_CLEARED{elapsed, wave}` → 通关结算屏（复用 settlement）。事件常量续 31。S。
2. **里程碑 W5/W10/W15**：达波次触发奖励/事件（宝箱/免费法术/属性）。S~M。
3. **Boss Rush 模式**：连续 Boss 波模式入口（复用 BossManager + waves 子集）。M。
4. **Endless 全局词条**：>W20 每 N 波抽全局增益/减益词条（正负权衡）。M。
5. **NG+（Phase4）**：通关后开启的更高难度循环，敌人/Boss 强化曲线 + 存档标记。M。

**验收标准**：W20 击杀 → 通关屏 + `GAME_CLEARED` 发出；里程碑奖励发放；Boss Rush 可进入并结算；Endless 词条按波刷新生效；NG+ 循环难度提升且可存读；MCP 实测。

---

## E5. 教程 / 引导（TutorialManager / 渐进解锁 / 靶场）  · P2 · 工作量 M

**目标**：新手引导从"仅难度选择"升级为真正教学：分步教程、内容渐进解锁、练习靶场。

**现状**：FTUE 仅难度选择（`main_menu.gd`）；无 `TutorialManager` autoload、无渐进解锁、无靶场场景。

**设计来源**：`docs/design/tutorial_design.md`。

**依赖**：解锁树可复用 `MetaProgress`。

**切分**：① TutorialManager（分步提示状态机 + 事件钩子，M）；② 渐进解锁（法术/核心按进度解锁，接 MetaProgress，S~M）；③ 靶场/练习模式（无伤害假人场景，S）。

**验收标准**：首次进入分步教学可完成；未解锁内容不出现在商店/背包；靶场可自由测试 build；MCP 实测。

---

## E6. Boss 深化（玩家无敌帧 / 场地机制 / 通关·死亡演出）  · P1 · 工作量 M

**目标**：承接已完成的 Boss 核心（阶段+7 招式+敌弹），补齐当初范围外的深度项。

**现状**：Boss 核心已完成（`95e5587`）。**未实现**：玩家无敌帧（当前敌弹单次命中即销毁、无 i-frame，多弹同帧可连扣）；场地机制（冰墙障碍 / 场地收缩，`boss_design §5.2`）；Boss 通关/死亡演出序列（`PHASE_DYING` 阶段）。

**设计来源**：`docs/technical/boss_design.md §5`。

**依赖**：ZoneManager（场地机制复用）；BossManager（已在）。

**切分（建议 3 个子计划）**：
1. **玩家无敌帧 (i-frames)**（**推荐最先做**，跨 E1/E6 受益）：PlayerStats 加短暂受击无敌窗口 + HUD 闪烁反馈；EnemyBulletManager/Boss 接触伤害尊重 i-frame。弹幕公平性前置。S。
2. **场地机制**：BossManager 招式可生成冰墙障碍（ZoneManager 阻挡区）+ 场地边界周期收缩（bosses.json 阶段字段 `arena_shrink`/`hazards`）。M。
3. **通关/死亡演出**：`PHASE_DYING` 阶段 + 死亡序列 VFX + 恢复部分 HP 的终章弹幕（final boss）。S~M，与 E4 通关演出衔接。

**验收标准**：连续受击有无敌窗口、HUD 反馈；冰墙阻挡玩家移动/子弹、场地按时收缩；Boss 死亡播放序列后才移除并触发通关（衔接 E4）；MCP 实测。

---

## E7. 渲染 / 性能 / 债务（LOD 剔除 / DamageNumber / C# 热路径 / UI .tscn 化 / i18n 债务）  · P3 · 工作量 M~L（可拆分独立小项）

**目标**：长尾优化与技术债清理，不阻塞玩法但影响手感/规模/可维护性。

**现状**：`enemy_manager.gd:25 _visible_flags` 声明却从不置 1 → 屏内剔除/低频分离力未实现；无伤害飘字（DamageNumber）；C# 热路径（BulletManagerCs/EnemyManagerCs/SpatialGridCs）为死代码（R-08 已承认）；UI 全程序化（无 `.tscn`）；i18n 债务：法术/核心/状态 `display_name`/`description` 仍硬编码未 tr 化，缺裸中文静态检查。

**设计来源**：`architecture_design.md §4.4`、R-08、ADR-A1。

**依赖**：无。各项可独立作为"缝隙任务"穿插。

**切分（独立小项）**：① DamageNumber 飘字（S，高手感回报）；② 敌人 LOD 屏内剔除 + 屏外低频分离（S~M）；③ 内容名 tr 化 + 裸中文静态检查（S，i18n 收尾）；④ UI 关键面板 `.tscn` 化（M，可选）；⑤ C# 热路径落地（L，仅当 GDScript 达性能瓶颈时；当前 500 敌 3.6% 预算，非必需）。

**验收标准**：飘字随命中显示；屏外敌人低频更新且 FPS 提升；4 语言无裸中文；MCP/截图实测。

---

## 附：立项流程

每个子计划遵循已验证的流水线（同 Boss）：
1. `superpowers:brainstorming` → 澄清范围/设计决策 → `docs_dev/specs/<date>-<feature>-design.md`（提交）。
2. `superpowers:writing-plans` → 逐任务实现计划 → `docs_dev/plans/<date>-<feature>.md`（提交）。
3. `superpowers:subagent-driven-development` → 子代理逐任务实现 + 两阶段评审 → 验收 → 合并。
4. 全程 Godot MCP 运行时实测；纯数据驱动；改动记 memory。

> 本路线图为"活文档"：完成一个 Epic/子项后在此勾除并更新现状引用。