From abe057edf80296dd279bb69c0a44ccc919c4812f Mon Sep 17 00:00:00 2001 From: Joywayer Date: Fri, 24 Jul 2026 11:49:51 +0800 Subject: [PATCH] =?UTF-8?q?docs(plan):=20E1-=E2=91=A0=20=E5=85=83=E7=B4=A0?= =?UTF-8?q?=E6=8A=97=E6=80=A7=E9=80=90=E4=BB=BB=E5=8A=A1=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E8=AE=A1=E5=88=92=EF=BC=883=20=E4=BB=BB=E5=8A=A1=20=C2=B7=20la?= =?UTF-8?q?mbda-MCP=20=E5=AE=9E=E6=B5=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plans/2026-07-24-element-resistance.md | 294 ++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs_dev/plans/2026-07-24-element-resistance.md diff --git a/docs_dev/plans/2026-07-24-element-resistance.md b/docs_dev/plans/2026-07-24-element-resistance.md new file mode 100644 index 0000000..08762bb --- /dev/null +++ b/docs_dev/plans/2026-07-24-element-resistance.md @@ -0,0 +1,294 @@ +# 元素抗性（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) `。） + +--- + +### 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) |