joywayerandClaude Opus 5
d498097005
「现状」归航行与切分列表第 3 项改为完成态，格式对齐已完成的 ①②。 显式记录与本文档原方案的偏离：未消费 _enemy_pos_snapshot 而是删除之 —— 锁定式目标需 entity_id，而快照按槽位存位置、不含 id，结构上支撑不了该语义。 另记退避 + 抖动这一同期落地的性能措施（详见 spec §5）。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
181 lines
16 KiB
Markdown
181 lines
16 KiB
Markdown
# 缺失功能路线图（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）**：
|
||
- ~~元素抗性~~ ✅ **完成**（2026-07-24，`feat/element-resistance`）：`apply_damage_from_context` 按 `ctx.damage_type` 查 `_RESIST` 表传入 `calc_damage(0, res)`；`enemies.json` 每型可选 `resistances{元素名:-0.9~0.9}`（支持负=弱点加伤）；设计器敌人页加 6×5 抗性网格。MCP 实测：抗火0.5→半伤、弱冰-0.5→1.5×、抗性+护甲叠加45。⚠️ **已知限制**：DOT 伤害（`status_manager.gd:116` 直调 `apply_damage`）暂不享元素抗性（架构上 DOT 不走 context，见 E2）。（`player_stats.gd:23 resistance` 玩家侧抗性仍占位。）
|
||
- ~~连锁/弹跳~~ ✅ **完成**（2026-07-24，`feat/bullet-bounce`）：镜像 pierce 管线——`CastStats.bounce_add` → `_apply_modifier` 折叠 → `_push_projectile` 写冷数据 → `_check_collision` 命中转向最近未访问敌(`_find_nearest_unvisited`)、`damage_mult×decay` 递减、`visited_targets` 防回跳、命中循环跳过已访问防密集群重复命中。bounce 优先于 pierce（耗尽后落 pierce）。`modifier_bounce` 词条上架。MCP 实测：bounce=2→3 敌 100/90/81、速度重定向证明优先级、折叠 bounce_add=2。
|
||
- ~~归航~~ ✅ **完成**（2026-07-30，`feat/bullet-homing`）：镜像 bounce 管线——`CastStats.homing_add`(float) → `_apply_modifier` 折叠 → `_push_projectile` 写冷数据 `homing_strength/homing_range/homing_target_id` → `_gd_integrate` 在位置积分**之前**调 `_apply_homing`，用 `wrapf` 取最短转向、`clampf` 到 `strength*delta` 限角速度、`rotated()` 保速率。目标为**发射后锁定**：仅首帧与目标死亡时经 `_find_nearest_unvisited` 重选；bounce 命中重定向时改写 `homing_target_id`（bounce 选目标、homing 追上去）。`modifier_homing` 词条上架。MCP 实测见下方「⚠️ 有意偏离」与 spec §5。
|
||
- ⚠️ **有意偏离本文档原方案**：本行原写「`_gd_integrate` 消费 `_enemy_pos_snapshot`」，实现**没有**消费它，而是**删除**了 `_enemy_pos_snapshot` 及其唯一生产者 `EnemyManager.fill_pos_snapshot`。理由：最终设计采用**按 entity_id 锁定目标**（轨迹可读、目标死亡有明确判据 `get_pos_by_id` 哨兵），而该快照**按槽位存位置、不含 entity_id**，结构上支撑不了锁定语义；接上它反而要每帧 O(敌人数) 重扫最近点。净效果是**减少**一份每帧 O(敌人数) 开销。
|
||
- ⚠️ **性能**：重选**失败**路径会每帧重跑 `query_circle(r=400)`，实测 300 弹即越过 2.0 ms 线，故同期落地**退避 + 抖动**（`homing_retry_at`，`HOMING_RETRY_MS=200`）。抖动必需——朴素固定退避会把同帧失败的子弹锁进同相，尖峰每 12 帧永久复发。详见 spec §5。
|
||
- 轨迹修正（加速/曲线）：`_data +11 acceleration` 已积分，但无"转向/曲线"类修饰器写入。
|
||
|
||
**设计来源**：`docs/mechanics/combat_mechanics_depth.md §4`（抗性公式）、子弹冷数据字段。
|
||
|
||
**依赖**：无硬依赖；元素 tag 体系已在（`SpellNode.element_tags`）。敌人需有 per-type/per-status 抗性数据源（新增 `enemies.json` 抗性字段或状态减抗）。
|
||
|
||
**切分（建议 4 个子计划）**：
|
||
1. ~~**元素抗性 (1-Res)**~~ ✅ **完成**（2026-07-24，`feat/element-resistance`；spec/plan `docs_dev/{specs,plans}/2026-07-24-element-resistance*`）：enemies.json `resistances{元素名:-0.9~0.9}`；EnemyManager `_RESIST` 查表传入 `calc_damage(0,res)`；设计器 6×5 抗性网格。
|
||
2. ~~**连锁/弹跳 chain/bounce**~~ ✅ **完成**（2026-07-24，`feat/bullet-bounce`；spec/plan `docs_dev/{specs,plans}/2026-07-24-bullet-bounce*`）：冷数据 `bounce_remaining/visited_targets/decay/range`，命中转向最近未访问敌+×0.9 递减，bounce 优先于 pierce，`modifier_bounce` 词条。
|
||
3. ~~**归航 homing**~~ ✅ **完成**（2026-07-30，`feat/bullet-homing`；spec/plan `docs_dev/{specs,plans}/2026-07-30-bullet-homing*`）：冷数据 `homing_strength/homing_range/homing_target_id`，每帧以 `strength*delta` 为上限朝**锁定目标**转向（`wrapf` 最短转向 + `rotated()` 保速率），目标死亡才重选；失败退避 + 抖动（`homing_retry_at`）；bounce 协同改写目标；`modifier_homing` 词条。**偏离**：未消费 `_enemy_pos_snapshot` 而是删除之（快照按槽位存位置、不含 entity_id，支撑不了锁定语义），见上方「现状」。
|
||
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`）。✅ **玩家无敌帧已完成**（分支 `feat/player-iframes`，2026-07-24：`take_damage` 时间戳门控 0.5s 窗口 + `is_invulnerable()` + 8Hz 闪烁 + 复活 `PLAYER_DAMAGED`/hurt 音效 + 顺带修复 balance_tab `_save` 丢键；时长入 `balance.json` `player_iframe_sec`）。**未实现**：场地机制（冰墙障碍 / 场地收缩，`boss_design §5.2`）；Boss 通关/死亡演出序列（`PHASE_DYING` 阶段）。
|
||
|
||
**设计来源**：`docs/technical/boss_design.md §5`。
|
||
|
||
**依赖**：ZoneManager（场地机制复用）；BossManager（已在）。
|
||
|
||
**切分（建议 3 个子计划）**：
|
||
1. ~~**玩家无敌帧 (i-frames)**~~ ✅ **完成**（2026-07-24，`feat/player-iframes`）：PlayerStats 时间戳无敌窗口 + HUD 闪烁反馈；所有外部伤害（敌弹/Boss 接触/近战）经 `take_damage` 单点尊重 i-frame。spec/plan：`docs_dev/{specs,plans}/2026-07-24-player-iframes*`。
|
||
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/子项后在此勾除并更新现状引用。
|