# 元素抗性（Element Resistance）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:** 让敌人对不同元素有差异化抗性/弱点，激活当前的死代码抗性维度，使元素类伤害产生真实差异。

**Architecture:** `enemies.json` 每型可选 `resistances{元素名:-0.9~0.9}` → `EnemyManager._RESIST`(type→PackedFloat32Array[6]) 加载 → `apply_damage_from_context` 按 `ctx.damage_type` 查表传入 `calc_damage(0, res)`。护甲逻辑不动（仍在 `apply_damage` 内）；物理(0) 无抗性；越界安全回退 0。设计器 enemy_tab 加 6×5 抗性网格。

**Tech Stack:** Godot 4.7.1 Mono / GDScript / 纯 JSON 数据驱动 / godot-mcp-pro 运行时实测（无 pytest：核心逻辑经运行中战斗场景 `execute_game_script` 断言，编辑器侧/设计器经 `execute_editor_script` + `validate_script`）。

> **规范**：所有 `.gd` 改动后 `validate_script`；纯数据驱动无硬编码；提交中文；分支 `feat/element-resistance`（已建）。spec：`docs_dev/specs/2026-07-24-element-resistance-design.md`。DamageType：PHYSICAL=0/FIRE=1/ICE=2/LIGHTNING=3/POISON=4/ARCANE=5。

---

### Task 1: 核心 —— EnemyManager 抗性加载 + 命中查表 + enemies.json 种子

**Files:**
- Modify: `data/enemies.json`（给 "1" Fast 加示例抗性/弱点）
- Modify: `scripts/autoloads/enemy_manager.gd`（成员区 :40-43、`_load_json_archetypes` :56-63、`apply_damage_from_context` :253-258）

- [ ] **Step 1: enemies.json 加种子抗性**

在 `data/enemies.json` 中，给 `"1"`（快速 Fast）项加 `resistances`（抗火、弱冰），用于实测。改为：
```json
  "1": { "name": "快速 Fast",     "speed": 140, "armor": 0,  "size": 11, "color": [0.95, 0.72, 0.20], "resistances": { "fire": 0.5, "ice": -0.5 } },
```
（其余型不加，保持缺失=0 的回退路径可测。注意 JSON 逗号。）

- [ ] **Step 2: EnemyManager 增成员 + 元素映射常量**

在 `enemy_manager.gd:43`（`var _RENDER_COLOR...` 之后）新增：
```gdscript
var _RESIST: Dictionary = {}       # type → PackedFloat32Array(6)，index=damage_type，[0]物理恒0
const _RESIST_ELEMENTS := {"fire": 1, "ice": 2, "lightning": 3, "poison": 4, "arcane": 5}
```

- [ ] **Step 3: `_load_json_archetypes` 加载抗性**

在 `enemy_manager.gd` 的 `_load_json_archetypes()` 每型循环内（`_RENDER_COLOR[t] = ...` 之后，`:63` 处）追加：
```gdscript
		var rf := PackedFloat32Array([0, 0, 0, 0, 0, 0])
		var res_d: Dictionary = d.get("resistances", {})
		for ename in _RESIST_ELEMENTS:
			if res_d.has(ename):
				rf[_RESIST_ELEMENTS[ename]] = clampf(float(res_d[ename]), -0.9, 0.9)
		_RESIST[t] = rf
```

- [ ] **Step 4: 增查表辅助**

在 `apply_damage_from_context` 之前（或就近）新增：
```gdscript
## 元素抗性查表：越界/缺失回退 0（物理 index 0 恒 0）
func _resist_for(etype: int, dtype: int) -> float:
	var rf: PackedFloat32Array = _RESIST.get(etype, PackedFloat32Array())
	if dtype < 0 or dtype >= rf.size():
		return 0.0
	return rf[dtype]
```

- [ ] **Step 5: 改写 `apply_damage_from_context` 传入抗性**

将 `enemy_manager.gd:253-258` 的整个函数替换为：
```gdscript
func apply_damage_from_context(entity_id: int, ctx_id: int) -> bool:
	var ctx: DamageContext = DamageContextPool.get_context(ctx_id)
	if ctx == null:
		return false
	var slot: int = _entity_index_map.get(entity_id, -1)
	var res: float = 0.0
	if slot >= 0:
		var etype: int = int(_data[slot * ENEMY_STRIDE + 6])
		res = _resist_for(etype, ctx.damage_type)
	var final_dmg: float = ctx.calc_damage(0.0, res)
	return apply_damage(entity_id, final_dmg, ctx.owner_id, true)
```
（护甲仍由 `apply_damage` 内 `_ARMOR` 处理，勿动。）

- [ ] **Step 6: 校验语法**

Run: godot-mcp-pro `validate_script` on `res://scripts/autoloads/enemy_manager.gd`
Expected: 无错误。

- [ ] **Step 7: 校验 JSON + 加载（编辑器脚本）**

Run: godot-mcp-pro `execute_editor_script`：
```gdscript
var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/enemies.json"))
var ok := d is Dictionary and d.has("1") and d["1"].has("resistances")
ok = ok and abs(float(d["1"]["resistances"].get("fire", 0)) - 0.5) < 0.001
ok = ok and abs(float(d["1"]["resistances"].get("ice", 0)) + 0.5) < 0.001
print("FAILS=", 0 if ok else 1)
```
Expected: `FAILS=0`

- [ ] **Step 8: 提交**

```bash
git add data/enemies.json scripts/autoloads/enemy_manager.gd
git commit -m "feat(resist): EnemyManager 元素抗性加载+命中查表；enemies.json Fast 种子抗火弱冰"
```
（heredoc，body 末尾加 `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`。）

---

### Task 2: 设计器 —— enemy_tab 抗性网格 + _save 写入

**Files:**
- Modify: `addons/game_designer/enemy_tab.gd`（成员 :9-11、`_ready` :24-40、`_save` :46-60）

- [ ] **Step 1: 增元素常量 + 行结构说明**

在 `enemy_tab.gd:7`（`const NAMES...` 之后）新增：
```gdscript
const ELEM_KEYS   = ["fire", "ice", "lightning", "poison", "arcane"]
const ELEM_LABELS = ["火 Fire", "冰 Ice", "雷 Lightning", "毒 Poison", "奥 Arcane"]
```

- [ ] **Step 2: `_ready` 主表后加抗性网格**

在 `enemy_tab.gd` 的 `_ready()` 内、`add_child(HSeparator.new())`（现 :37，主表与保存按钮之间）**之后、保存按钮之前**插入：
```gdscript
	add_child(UI.cell_label("元素抗性 Resistances（-0.9~0.9，负=弱点加伤）"))
	var rgrid := GridContainer.new()
	rgrid.columns = ELEM_KEYS.size() + 1
	add_child(rgrid)
	var rhead := Label.new(); rhead.text = "原型"; rhead.modulate = Color(0.7, 0.8, 1.0)
	rgrid.add_child(rhead)
	for el in ELEM_LABELS:
		var el_l := Label.new(); el_l.text = el; el_l.modulate = Color(0.7, 0.8, 1.0)
		rgrid.add_child(el_l)
	for i in 6:
		var d2: Dictionary = _data.get(str(i), {})
		var res_d: Dictionary = d2.get("resistances", {})
		rgrid.add_child(UI.cell_label(NAMES[i]))
		var res_spins := {}
		for ei in ELEM_KEYS.size():
			var ename: String = ELEM_KEYS[ei]
			var sp2 := UI.spin(-0.9, 0.9, 0.05, float(res_d.get(ename, 0.0)))
			rgrid.add_child(sp2)
			res_spins[ename] = sp2
		_rows[i]["resist"] = res_spins
```
（注意：此块必须在 6 行主表 `for i in 6` 之后运行，`_rows` 已填满 6 项——上面的 `_rows[i]["resist"] = ...` 给已存在的行字典追加键。）

- [ ] **Step 3: 改写 `_save` 写入 resistances**

将 `enemy_tab.gd:46-60` 的 `_save` 整体替换为：
```gdscript
func _save() -> void:
	var out: Dictionary = {}
	for i in 6:
		var r: Dictionary = _rows[i]
		var entry := {
			"name": NAMES[i],
			"speed": r["speed"].value,
			"armor": r["armor"].value,
			"size": r["size"].value,
			"color": [r["color"].color.r, r["color"].color.g, r["color"].color.b],
		}
		var rd := {}
		for ename in ELEM_KEYS:
			var v: float = r["resist"][ename].value
			if absf(v) > 0.0001:
				rd[ename] = v
		if not rd.is_empty():
			entry["resistances"] = rd
		out[str(i)] = entry
	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/enemy_tab.gd`
Expected: 无错误。

- [ ] **Step 5: 设计器读写往返实测**

> ⚠️ dock 内驻留旧类需 `EditorInterface.restart_editor(true)` 清缓存后新代码才生效（CLAUDE.md）；若下方断言用旧类，先重启编辑器再跑。fresh `load().new()` 通常可避开。

Run: godot-mcp-pro `execute_editor_script`：
```gdscript
var Tab = load("res://addons/game_designer/enemy_tab.gd")
var t = Tab.new(); add_child(t)
var fails := 0
# 读：Fast(1) fire 应=0.5, ice=-0.5
if abs(t._rows[1]["resist"]["fire"].value - 0.5) > 0.001: fails += 1
if abs(t._rows[1]["resist"]["ice"].value + 0.5) > 0.001: fails += 1
# 写往返：改 Basic(0) poison=0.3，Fast(1) fire→0，重存重读
t._rows[0]["resist"]["poison"].value = 0.3
t._rows[1]["resist"]["fire"].value = 0.0
t._save()
var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/enemies.json"))
if abs(float(d["0"].get("resistances", {}).get("poison", -9)) - 0.3) > 0.001: fails += 1   # 写入非零
if d["1"].get("resistances", {}).has("fire"): fails += 1                                     # 归零应省略键
if not d["1"].get("resistances", {}).has("ice"): fails += 1                                  # ice=-0.5 仍在
t.queue_free()
print("FAILS=", fails)
```
Expected: `FAILS=0`。测试后用 `git checkout -- data/enemies.json` 还原到 Task 1 种子状态（`_save` 会 pretty-print 重排文件）。

- [ ] **Step 6: 提交**

```bash
git checkout -- data/enemies.json   # 还原往返测试对文件的改写/重排
git add addons/game_designer/enemy_tab.gd
git commit -m "feat(resist): 设计器敌人页增元素抗性网格(6×5) + _save 写 resistances（全0省略）"
```

---

### Task 3: 验收 —— 运行时集成实测（MCP）+ 收尾

**Files:** 无（运行时断言）+ 收尾文档

- [ ] **Step 1: 启动战斗场景**

Run: godot-mcp-pro `play_scene` → `res://scenes/main/combat_s2.tscn`。确认运行、无 `get_editor_errors`。

- [ ] **Step 2: 抗性/弱点/物理对照（验收①②③④）**

> 方法：直接生成敌人 + 构造 DamageContext 命中，绕过子弹几何，精确对照。Fast(type=1) 抗火0.5/弱冰-0.5；Basic(type=0) 无抗性。

> `spawn_enemy(pos, hp, enemy_type)` 签名已确认（`enemy_manager.gd:121`）。用 lambda 辅助（`execute_game_script` 体内不能定义具名 func，须用 Callable）。

Run: godot-mcp-pro `execute_game_script`：
```gdscript
var fails := 0
# lambda：对 (enemy_type, damage_type) 生成敌人+施加 base=100 伤害，返回实际掉血
var probe := func(etype, dtype):
	var eid = EnemyManager.spawn_enemy(Vector2(300, 0), 1000.0, etype)
	var before = EnemyManager.get_hp_percent(eid) * 1000.0
	var cid = DamageContextPool.acquire(100.0, 1.0, dtype, -1, false, 0.0)
	EnemyManager.apply_damage_from_context(eid, cid)
	DamageContextPool.release(cid)
	return before - EnemyManager.get_hp_percent(eid) * 1000.0

var f1 = probe.call(1, 1)   # Fast 抗火0.5 → ≈50
if abs(f1 - 50.0)  > 1.0: fails += 1
var f2 = probe.call(1, 2)   # Fast 弱冰-0.5 → ≈150
if abs(f2 - 150.0) > 1.0: fails += 1
var f3 = probe.call(1, 0)   # Fast 物理无抗 → ≈100
if abs(f3 - 100.0) > 1.0: fails += 1
var b1 = probe.call(0, 1)   # Basic 无 resistances 火 → 回退0 ≈100
if abs(b1 - 100.0) > 1.0: fails += 1
var e1 = probe.call(0, 99)  # 越界 damage_type 不崩 → 回退0 ≈100
if abs(e1 - 100.0) > 1.0: fails += 1
print("FAILS=", fails, " fire_resist=", f1, " ice_weak=", f2, " phys=", f3, " basic_fire=", b1, " oob=", e1)
```
Expected: `FAILS=0`，fire_resist≈50 / ice_weak≈150 / phys≈100 / basic_fire≈100 / oob≈100。
> 注：apply_damage 内 combo_bonus 默认 1.0（无 COMBO_MARK 层），armor 按型（Fast=0/Basic=0）故上述期望值成立。若某敌被一次伤害不足以在同一 slot 留存（如秒杀），大血量 1000 已规避。

- [ ] **Step 3: 护甲叠加对照（验收③）**

Run: godot-mcp-pro `execute_game_script`（复用上面 `_spawn`/`_hit` 或重新定义）：
```gdscript
# Armored(2) armor=5，无 resistances：火(1) base100 → max(1, 100×1×1 −5)=95
var fails := 0
var cid = DamageContextPool.acquire(100.0, 1.0, 1, -1, false, 0.0)
var eid = EnemyManager.spawn_enemy(Vector2(300, 0), 1000.0, 2)   # (pos, hp, enemy_type=Armored)
var before = EnemyManager.get_hp_percent(eid) * 1000.0
EnemyManager.apply_damage_from_context(eid, cid)
DamageContextPool.release(cid)
var drop = before - EnemyManager.get_hp_percent(eid) * 1000.0
if abs(drop - 95.0) > 1.0: fails += 1
print("FAILS=", fails, " armored_drop=", drop)   # 期望 ≈95（护甲减免生效、与抗性正交）
```
Expected: `FAILS=0`，armored_drop≈95。然后 `stop_scene`。

- [ ] **Step 4: 更新路线图 + memory + 提交**

- `docs_dev/plans/2026-07-23-missing-features-roadmap.md`：E1「现状」抗性行标记完成、切分①勾除。
- memory `slice-progress-vs-plan.md`：记 E1-① 元素抗性完成（分支/commit）+ MEMORY.md 索引。

```bash
git add docs_dev/plans/2026-07-23-missing-features-roadmap.md
git commit -m "docs(roadmap): E1-① 元素抗性完成，勾除现状项"
```

---

## 验收标准回溯（spec §4）

| # | 验收标准 | 覆盖任务 |
| :- | :-- | :-- |
| 1 | 抗火减半 / 物理不变 | Task 3 Step 2 (f1, f3) |
| 2 | 负抗性放大 1.5× | Task 3 Step 2 (f2) |
| 3 | 抗性与护甲叠加正确 | Task 3 Step 3 |
| 4 | 缺失/未列元素回退 0 | Task 3 Step 2 (b1, oob) |
| 5 | 设计器往返 FAILS=0（负值/全0省略） | Task 2 Step 5 |
| 6 | validate 通过 / 越界不崩 | 各 validate 步 + Task 3 Step 2 (oob) |