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

玩家无敌帧（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 之后新增一行（同级顶层键）：

  "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... 之后）新增：

var _IFRAME_SEC: float = 0.5   # 玩家受击无敌窗口（秒）；balance.json player_iframe_sec

• Step 3: _load_balance 读取该键

在 settings_manager.gd 的 _load_balance() 末尾（现 :91-93 infinite_spells 块之后）追加：

	if data.has("player_iframe_sec"):
		_IFRAME_SEC = float(data["player_iframe_sec"])

• Step 4: 增访问器

在 settings_manager.gd:70（hp_cost_cap_ratio() 之后）新增：

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：

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: 提交

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... 之后）新增：

var _invuln_until_msec: int = 0   # < now 表示可受击；受击后设为 now + iframe 窗口

• Step 2: 改写 take_damage 加门控 + emit

将 player_stats.gd:65-69 的 take_damage 整体替换为：

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 之后新增：

func is_invulnerable() -> bool:
	return Time.get_ticks_msec() < _invuln_until_msec

• Step 4: 移除死订阅（避免 emit 自递归）

删除 player_stats.gd:33 的这一行：

	EventBus.subscribe(EventID.PLAYER_DAMAGED, _on_player_damaged)

并删除 player_stats.gd:116-117 的整个 _on_player_damaged 函数：

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() 之前）新增一行：

	_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: 提交

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 之后）追加：

	# 无敌帧闪烁反馈：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: 提交

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 之前）新增：

var _iframe: SpinBox

• Step 2: _ready 增输入栏

在 balance_tab.gd 的 _ready() 内、保存按钮（add_child(UI.btn("💾 保存 balance.json", _save))，现 :56）之前插入：

	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 整体替换为：

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：

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: 提交

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：

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：

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：

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）。

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 步