spellforge/docs_dev/specs/2026-07-20-mana-system-mvp-design.md

# Mana 魔力系统 —— 精实 MVP 设计规范

> **日期**：2026-07-20 · **状态**：设计已确认，待写实现计划
> **背景**：Mana 是 `game_design §4.1` 声称的核心平衡阀（限制"无限加特林"），但代码 0% 实现——无 `mana` 变量、无 `mana_cost` 数据，连 `CoreDefinition` 都缺 mana 字段。本规范定义"精实 MVP"：让 Mana 成为真实可玩的资源门槛，暂不实现进阶反作弊/边缘机制。

---

## 1. 目标与范围

**目标**：法术施放消耗魔力；魔力随时间回复；魔力耗尽时停止施法，形成"高射速/高爆发 ↔ 魔力"的平衡张力，并有 HUD 蓝条可视化。

**本次 MVP 包含**：
- 单一魔力池（取自当前激活法杖 Core 的 `mana_max` + `mana_regen/秒`）。
- 每个法术节点消耗其 `mana_cost`（按 `numerical_design §2` 权威数值）。
- 施法时逐节点扣蓝；某节点付不起 → **停下本次施法，跳过剩余节点**（已发射的动作保留）。
- HUD 蓝条。
- `cores.json` 加 mana 字段、`spells.json` 加 `mana_cost`、`CoreDefinition` 加字段。

**明确不做（后续迭代）**：
- 持续射击**递增蓝耗**（`numerical §5.A` 反"无限蓝机枪"）。
- `infinite_spells` Core 蓝空时**扣 HP**。
- **全局蓝池 + 法杖上限取 Min**（MVP 只有法杖单池）。
- `cast_delay`/施法后摇重构（保持现有 `cast_interval` 自动施法节奏不变）。

---

## 2. 架构：组件与职责

数据状态、回蓝驱动、消耗门控三者分离，各自单一职责。

### 2.1 `PlayerStats`（Autoload）—— 魔力状态与操作
新增字段与方法：
```
var mana:        float = 100.0
var mana_max:    float = 100.0
var mana_regen:  float = 5.0     # 每秒回复

func set_mana_pool(max_v: float, regen: float) -> void   # 换杖时调用，重置 max/regen 并把 mana 夹到 [0,max]
func spend_mana(cost: float) -> bool                     # 够则扣除返回 true，否则不变返回 false
func regen_mana(delta: float) -> void                    # mana = min(mana_max, mana + mana_regen*delta)；变化时 emit stats_changed
```
- `mana` 纳入 `stats_changed`（HUD 刷新用）。
- `reset_for_run()` 增加 `mana = mana_max`（开局满蓝）。
- **不纳入存档**（`get_save_data`/`load_save_data` 不含 mana）——回蓝以秒计，续玩从满蓝开始即可。
- 职责边界：只管"当前有多少蓝、能不能花、怎么回"，不知道谁在花。

### 2.2 `CoreDefinition`（+2 字段）
```
@export var base_mana_max:   float = 100.0
@export var base_mana_regen: float = 5.0
```
由 `WandPreset.make_core_by_id()` 从 `cores.json` 读入（缺省用上面默认值，向后兼容旧数据）。

### 2.3 `PlayerManager`（Autoload）—— 驱动
- `equip_wand(core, compiled)`：新增 `PlayerStats.set_mana_pool(core.base_mana_max, core.base_mana_regen)`（core 为 null 时用默认）。
- `_physics_process(delta)`：新增一行 `PlayerStats.regen_mana(delta)`（回蓝持续进行，含商店/施法间隙）。
- 职责边界：帧驱动器，只负责"按时回蓝、按时触发施法"，不持有蓝量。

### 2.4 `SpellEvaluator.execute_compiled`（消耗门控）

**核心规则：扣蓝发生在节点效果"实际生效处"，而非盲目逐个遍历**——否则会给被控制流跳过、并未真正发射的节点误扣蓝（现有语义"每次施法仅首个 ACTION 生效，除非 multicast/double_cast"）。

具体扣蓝点：
- **ACTION** 实际发射时（`_push_projectile` 及其 zone/summon 变体）扣其 `mana_cost`；若付不起 → **不发射该动作，且中止本次施法剩余部分**。
- **MODIFIER** 在 `_apply_modifier` 应用时扣其 `mana_cost`；付不起同样中止。
- **TRIGGER** 注册 SubPayload 时扣其 `mana_cost`；命中后 SubPayload（`execute_sub`，异步 on-hit）执行**不再扣蓝**（MVP 简化，避免命中回调里做资源判定）。
- **被控制流跳过的节点不扣蓝**：超出 `actions_remaining` 的 ACTION、被 LOGIC 门跳过的分支、被共鸣 `_consumed` 标记的输入卡，均不产生蓝耗。
- **中止信号机制**（`ctx` 上的 depleted 标志位 vs 效果函数返回 bool 令主循环 break）留实现计划敲定；语义目标一致：一旦某要生效的节点付不起蓝，本次施法就此打住，已生效部分保留。
- **施法时立即执行的路径都消耗魔力**：`execute_compiled` 主循环、**LOOP 体（`_run_logic_loop`）**、**CIRCUIT 分支（`_run_branch_payload`）** 均逐节点扣蓝、蓝空即停（复审发现 LOOP/CIRCUIT 曾漏扣、已修 `8b9565e`）；唯 **SubPayload 的 on-hit 执行（`execute_sub`）不消耗**——命中回调不做资源判定。

### 2.5 `combat_s2` HUD —— 蓝条
- 在 HUD 区新增蓝色 `ProgressBar`（或等效控件），`max_value = PlayerStats.mana_max`、`value = PlayerStats.mana`。
- 订阅 `PlayerStats.stats_changed` 刷新（HUD 已订阅该信号刷新其他数值）。
- 文案键走 i18n（如需文字标签，新增 `UI_MANA` 四语键）。

---

## 3. 数据流

```
装备法杖 → PlayerStats 蓝池置满(max/regen 来自 Core)
   │
每帧 → PlayerManager.regen_mana(delta) → 蓝量上升至 max
   │
每 cast_interval 秒 → PlayerManager 触发 execute_compiled
   │
execute_compiled 逐节点 → spend_mana(cost)？付得起就执行，付不起就 break
   │
stats_changed → HUD 蓝条更新
```

---

## 4. 数值（权威来源 `numerical_design §2`）

**基础法杖**：`mana_max = 100`、`mana_regen = 5/秒`。

**每法术 `mana_cost`**（doc ID → 实际 data ID 映射）：
| doc §2 | 实际 spells.json id | mana_cost |
| :--- | :--- | :--- |
| spark_bolt | action_spark_bolt | 5 |
| double_cast | modifier_double_cast | 2 |
| spread_mod | modifier_spread_mod | 0 |
| damage_plus | modifier_damage_plus | 15 |
| trigger_hit | trigger_on_hit | 10 |
| chain_bolt | action_chain_bolt | 60 |
| nuke | (若存在) action_nuke | 200 |
| homing | (若存在) modifier_homing | 40 |

**赋值规则**（`spells.json` 中未被 §2 列出的法术）：按类型/Tier 给缺省——
- LOGIC / 纯控制节点：0
- 小修正（如 pierce+）：~8
- Tier1 ACTION：5–10；Tier2 ACTION：20–30；Tier3 ACTION：60+
- 召唤/地面（poison_pool / summon_turret）：~25–35
- 共鸣产物（plasma_storm，不在商店）：0；且被 `_consumed` 标记的输入卡按 §2.4 不扣蓝 → **共鸣在 MVP 里整体免蓝**，作为凑出组合的奖励（可接受；后续如需再收费另议）

> 实现时以实际 `data/spells.json` 的完整 id 列表为准逐条填 `meta.mana_cost`；本表为权威值锚点。

---

## 5. 边界与默认（已确认）

- **开局/开波满蓝**：`reset_for_run` 置满；波间在商店持续回蓝。
- **不存档**：续玩从满蓝开始。
- **蓝空施法**：本次施法不产出任何东西，但 `cast_timer` 照常重置——形成"憋蓝"手感门槛。
- **`nuke`(200) > 基础 max(100)**：基础法杖无法施放核弹，须换更高蓝上限的 Core（有意的构建门槛）。
- **换杖夹值**：`set_mana_pool` 把当前 `mana` 夹到新 `[0, max]`。

---

## 6. 测试计划（Godot MCP 运行时实测，同 bug 修复流程）

1. **回蓝**：`mana` 从低值随时间上升并封顶于 `mana_max`。
2. **逐节点扣蓝**：满蓝下施放 `[modifier_damage_plus(15), action_spark_bolt(5)]` → `mana` 减少 20。
3. **停下跳过（首节点付不起）**：`mana=3`、deck `[action_spark_bolt(5), ...]` → 无子弹产出（`BulletManager.get_active_count()==0`）。
4. **部分施放**：`mana=8`、deck `[spark(5), spark(5)]` + double_cast 令两发都尝试 → 第 1 发发射、第 2 发被跳过。
5. **HUD**：蓝条 `value` 随施放/回蓝变化；截图确认蓝条渲染。
6. **回归**：既有法术链（伤害、pierce、persistent memory `[0,0,1,0]`）在加入扣蓝后行为不变（付得起时）。

---

## 7. 涉及文件清单

| 文件 | 改动 |
| :--- | :--- |
| `scripts/autoloads/player_stats.gd` | +mana 状态/方法、reset/stats_changed 集成 |
| `scripts/domain/spell_system/core_definition.gd` | +`base_mana_max`/`base_mana_regen` |
| `scripts/autoloads/wand_preset.gd` | 从 cores.json 读入两字段 |
| `scripts/domain/player_manager.gd` | equip 时置池、_physics_process 回蓝 |
| `scripts/domain/spell_system/spell_evaluator.gd` | execute_compiled 逐节点扣蓝门控 |
| `scenes/main/combat_s2.gd` | HUD 蓝条 + stats_changed 刷新 |
| `data/cores.json` | 每 Core +mana_max/mana_regen |
| `data/spells.json` | 每法术 +mana_cost |
| `translations/*.po` | （如需）`UI_MANA` 四语键 |

---

## 8. 完成定义 (DoD)

- 上述 6 项测试在 Godot 4.6 运行时全部通过、0 编译错误。
- 基础法杖满蓝 100、回蓝 5/s；连打 spark_bolt 会见蓝下降并在停火后回满。
- 纯 Modifier 或蓝不足时不产出子弹（与既有 Deck 防呆互补）。
- HUD 蓝条可见并实时反映蓝量。
- 文档 `numerical_design`/`core_wand_design` 的 Mana 现状 callout 更新为"已实现（MVP）"。