spellforge/docs_dev/specs/2026-07-21-mana-complete-design.md

Mana 完整化设计规范（可发布）

日期：2026-07-21 · 状态：设计已确认，待写实现计划 背景：Mana 精实 MVP（蓝池/逐节点扣蓝/蓝空停施/回蓝/HUD 蓝条/编辑器可调）已上线。本规范把 Mana 补成可发布的完整功能：加入 3 个 Mana 定义性机制 + UI 打磨 + 平衡。 数据驱动原则：所有可调数值入 balance.json（平衡页签可调）/ cores.json（Core 编辑器）/ spells.json（法术编辑器），不硬编码。

---

1. 范围

本次包含：

• P1 递增蓝耗：连续高射速堆"热"，蓝耗随热上涨；停火/慢射衰减。防"无限蓝机枪"。
• P2 infinite_spells 特性 + heavy_cost 修正器：蓝空时不停施、扣 HP 续命（卖血流），单次 HP 上限 15% max HP。
• P3 魔力虹吸（多来源）：击杀回蓝；来源 = Core 基础值 + 卡组内法术 meta.mana_leech 之和（+ 未来属性货架加成）。
• P4 UI 打磨：蓝条叠数字、低蓝反馈、过热提示、UI_MANA 四语键。
• P5 平衡：调基础杖续航手感（可持续突突、但堆射速会憋蓝）。

明确不做：cast_delay 施法后摇重构（独立战斗节奏系统）、全局蓝池+法杖取 Min、过热强制冷却（用 P1 递增蓝耗替代）、§5.E 双重 HP 组合的 UI 警告（可选，留后续）。

---

2. P1 递增蓝耗

2.1 状态与参数

• PlayerStats.mana_heat: float = 0.0（0 = 无热，1.0 = 蓝耗翻倍）。
• balance.json："mana_heat": { "per_cast": 0.01, "decay_per_sec": 0.1, "max": 1.0 }；SettingsManager 加载 + getters mana_heat_per_cast/_decay/_max()（缺字段回退默认）。

2.2 逻辑

• 扣蓝乘算：SpellEvaluator.execute_compiled 开头取 heat_mult = 1.0 + PlayerStats.mana_heat；每个节点扣蓝时 实际蓝耗 = base_mana_cost × heat_mult。
• 堆热：cast_fired = 本次至少成功扣了一次蓝 或 触发了一次 infinite 扣血（即真的打出了东西）；为真则 execute_compiled 末尾 mana_heat = min(max, mana_heat + per_cast)。完全被蓝空拦下（非 infinite、首节点就付不起）→ 不堆热。
• 衰减：PlayerManager._physics_process 每帧 PlayerStats.mana_heat = max(0.0, mana_heat - decay_per_sec × delta)（无条件衰减）。
• 效果：慢杖(2/s)每秒 +0.02 vs 衰减 −0.1 → 热≈0；机枪杖(20/s)每秒 +0.2 vs −0.1 → 堆至 cap，蓝耗翻倍节流。只惩罚真机枪流。

---

3. P2 infinite_spells + heavy_cost

3.1 数据

• cores.json 加 wand_eternal（传说）：feature_tags = 5（CoreFeatureTag.INFINITE_SPELLS，单选枚举值），mana_max 较低（如 40，逼迫卖血）。
• spells.json 加 modifier_heavy_cost（鲜血献祭）：{ "type": 1, "meta": { "heavy_cost": 10, "damage_add": 50, "mana_cost": 0, "shop_cost": 26 } }。
• balance.json："infinite_spells": { "hp_per_shot": 1.0, "hp_cost_cap_ratio": 0.15 }；SettingsManager getters。

3.2 逻辑（SpellEvaluator）

• SpellContext 加 hp_cost_accum: float = 0.0；reset() 归零。
• _apply_modifier：if meta.has("heavy_cost"): ctx.hp_cost_accum += float(meta["heavy_cost"])（主动构建代价，先累加）。
• 扣蓝门控统一为 helper _charge_mana(base_cost: float, ctx, infinite: bool, heat_mult: float) -> bool：

  if base_cost <= 0.0: return true
  if PlayerStats.spend_mana(base_cost * heat_mult): return true
  if infinite:
      ctx.hp_cost_accum += SettingsManager.infinite_hp_per_shot()   # 蓝空 → 每发扣 HP，继续
      return true
  return false   # 非 infinite → 停施
  

  三处门控点（主循环 / _run_logic_loop / _run_branch_payload）都改调 _charge_mana(...)，infinite 与 heat_mult 在 execute_compiled 开头计算（infinite = compiled.feature_tags == CoreFeatureTag.INFINITE_SPELLS）并传入。
• 施法末结算 HP 代价：var hp_cost = minf(ctx.hp_cost_accum, PlayerStats.hp_max * cap_ratio)；if hp_cost > 0.0: PlayerStats.spend_hp_cost(hp_cost)。
• PlayerStats.spend_hp_cost(amount)：直接扣血（主动代价，不走难度减伤 take_damage）：hp = max(0.0, hp - amount)；stats_changed.emit()；hp<=0 → emit PLAYER_DIED。
• §5.E 一致：heavy_cost 先记 10，蓝空再 +1，同帧上限 15% max HP（cap 兜底）。

---

4. P3 魔力虹吸（多来源击杀回蓝）

4.1 状态与来源

• PlayerStats.mana_leech: float = 0.0（计算值，装备/换牌时重算）。
• CoreDefinition.base_mana_leech: float = 0.0（cores.json.mana_leech，Core 编辑器加一栏，续航型 Core 带之；如 wand_eternal 给 2）。
• 法术 meta.mana_leech（如新增「魔力虹吸」MODIFIER modifier_mana_leech：meta:{mana_leech:2, mana_cost:0, shop_cost:22}，放卡组即生效）。

4.2 逻辑

• 重算点：combat_manager._rebuild_wand()（已有 core + 原始 nodes）末尾：

  var leech: float = _equipped_core.base_mana_leech if _equipped_core else 0.0
  for n in nodes:
      if n != null: leech += float(n.meta.get("mana_leech", 0.0))
  PlayerStats.mana_leech = leech
  

• 击杀回蓝：PlayerStats _ready 订阅 ENEMY_KILLED → gain_mana(mana_leech)；func gain_mana(n): if n>0: mana = min(mana_max, mana + n)（emit stats_changed）。
• 求和天然叠加：换更高 base 的 Core、或卡组塞多张 leech 卡都能提升。为未来属性货架 C 留 + 加成 接口（现为 0）。

---

5. P4 UI 打磨（combat_s2 HUD）

• 蓝条数字：在 _mana_bar 上叠一个居中 Label，_refresh_hud 里 = tr("UI_MANA") % [int(PlayerStats.mana), int(PlayerStats.mana_max)]（如 "蓝 40/100"）。新增 UI_MANA 四语键。
• 低蓝反馈：_refresh_hud 里 mana/mana_max < 0.2 时把蓝条 fill 颜色改暗红并轻微闪烁（用 sin(time) 调 alpha），否则蓝色。
• 过热提示：mana_heat > 0.01 时蓝条边框/自身 modulate 泛红（热越高越红），直观显示"憋蓝中"。
• 纯表现层，读 PlayerStats，不反向依赖。

---

6. P5 平衡（数值，编辑器可调）

• 现状基础杖续航偏紧（spark 5/发 × 2/s = 10 vs 回蓝 5 → 净耗）。目标手感：基础杖能持续突突基础弹，但堆射速/用贵法术会憋蓝。
• 调整入口（数据驱动、MCP 实测手感）：cores.json 基础 mana_regen（如 5→8）、spells.json spark mana_cost（如 5→3），保留递增蓝耗对机枪流的惩罚。
• 不写死结论；实现时用 MCP 起战斗观测蓝条曲线与手感，落到数据。

---

7. 边界

• mana_heat 不入存档（战斗态，开局/换杖清零）；换杖 equip_wand 时 PlayerStats.mana_heat = 0.0。
• hp_cost_accum 每次施法 reset，防池化残留。
• 非 infinite Core 行为与现状完全一致（蓝空 break）；heavy_cost 卡在非 infinite 杖上仍扣 HP（主动代价，符合设计"卖血流"）。
• mana_leech 换杖/换牌必重算，防旧值残留；卡组为空/无 leech → 0。
• SubPayload 命中执行（execute_sub）保持不扣蓝、不受热/infinite/heavy_cost 影响（同 MVP，仅主施法流承担资源）。

---

8. 测试计划（Godot MCP 运行时实测）

1. 递增蓝耗堆积/衰减：模拟连续施法 N 次 → mana_heat 上升并封顶 max；停手若干帧 → 衰减回 0；heat=0.5 时 spark 实扣蓝 = 5×1.5=7.5。
2. infinite_spells 扣血：装 wand_eternal(feature=5, 低蓝)，mana=0 施 spark → 不停施、hp 下降、单次 HP ≤ 15% max。
3. heavy_cost 叠加：deck [modifier_heavy_cost, action] 施一次 → hp −10（+若蓝空再 −1）；上限 15% 生效。
4. 魔力虹吸多来源：Core base_mana_leech=2 + 卡组含 modifier_mana_leech(2) → PlayerStats.mana_leech=4；发 ENEMY_KILLED → mana +4（封顶 max）。
5. 回归：既有 MVP（逐节点扣蓝/停施/LOOP扣蓝/持久内存 [0,0,1,0]）在加乘算后仍正确（heat=0 时行为不变）。
6. UI：截图确认蓝条数字、低蓝暗红、过热泛红。
7. 平衡：起战斗观测基础杖蓝条能维持基础弹、堆射速会见底。

---

9. 涉及文件清单

文件	改动
scripts/autoloads/player_stats.gd	+mana_heat/mana_leech；gain_mana/spend_hp_cost；订阅 ENEMY_KILLED 回蓝
scripts/domain/spell_system/core_definition.gd	+base_mana_leech
scripts/autoloads/wand_preset.gd	读 mana_leech
scripts/domain/spell_system/spell_context.gd	+hp_cost_accum + reset
scripts/domain/spell_system/spell_evaluator.gd	_charge_mana helper（heat 乘算 + infinite 扣血）；三处门控改调；heavy_cost 累加；施法末 HP 结算 + heat 堆积
scripts/domain/player_manager.gd	每帧衰减 mana_heat；equip 清零 heat
scripts/domain/combat/combat_manager.gd	_rebuild_wand 重算 mana_leech
scripts/autoloads/settings_manager.gd	加载 mana_heat/infinite_spells 配置 + getters
data/balance.json	+mana_heat/infinite_spells 配置
data/cores.json	+wand_eternal；相关 Core +mana_leech；平衡回蓝
data/spells.json	+modifier_heavy_cost / modifier_mana_leech；平衡 spark 蓝耗
scenes/main/combat_s2.gd	HUD 蓝条数字 + 低蓝/过热反馈
addons/game_designer/core_tab.gd	Core 编辑器 +mana_leech 栏（编辑器可调）
translations/*.po	UI_MANA 四语键

---

10. 完成定义 (DoD)

• 上述 7 项测试运行时全绿、0 编译错误。
• 递增蓝耗只惩罚高射速流；慢杖手感不变。
• wand_eternal 蓝空能卖血续命、单次 HP ≤ 15%；heavy_cost 卡生效。
• 魔力虹吸 Core 与法术卡两条路都能续航、可叠加、编辑器可调。
• HUD 蓝条有数字 + 低蓝/过热反馈。
• 基础杖续航手感调到位。
• numerical_design §5.A、core_wand_design §3（infinite_spells）、game_design §4.1/§4.3 的 Mana 现状 callout 更新。