From 17f6ce2ff082510cdbb42877ea053fa8311ebac0 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Wed, 22 Jul 2026 15:40:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=E6=96=B0=E5=A2=9E=E7=BC=96?= =?UTF-8?q?=E8=BE=91=E5=99=A8=E6=8F=92=E4=BB=B6/=E6=B8=B8=E6=88=8F?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E5=99=A8=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83?= =?UTF-8?q?=EF=BC=88=E5=AD=97=E6=AE=B5=E5=8C=96=E3=80=81=E6=92=91=E6=BB=A1?= =?UTF-8?q?=E3=80=81=E5=8F=8C=E8=AF=AD=E3=80=81=E9=AA=8C=E8=AF=81=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e7317d5..e7f5e39 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,3 +21,20 @@ Spellforge（万法熔炉）—— Godot 4.6 (Mono) 弹幕射击 Roguelite，SoA - **`docs_dev/`** —— **开发过程中产生的文档**。开发计划、进度追踪、审计报告、平台认证清单、历史归档草案等过程性文档。索引见 [`docs_dev/README.md`](docs_dev/README.md)。 > 判断依据：若文档是「项目应当如何设计/实现」的权威规范 → `docs/`；若是「开发过程中的计划、记录、追踪、归档」→ `docs_dev/`。 + +## 编辑器插件 / 游戏设计器开发规范 + +面向 `addons/game_designer/` 等 `@tool` 编辑器插件（可视化配置工具）。用户手册见 [`docs/handbook/07_game_designer.md`](docs/handbook/07_game_designer.md)。 + +- **字段化，禁止手写 JSON**：凡是可结构化的数据都用输入控件（`SpinBox` / `OptionButton` / `CheckBox` / 行编辑器），**不要**用 `TextEdit` 让用户手写 JSON —— 易配置错、可读性差。 + - 可变长的小整数元组列表（如 Core `edges`、balance `aether_thresholds`）用共享组件 [`addons/game_designer/tuple_list_editor.gd`](addons/game_designer/tuple_list_editor.gd)（`setup`/`set_values`/`get_values`，行 + ➕加/🗑删）。 + - **唯一例外**：专门收纳「schema 之外的未知键」的逃生舱（如法术 meta 的「其它(JSON)」），因键不可预知才保留文本框，且正常应为空。 +- **复用 `designer_ui.gd` 辅助**：控件一律经 `UI.spin/line/opt/btn/cell_label/header/status_label/set_status/load_json/save_json` 创建；元素标签用共享常量 `UI.ELEM_LABELS`/`UI.ELEM_TAGS`。不要自建裸控件绕过。 +- **输入框须完整显示内容**：输入/下拉控件设 `size_flags_horizontal = Control.SIZE_EXPAND_FILL`（`designer_ui.gd` 的 `line/opt/spin` 工厂已内置），撑满面板宽度，长文本/长选项不截断。 +- **标签中英双语，中文在前**：所有枚举/选项显示用「中文 English」序（如 `动作 ACTION`、`火 Fire`、`矩阵 MATRIX`、`每 N 次 every_n_shots`）。 +- **显示与存储解耦**：`OptionButton` 存整数 index 或 key，**绝不**把双语显示串写进 JSON。显示标签数组与存储值数组分离（如 `LOGIC_OPS` 存 key、`LOGIC_OP_LABELS` 仅供下拉显示，二者 index 对齐）。 +- **数据往返一致 / 防丢键**：`_on_select` 回读 → `_on_apply` 应用应语义等价；未知键用逃生舱保留不丢；可选键为默认值时可省略以保持 JSON 简洁。 +- **改动后验证**：用 godot-mcp-pro `validate_script` 校验语法；对真实 `data/*.json` 跑回读往返（`execute_editor_script` 断言 `FAILS=0`）。⚠️ dock 里驻留的旧 GDScript 类需 `EditorInterface.restart_editor(true)` 清缓存后才测得到新代码（`reload_project`/`reload_plugin` **不**重编译已加载类）。 +- **纯数据驱动**：内容只存在于 `res://data/*.json`，代码不含硬编码副本或回退；文件缺失/格式错误应 `push_error` 明确报错，不静默用旧值。 +- **新增 `.gd` 记得提交同名 `.gd.uid`**（与既有组件一致）。 +- **新增分页 3 步**：`@tool extends VBoxContainer` 标签脚本（复用 `designer_ui.gd`）→ 在 `designer_panel.gd` 的 `_init()` 里 `_add_tab(...)` 注册 → 对应 Manager 加 `_load_json_xxx()` 于 `_ready()` 调用。