docs(plan): E6-a 玩家无敌帧逐任务实现计划（5 任务 · TDD-MCP 实测）

docs_dev/plans/2026-07-24-player-iframes.md

@@ -0,0 +1,383 @@
+# 玩家无敌帧（i-frames）Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 玩家受击后获得数据驱动的短暂无敌窗口，杜绝多弹同帧连扣血，并复活当前失效的 hurt 受击反馈。
+
+**Architecture:** 单点集中在 `PlayerStats.take_damage()` 用 `Time.get_ticks_msec()` 时间戳门控（无每帧 tick）；时长入 `balance.json` → `SettingsManager` 访问器；`combat_s2._process` 每帧读 `is_invulnerable()` 驱动玩家节点闪烁；`take_damage` 复活 `PLAYER_DAMAGED` emit（连带 `audio_manager` 的 hurt 订阅）。
+
+**Tech Stack:** Godot 4.7.1 Mono / GDScript / 纯 JSON 数据驱动 / godot-mcp-pro 运行时实测（本工程无 pytest；autoload 逻辑经 `execute_game_script` 在运行中的战斗场景断言，编辑器侧数据/设计器经 `execute_editor_script` + `validate_script`）。
+
+> **规范**：所有 `.gd` 改动后 `validate_script`；纯数据驱动无硬编码时长副本；提交信息中文；分支 `feat/player-iframes`（已建）。spec：`docs_dev/specs/2026-07-24-player-iframes-design.md`。
+
+---
+
+### Task 1: 数据层 —— balance.json 键 + SettingsManager 访问器
+
+**Files:**
+- Modify: `data/balance.json`
+- Modify: `scripts/autoloads/settings_manager.gd`（成员变量区 :34-38、`_load_balance` 尾 :91-93、访问器区 :66-70）
+
+- [ ] **Step 1: balance.json 增顶层键**
+
+在 `data/balance.json` 的 `infinite_spells` 之后新增一行（同级顶层键）：
+
+```json
+  "infinite_spells": { "hp_per_shot": 1.0, "hp_cost_cap_ratio": 0.15 },
+  "player_iframe_sec": 0.5
+```
+
+（注意给 `infinite_spells` 行补逗号。最终顶层键顺序：difficulty_mults, boss_hp, aether_thresholds, mana_heat, infinite_spells, player_iframe_sec。）
+
+- [ ] **Step 2: SettingsManager 增成员变量**
+
+在 `settings_manager.gd:38`（`var _INFINITE...` 之后）新增：
+
+```gdscript
+var _IFRAME_SEC: float = 0.5   # 玩家受击无敌窗口（秒）；balance.json player_iframe_sec
+```
+
+- [ ] **Step 3: `_load_balance` 读取该键**
+
+在 `settings_manager.gd` 的 `_load_balance()` 末尾（现 :91-93 `infinite_spells` 块之后）追加：
+
+```gdscript
+	if data.has("player_iframe_sec"):
+		_IFRAME_SEC = float(data["player_iframe_sec"])
+```
+
+- [ ] **Step 4: 增访问器**
+
+在 `settings_manager.gd:70`（`hp_cost_cap_ratio()` 之后）新增：
+
+```gdscript
+func player_iframe_sec() -> float:    return _IFRAME_SEC
+```
+
+- [ ] **Step 5: 校验语法**
+
+Run: godot-mcp-pro `validate_script` on `res://scripts/autoloads/settings_manager.gd`
+Expected: 无错误。
+
+- [ ] **Step 6: 校验 JSON + 访问器（编辑器脚本）**
+
+Run: godot-mcp-pro `execute_editor_script`：
+
+```gdscript
+var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/balance.json"))
+var ok := d is Dictionary and d.has("player_iframe_sec") and abs(float(d["player_iframe_sec"]) - 0.5) < 0.0001
+print("FAILS=", 0 if ok else 1, " val=", d.get("player_iframe_sec"))
+```
+
+Expected: `FAILS=0 val=0.5`
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add data/balance.json scripts/autoloads/settings_manager.gd
+git commit -m "feat(iframe): balance.json 增 player_iframe_sec 键 + SettingsManager 访问器（默认0.5s）"
+```
+
+---
+
+### Task 2: 核心 —— PlayerStats 无敌帧门控 + 复活 PLAYER_DAMAGED + 移除死订阅
+
+**Files:**
+- Modify: `scripts/autoloads/player_stats.gd`（成员区 :22-23、`_ready` :32-34、`take_damage` :65-69、`_on_player_damaged` :116-117、`reset_for_run` :119-126）
+
+- [ ] **Step 1: 增无敌窗口成员变量**
+
+在 `player_stats.gd:23`（`var resistance...` 之后）新增：
+
+```gdscript
+var _invuln_until_msec: int = 0   # < now 表示可受击；受击后设为 now + iframe 窗口
+```
+
+- [ ] **Step 2: 改写 `take_damage` 加门控 + emit**
+
+将 `player_stats.gd:65-69` 的 `take_damage` 整体替换为：
+
+```gdscript
+func take_damage(amount: float) -> void:
+	var now: int = Time.get_ticks_msec()
+	if now < _invuln_until_msec:
+		return  # 无敌窗口内：忽略外部伤害（多弹同帧只扣一次）
+	var applied: float = amount * SettingsManager.player_dmg_taken_mult()  # 难度减伤（初学者×0.7）
+	hp = max(0.0, hp - applied)
+	_invuln_until_msec = now + int(SettingsManager.player_iframe_sec() * 1000.0)
+	EventBus.emit(EventID.PLAYER_DAMAGED, {"damage": applied})  # 复活 hurt 音效 / HUD 钩子
+	stats_changed.emit()
+	if hp <= 0.0:
+		EventBus.emit(EventID.PLAYER_DIED, {})
+```
+
+- [ ] **Step 3: 增 `is_invulnerable()` 查询**
+
+在改写后的 `take_damage` 之后新增：
+
+```gdscript
+func is_invulnerable() -> bool:
+	return Time.get_ticks_msec() < _invuln_until_msec
+```
+
+- [ ] **Step 4: 移除死订阅（避免 emit 自递归）**
+
+删除 `player_stats.gd:33` 的这一行：
+
+```gdscript
+	EventBus.subscribe(EventID.PLAYER_DAMAGED, _on_player_damaged)
+```
+
+并删除 `player_stats.gd:116-117` 的整个 `_on_player_damaged` 函数：
+
+```gdscript
+func _on_player_damaged(payload: Dictionary) -> void:
+	take_damage(float(payload.get("damage", 0.0)))
+```
+
+（`_ready` 保留 `ENEMY_KILLED` 订阅不动。）
+
+- [ ] **Step 5: `reset_for_run` 重置无敌窗口**
+
+在 `player_stats.gd` 的 `reset_for_run()` 内（`stats_changed.emit()` 之前）新增一行：
+
+```gdscript
+	_invuln_until_msec = 0
+```
+
+- [ ] **Step 6: 校验语法**
+
+Run: godot-mcp-pro `validate_script` on `res://scripts/autoloads/player_stats.gd`
+Expected: 无错误（确认 `_on_player_damaged` 已无引用残留）。
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add scripts/autoloads/player_stats.gd
+git commit -m "feat(iframe): PlayerStats.take_damage 时间戳门控无敌窗口 + 复活 PLAYER_DAMAGED emit；移除死订阅"
+```
+
+---
+
+### Task 3: 视觉反馈 —— combat_s2 无敌期玩家闪烁
+
+**Files:**
+- Modify: `scenes/main/combat_s2.gd`（`_process` 尾 :99-104、`_player_node` 成员）
+
+- [ ] **Step 1: 确认 `_player_node` 成员存在**
+
+Run: `grep -n "_player_node" scenes/main/combat_s2.gd`
+Expected: 见成员声明 + `_setup_player` 赋值（:112）。若无成员声明则在类顶部 var 区补 `var _player_node: Node2D = null`（`_setup_player` 已用它，通常已声明）。
+
+- [ ] **Step 2: 在 `_process` 末尾追加闪烁驱动**
+
+在 `combat_s2.gd` 的 `_process(delta)` 末尾（现 DPS 轮询块 :100-104 之后）追加：
+
+```gdscript
+	# 无敌帧闪烁反馈：8Hz 方波（相位来自系统时钟，避免累加状态）
+	if _player_node:
+		if PlayerStats.is_invulnerable():
+			var on: bool = (Time.get_ticks_msec() / 62) % 2 == 0   # ≈8Hz（62ms 半周期）
+			_player_node.modulate.a = 1.0 if on else 0.35
+		elif _player_node.modulate.a != 1.0:
+			_player_node.modulate.a = 1.0   # 窗口结束确保恢复不透明
+```
+
+- [ ] **Step 3: 校验语法**
+
+Run: godot-mcp-pro `validate_script` on `res://scenes/main/combat_s2.gd`
+Expected: 无错误。
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add scenes/main/combat_s2.gd
+git commit -m "feat(iframe): 无敌期间玩家节点 8Hz 方波闪烁反馈"
+```
+
+---
+
+### Task 4: 设计器 —— 平衡页 player_iframe_sec 输入栏（含防丢键修复）
+
+**Files:**
+- Modify: `addons/game_designer/balance_tab.gd`（成员 :11-16、`_ready` 尾 :55-57、`_save` :63-77）
+
+> **说明**：现 `_save()` 用全新 dict 输出，会**丢弃** `mana_heat`/`infinite_spells` 键（违反 CLAUDE.md 设计器「防丢键」约定）。本任务顺带修复：`_save` 以 `_data` 副本为基底合并已知键，既保留未知键又加入新键。
+
+- [ ] **Step 1: 增成员变量**
+
+在 `balance_tab.gd:16`（`var _status: Label` 之前）新增：
+
+```gdscript
+var _iframe: SpinBox
+```
+
+- [ ] **Step 2: `_ready` 增输入栏**
+
+在 `balance_tab.gd` 的 `_ready()` 内、保存按钮（`add_child(UI.btn("💾 保存 balance.json", _save))`，现 :56）**之前**插入：
+
+```gdscript
+	add_child(HSeparator.new())
+	var hf := HBoxContainer.new(); add_child(hf)
+	hf.add_child(UI.cell_label("无敌帧时长(秒) player_iframe_sec"))
+	_iframe = UI.spin(0.0, 2.0, 0.05, float(_data.get("player_iframe_sec", 0.5)))
+	hf.add_child(_iframe)
+```
+
+- [ ] **Step 3: 改写 `_save` 为合并式（防丢键 + 写入新键）**
+
+将 `balance_tab.gd:63-77` 的 `_save` 整体替换为：
+
+```gdscript
+func _save() -> void:
+	var mults: Dictionary = {}
+	for key in MULT_KEYS:
+		var spins: Array = _mult_spins[key]
+		mults[key] = [spins[0].value, spins[1].value, spins[2].value]
+	var out: Dictionary = _data.duplicate(true)   # 基底保留未知键（mana_heat/infinite_spells 等）
+	out["difficulty_mults"] = mults
+	out["boss_hp"] = {"4": _miniboss.value, "5": _boss.value}
+	out["aether_thresholds"] = _aether.get_values()
+	out["player_iframe_sec"] = _iframe.value
+	if UI.save_json(PATH, out):
+		UI.set_status(_status, "💾 已保存（重启 F5 生效）")
+	else:
+		UI.set_status(_status, "✗ 保存失败", true)
+```
+
+- [ ] **Step 4: 校验语法**
+
+Run: godot-mcp-pro `validate_script` on `res://addons/game_designer/balance_tab.gd`
+Expected: 无错误。
+
+- [ ] **Step 5: 设计器读写往返实测**
+
+> ⚠️ dock 内驻留旧类需 `EditorInterface.restart_editor(true)` 清缓存后新代码才生效（见 CLAUDE.md）。若断言用旧类失败，先重启编辑器再跑。
+
+Run: godot-mcp-pro `execute_editor_script`：
+
+```gdscript
+var Tab = load("res://addons/game_designer/balance_tab.gd")
+var t = Tab.new(); add_child(t)   # 触发 _ready 从 balance.json 装载
+await get_tree().process_frame
+var fails := 0
+# 读：SpinBox 应等于文件值 0.5
+if abs(t._iframe.value - 0.5) > 0.0001: fails += 1
+# 写往返：改值→_save→重读文件应一致，且未知键 mana_heat/infinite_spells 保留
+t._iframe.value = 0.65
+t._save()
+var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/balance.json"))
+if abs(float(d.get("player_iframe_sec", -1)) - 0.65) > 0.0001: fails += 1
+if not (d.has("mana_heat") and d.has("infinite_spells")): fails += 1   # 防丢键
+# 复原为 0.5
+t._iframe.value = 0.5; t._save()
+t.queue_free()
+print("FAILS=", fails)
+```
+
+Expected: `FAILS=0`（并确认文件 `player_iframe_sec` 复原为 0.5、mana_heat/infinite_spells 仍在）。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add addons/game_designer/balance_tab.gd
+git commit -m "feat(iframe): 设计器平衡页增 player_iframe_sec 栏；_save 改合并式修复丢键"
+```
+
+---
+
+### Task 5: 验收 —— 运行时集成实测（MCP）
+
+**Files:** 无（纯运行时断言）
+
+> 目标：在真实运行的战斗场景验证 spec §4 全部验收标准。
+
+- [ ] **Step 1: 启动战斗场景**
+
+Run: godot-mcp-pro `play_scene` → `res://scenes/main/combat_s2.tscn`（若该场景需先建 run 状态，改用工程默认主场景进入战斗；确认玩家已生成、`PlayerManager.get_position()` 有效）。
+Expected: 场景运行，无编辑器错误。
+
+- [ ] **Step 2: 多弹同帧只扣一次血（验收①②）**
+
+Run: godot-mcp-pro `execute_game_script`：
+
+```gdscript
+PlayerStats._invuln_until_msec = 0
+PlayerStats.hp = 100.0
+var p: Vector2 = PlayerManager.get_position()
+# 同一帧在玩家身上生成 5 颗敌弹（各 10 伤）
+for k in 5:
+	EnemyBulletManager.spawn_bullet(p, Vector2.ZERO, 5.0, 4.0, 10.0)
+await get_tree().physics_frame        # 让 EnemyBulletManager._physics_process 处理命中
+await get_tree().physics_frame
+var dmg := 100.0 - PlayerStats.hp
+var one_hit := 10.0 * SettingsManager.player_dmg_taken_mult()
+var fails := 0
+if abs(dmg - one_hit) > 0.01: fails += 1   # 只扣一次
+if not PlayerStats.is_invulnerable(): fails += 1   # 受击后处于无敌
+print("FAILS=", fails, " dmg=", dmg, " expected_one=", one_hit)
+```
+
+Expected: `FAILS=0`，`dmg` ≈ 单次伤害（标准难度 10.0）。
+
+- [ ] **Step 3: 窗口到期后可再次受击（验收②）**
+
+Run: godot-mcp-pro `execute_game_script`：
+
+```gdscript
+PlayerStats._invuln_until_msec = 0
+PlayerStats.hp = 100.0
+PlayerStats.take_damage(10.0)
+var after_first := PlayerStats.hp
+await create_tween().tween_interval(SettingsManager.player_iframe_sec() + 0.1).finished
+PlayerStats.take_damage(10.0)
+var fails := 0
+if not (PlayerStats.hp < after_first - 0.01): fails += 1   # 窗口后二次生效
+print("FAILS=", fails, " hp=", PlayerStats.hp)
+```
+
+Expected: `FAILS=0`，HP 两次均下降。
+
+- [ ] **Step 4: spend_hp_cost 不受无敌影响（验收④）**
+
+Run: godot-mcp-pro `execute_game_script`：
+
+```gdscript
+PlayerStats.hp = 100.0
+PlayerStats.take_damage(10.0)           # 进入无敌
+var mid := PlayerStats.hp
+PlayerStats.spend_hp_cost(5.0)          # 自伤：应无视无敌，正常扣
+var fails := 0
+if abs((mid - 5.0) - PlayerStats.hp) > 0.01: fails += 1
+print("FAILS=", fails, " hp=", PlayerStats.hp, " expected=", mid - 5.0)
+```
+
+Expected: `FAILS=0`，卖血正常扣 5。
+
+- [ ] **Step 5: 截图确认闪烁 + 收尾**
+
+Run: godot-mcp-pro `get_game_screenshot`（受击瞬间附近，观察玩家节点闪烁；非强制像素断言，目视确认）。然后 `stop_scene`。
+Expected: 玩家标记在无敌期呈半透明闪烁。
+
+- [ ] **Step 6: 更新路线图 + memory + 提交**
+
+- 在 `docs_dev/plans/2026-07-23-missing-features-roadmap.md` 的 E6「现状」勾除「玩家无敌帧」项。
+- 更新 memory `slice-progress-vs-plan.md`：记 E6-a i-frames 完成（分支/commit）。
+
+```bash
+git add docs_dev/plans/2026-07-23-missing-features-roadmap.md
+git commit -m "docs(roadmap): E6-a 玩家无敌帧完成，勾除现状项"
+```
+
+---
+
+## 验收标准回溯（spec §4）
+
+| # | 验收标准 | 覆盖任务 |
+| :- | :-- | :-- |
+| 1 | 多弹同帧只扣一次血 | Task 5 Step 2 |
+| 2 | 窗口内免疫 / 窗口后可再受击 | Task 5 Step 2,3 |
+| 3 | 无敌期闪烁 + hurt 音效 | Task 3 + Task 2（emit）+ Task 5 Step 5 |
+| 4 | spend_hp_cost 不受影响 | Task 5 Step 4 |
+| 5 | balance.json 改值生效 + 设计器往返 FAILS=0 | Task 1 Step 6 + Task 4 Step 5 |
+| 6 | validate_script 通过 / 无硬编码时长副本 | 各 Task validate 步 |