joywayerandClaude Opus 4.8
150ec7aa1c
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
147 lines
9.8 KiB
Markdown
147 lines
9.8 KiB
Markdown
# 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 更新。
|