# 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. 七个分页详解

> 所有分页均为**字段化表单**（输入框/下拉/复选框/行编辑器），选项显示为「中文 English」双语，**无需手写 JSON**。

### ✨ 法术（spells.json）
新增/编辑/删除法术，最丰富的玩法配置。**字段化表单**，详见 [06 法术编辑器](06_spell_editor.md)。
- 列表 → 选中编辑；➕新增 / ⧉复制 / 🗑删除
- 固定字段：ID / 类型(动作/修饰/触发/逻辑) / 显示名 / 描述
- **元素标签**：火/冰/雷/水/毒 复选框（可多选）+ 自定义标签框（非元素 tag）
- **通用 meta**：蓝耗 mana_cost / 商店价 shop_cost / 解锁价 unlock_cost
- **动态字段**：随类型（及 ACTION 动作种类 弹道/毒池/召唤、LOGIC logic_op）自动切换；伤害类型/施加状态等为下拉；schema 之外的键落入「其它(JSON)」框保留不丢
- 💧 **蓝耗**：`meta.mana_cost` 决定施放消耗的魔力（0=免蓝）；权威数值见 `numerical_design §2`

### 👾 敌人（enemies.json）
6 种敌人原型的数值表格，**直接拖动数字框**调整：

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

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

### 🌊 波次（waves.json）
**关卡难度曲线编辑器**——逐波配置：

| 列 | 含义 |
|:---|:---|
| 怪数 | 本波杂兵数量 |
| 血量 | 杂兵基础血量 |
| 类型 | 杂兵原型（杂兵/快速/护甲…）下拉 |
| 精英 | 带寻路的精英数（W15+）|
| 金币 / XP | 波次结算奖励 |
| Boss | 无 None / 首领 MiniBoss / 终焉 Boss |

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

### 🪄 Core（cores.json）
法杖类型配置（影响法术排列玩法）：

| 字段 | 含义 |
|:---|:---|
| 槽位数 | 可装法术数 |
| 拓扑 | 线性 LINEAR / 矩阵 MATRIX / 电路 CIRCUIT |
| CPU 上限 | 单次施法最大执行步数 |
| 施法间隔 | 自动施法冷却(s) |
| 蓝上限(Mana Max) | 法杖蓝池上限（基础 100） |
| 回蓝/秒(Mana Regen) | 每秒回复的魔力（基础 5） |
| 特性 | 无 None / 记忆 PERSISTENT_MEMORY / 双流 / 末位施法 / 洗牌 / 无限法术 |
| 矩阵行·列 | MATRIX 专用网格尺寸 |
| 电路边 | CIRCUIT 专用，`from → to` 行编辑器（可 ➕加/🗑删边）|

### 🔮 共鸣（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、施加状态选「冻结 Freeze」→ ✓应用 → 💾保存 → 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()` 调用

> **开发规范见 [`CLAUDE.md`](../../CLAUDE.md) 「编辑器插件 / 游戏设计器开发规范」**：字段化（禁止手写 JSON，可变长整数元组用 `tuple_list_editor.gd`）、输入框 `SIZE_EXPAND_FILL` 撑满、标签「中文 English」双语、显示与存储解耦、改动后 `validate_script` + 回读往返验证。

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