spellforge/docs/handbook/07_game_designer.md

07 游戏设计器（一站式可视化配置工具）

核心理念：策划 / 美术 / 开发无需写一行代码，在编辑器的「🎮 游戏设计器」面板里调数值、改玩法、加内容。所有改动保存为 res://data/*.json，游戏运行时自动加载。

---

1. 打开工具

1. 启用插件（默认已启用）：项目 → 项目设置 → 插件 → 勾选 "Game Designer"
2. 编辑器底部面板点击 「🎮 游戏设计器」 标签（与"输出""调试器"并列）
3. 出现 7 个分页：✨法术 / 👾敌人 / 🌊波次 / 🪄Core / 🔮共鸣 / 🔥状态 / ⚖平衡

🏛 纯数据驱动架构：游戏所有内容数据只存在于 res://data/*.json，代码不含任何硬编码内容副本或回退。这意味着——改 JSON 就是改游戏，数据是唯一权威源。若某个 data 文件缺失，游戏会在输出面板 push_error 明确报错（而非静默用旧值）。

首次启用或改插件后，可能需重启 Godot 编辑器让面板出现。

---

2. 通用工作流

在面板里改数值/加内容  →  点「💾 保存」  →  按 F5 运行游戏  →  改动生效

⚠️ 所有改动需重启游戏（F5）生效——数据在游戏启动时由各 Manager 一次性加载。

---

3. 五个分页详解

✨ 法术（spells.json）

新增/编辑/删除法术，最丰富的玩法配置。详见 06 法术编辑器（meta 字段速查表）。

• 列表 → 选中编辑；➕新增 / ⧉复制 / 🗑删除
• 字段：ID / 类型(ACTION/MODIFIER/TRIGGER/LOGIC) / 显示名 / 描述 / 元素标签 / meta(JSON)
• 「插入该类型 meta 模板」一键填入起始参数（模板已含 mana_cost 蓝耗、shop_cost 售价）
• 💧 蓝耗：每个法术的 meta.mana_cost 决定施放消耗的魔力（0=免蓝）；权威数值见 numerical_design §2

👾 敌人（enemies.json）

6 种敌人原型的数值表格，直接拖动数字框调整：

列	含义
速度	移动速度（px/s）
护甲	每次命中减免的固定伤害
尺寸	渲染直径（px），Boss 设大更醒目
颜色	点色块选颜色（敌人渲染色）

原型：杂兵 / 快速 / 护甲 / 精英 / 首领(MiniBoss) / 终焉(Boss)

🌊 波次（waves.json）

关卡难度曲线编辑器——逐波配置：

列	含义
怪数	本波杂兵数量
血量	杂兵基础血量
类型	杂兵原型（Basic/Fast/Armored…）
精英	带寻路的精英数（W15+）
金币 / XP	波次结算奖励
Boss	无 / MiniBoss(4) / Boss(5)

• 「➕末尾加一波」扩展关卡长度
• 改完点「💾保存 waves.json」

🪄 Core（cores.json）

法杖类型配置（影响法术排列玩法）：

字段	含义
槽位数	可装法术数
拓扑	LINEAR(线性) / MATRIX(矩阵邻接) / CIRCUIT(电路分叉)
CPU 上限	单次施法最大执行步数
施法间隔	自动施法冷却(s)
蓝上限(Mana Max)	法杖蓝池上限（基础 100）
回蓝/秒(Mana Regen)	每秒回复的魔力（基础 5）
特性	无 / PERSISTENT_MEMORY(寄存器跨帧) / …
矩阵行·列	MATRIX 专用网格尺寸
电路边	CIRCUIT 专用，JSON 有向边 [{"from":0,"to":1}]

🔮 共鸣（resonance.json）

元素组合自动合成配方（隐藏玩法）：

• 元素 A + 元素 B（相邻放置）→ 合成产物法术
• 匹配方式：adjacent(相邻) / anywhere_in_deck(任意位置)
• 消耗输入：合成后是否移除原两张法术
• 例：tag:water + tag:lightning → action_plasma_storm

🔥 状态（status_effects.json）

DoT/控制/叠层效果：

字段	含义
状态 ID	整数（1=燃烧 2=冻结 3=中毒…），与法术 meta 的 apply_status_id 对应
持续时间 / 跳字间隔	DoT 周期
叠层模式	REFRESH(刷新) / INTENSITY(叠层) / INDEPENDENT(独立)
最大层数	0=无限
每跳伤害	DoT 每次伤害
VFX ID	触发的特效

⚖ 平衡（balance.json）

全局数值微调：

• 难度乘子表格：4 行(敌人血量×/玩家受伤×/波次怪数×/Boss血量×) × 3 档(初学者/标准/挑战)
• Boss 基础血量：MiniBoss(W8) / Final Boss(W20)

调一格数字即可改变整体难度曲线。

---

4. 数据流原理

🎮 游戏设计器面板  ──保存──▶  res://data/*.json  ──游戏 F5 启动加载──▶  各 Manager
  (编辑器内)              (纯文本，可 git 版本管理)
                                                  spells.json  → SpellRegistry
                                                  enemies.json → EnemyManager
                                                  waves.json   → WaveManager
                                                  cores.json   → WandPreset
                                                  balance.json → SettingsManager + WaveManager

• JSON 是唯一权威数据源——代码不含硬编码内容副本（纯数据驱动）
• 文件缺失/格式错误 → push_error 明确报错（不静默，便于发现问题）
• 数据是纯文本，多人协作改数值不会冲突代码，可走 git review

数据文件清单

文件	内容	加载方
spells.json	全部法术定义	SpellRegistry
enemies.json	6 敌人原型数值	EnemyManager
waves.json	20 波关卡曲线	WaveManager
cores.json	法杖 Core 定义	WandPreset
resonance.json	共鸣配方	SpellEvaluator
status_effects.json	状态效果定义	StatusRegistry
balance.json	难度乘子 + Boss 血量	SettingsManager

---

5. 实操示例

例 1：让游戏更简单（策划）

平衡分页 → 「敌人血量×」初学者列改 0.5 → 保存 → F5。初学者难度敌人血量减半。

例 2：W10 提前出 Boss（策划）

波次分页 → 第 10 行 Boss 列选 MiniBoss(4) → 保存 → F5。

例 3：新增一个"冰锥"法术（策划）

法术分页 → ➕新增 → ID 填 action_ice_spike，类型 ACTION，「插入模板」后改 base_damage 为 8、加 "apply_status_id": 2（冻结）→ ✓应用 → 💾保存 → F5。新法术自动进商店。

例 4：精英敌人改成紫色更大（美术）

敌人分页 → 精英行 → 尺寸改 30，颜色点开选紫色 → 保存 → F5。

---

6. 扩展工具（给开发）

新增编辑器分页只需 3 步（参考 addons/game_designer/）：

1. 写一个 @tool extends VBoxContainer 的标签脚本（读写对应 data/xxx.json，复用 designer_ui.gd 的 spin/line/opt/btn 辅助）
2. 在 designer_panel.gd 的 _init() 里 _add_tab(...) 注册
3. 对应 Manager 加 _load_json_xxx()，在 _ready() 调用

Godot 编辑器扩展 = Unity 平替：EditorPlugin(面板/工具栏/底部面板) ↔ EditorWindow；@tool ↔ ExecuteInEditMode；EditorInspectorPlugin ↔ CustomEditor；自定义 Resource ↔ ScriptableObject。