初次提交

2026-07-20 10:56:52 +08:00
commit 7bcc0026e0
462 changed files with 50191 additions and 0 deletions
@@ -0,0 +1,134 @@
+# 06 法术编辑器（可视化工具）
+
+> **给策划/开发**：无需写一行代码，在 Godot 编辑器里用可视化表单新增、编辑、删除法术。这是 Godot 的 **EditorPlugin**（等同 Unity 的自定义 EditorWindow）。
+
+---
+
+## 1. 启用插件
+
+插件位于 `res://addons/spell_editor/`，默认已在 `project.godot` 启用。若未显示：
+
+```
+项目 → 项目设置 → 插件 → 勾选 "Spell Editor (法术编辑器)"
+```
+
+启用后，编辑器**左下停靠区**会出现「法术编辑器」标签页。
+
+> 首次启用或修改插件后，可能需要**重启 Godot 编辑器**让停靠面板出现。
+
+---
+
+## 2. 界面说明
+
+```
+✨ 法术编辑器
+┌────────────────────────┐
+│ 法术列表（ItemList）     │  ← 所有 data/spells.json 中的法术
+│  [ACTION] action_frost… │
+│  [MODIFIER] modifier_pi… │
+└────────────────────────┘
+[➕新增] [⧉复制] [🗑删除]
+────────────────────────
+ID（唯一）       : [______]
+类型             : [ACTION ▾]
+显示名（tr 键）   : [______]
+描述（tr 键）     : [______]
+元素标签（逗号）   : [tag:ice]
+meta（JSON）      : [______]
+                   [______]
+[插入该类型 meta 模板]
+────────────────────────
+[✓应用到列表] [💾保存文件] [↻重载]
+状态：……
+```
+
+---
+
+## 3. 新增一个法术（操作流程）
+
+1. 点 **➕新增** → 列表出现 `new_spell`，表单自动填入 ACTION 模板
+2. 改 **ID**（如 `action_lightning`，必须全局唯一）
+3. 选 **类型**（ACTION / MODIFIER / TRIGGER / LOGIC）
+4. 填 **显示名 / 描述**（建议填 `tr()` 键，如 `SPELL_LIGHTNING_NAME`，见 [04 本地化](04_localization.md)）
+5. 填 **元素标签**（共鸣用，如 `tag:lightning`；多个用逗号）
+6. 编辑 **meta**（JSON）——点「插入该类型 meta 模板」获取起始模板，改数值
+7. 点 **✓应用到列表** → 校验并写入内存
+8. 点 **💾保存文件** → 写入 `res://data/spells.json`
+9. 运行游戏（F5）→ 新法术自动出现在商店池，可购买施放
+
+> **改完不生效？** 法术在游戏启动时由 `SpellRegistry` 加载，需要**重启游戏**（F5 重新运行）。
+
+---
+
+## 4. meta 字段速查（按类型）
+
+### ACTION（弹道）
+```json
+{ "base_damage": 5.0, "speed": 350.0, "lifetime": 4.0, "radius": 6.0,
+  "damage_type": 0, "apply_status_id": 2, "pierce": 0, "shop_cost": 20 }
+```
+- `apply_status_id`：命中施加状态（1=燃烧 2=冻结 3=中毒…见 `status_id.gd`），可省略
+- `action_kind`：`"zone"`（地面效果）/ `"summon"`（召唤物），省略=普通弹道
+
+### ACTION（地面效果，毒池等）
+```json
+{ "action_kind": "zone", "radius": 200.0, "status_id": 3,
+  "duration": 5.0, "tick_interval": 1.0, "shop_cost": 28 }
+```
+
+### ACTION（召唤炮台）
+```json
+{ "action_kind": "summon", "lifetime": 20.0, "range": 350.0,
+  "fire_interval": 0.8, "base_damage": 4.0, "speed": 360.0, "shop_cost": 35 }
+```
+
+### MODIFIER（修改施法）
+```json
+{ "damage_add": 10.0, "damage_mult": 1.0, "spread_add": 1,
+  "multicast": 1, "pierce": 2, "shop_cost": 20 }
+```
+
+### TRIGGER（命中子母弹）
+```json
+{ "base_damage": 3.0, "speed": 250.0, "lifetime": 4.0, "radius": 6.0,
+  "damage_type": 0, "shop_cost": 30 }
+```
+
+### LOGIC（条件/循环）
+```json
+{ "logic_op": "every_n_shots", "n": 3, "reg": 0, "shop_cost": 24 }
+```
+`logic_op` 取值：`every_n_shots` / `if_hp_below`(threshold) / `if_enemy_nearby`(range) / `loop`(count)
+
+---
+
+## 5. 数据流（原理）
+
+```
+法术编辑器 dock  ──保存──▶  res://data/spells.json  ──游戏启动加载──▶  SpellRegistry
+   （编辑器内）                  （纯数据，可 git 版本管理）        （注册到法术 VM）
+                                                                      │
+                                                  商店抽取 / 背包装备 / 法术 VM 编译施放
+```
+
+- `data/spells.json` 中的法术**优先级最高**，会覆盖 `wand_preset.gd` 里的同 ID 硬编码版本
+- 不在 JSON 里的法术仍由硬编码提供（向后兼容，不会丢失现有法术）
+- JSON 是纯文本，可纳入 git，多人协作改法术不冲突代码
+
+---
+
+## 6. 扩展方向（给开发）
+
+同一套 EditorPlugin 模式可复制出更多可视化工具：
+
+| 工具 | 数据文件 | 对应硬编码 |
+|:---|:---|:---|
+| **法术编辑器**（已实现） | `data/spells.json` | `wand_preset.gd` |
+| 敌人编辑器（可加） | `data/enemies.json` | `enemy_manager.gd` `_SPEED`/`_ARMOR` |
+| 波次编辑器（可加） | `data/waves.json` | `wave_manager.gd` `WAVE_CONFIG` |
+| Core 编辑器（可加） | `data/cores.json` | `wand_preset.gd` `make_*_core` |
+| 共鸣配方编辑器（可加） | `data/resonance.json` | `spell_evaluator.gd` `_resonance_recipes` |
+
+实现参考 `addons/spell_editor/spell_dock.gd`：`@tool` 脚本 + `EditorPlugin.add_control_to_dock` + JSON 读写 + 对应 Manager 的 `_load_json_*()` 加载方法。
+
+> **Godot 编辑器扩展能力**：`EditorPlugin`（停靠面板/工具栏/底部面板）、`@tool`（脚本在编辑器运行）、`EditorInspectorPlugin`（自定义检视器）、自定义 `Resource`（`.tres` 自带表单）、`EditorScript`（一次性脚本）。与 Unity 的 EditorWindow/CustomEditor/ScriptableObject 一一对应，且与节点系统集成更紧。