docs(designer): 整数元组列表编辑器实现计划
This commit is contained in:
@@ -0,0 +1,336 @@
|
||||
# 整数元组列表编辑器（edges / aether_thresholds 去 JSON）实现计划
|
||||
|
||||
> **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:** 新增可复用行编辑器 `tuple_list_editor.gd`，把 Core `edges`（电路边）与平衡 `aether_thresholds`（碎片阈值）从手写 JSON 改为 SpinBox 行编辑；spell `其它(JSON)` 不动。
|
||||
|
||||
**Architecture:** 一个 `@tool VBoxContainer` 组件（`setup`/`set_values`/`get_values`），数据模型 `Array[Array[int]]`；core_tab 在 `{from,to}` 字典与 `[from,to]` 数组间转换，balance_tab 直接用 `[波次,碎片]` 数组。运行时代码/数据格式零改动。
|
||||
|
||||
**Tech Stack:** Godot 4.6 (Mono) / GDScript `@tool`；验证用 godot-mcp-pro（`validate_script` / `execute_editor_script` / `reload_project`）。
|
||||
|
||||
**Spec:** `docs_dev/specs/2026-07-22-designer-tuple-list-editor-design.md`
|
||||
|
||||
**验证说明：** 沿用既有模式——每个改动文件 `validate_script` 校验；最后 `execute_editor_script` 对 `cores.json`/`balance.json` 回读往返（Task 4）。⚠️ core_tab/balance_tab 当前在编辑器 dock 里以旧编译类驻留，回读前需**重启编辑器**清 GDScript 类缓存（同上一增量，需用户确认）。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 新建 `tuple_list_editor.gd`
|
||||
|
||||
**Files:**
|
||||
- Create: `addons/game_designer/tuple_list_editor.gd`
|
||||
|
||||
- [ ] **Step 1: 写入完整脚本**
|
||||
|
||||
创建 `addons/game_designer/tuple_list_editor.gd`（保留 TAB 缩进）：
|
||||
|
||||
```gdscript
|
||||
## 整数元组列表编辑器（@tool）— 每行 N 个 SpinBox + 🗑 删行，底部 ➕ 加行。
|
||||
## 用于 Core edges（from/to）、balance aether_thresholds（波次/碎片）等可变长小整数元组列表。
|
||||
## 数据模型：Array[Array]（行数组）；调用方负责与自身 JSON 结构互转。
|
||||
@tool
|
||||
extends VBoxContainer
|
||||
|
||||
var _cols: Array = [] # [{label,min,max,step,int,default}]
|
||||
var _rows_box: VBoxContainer
|
||||
var _add_label: String = "➕ 加行"
|
||||
|
||||
func setup(col_specs: Array, add_label: String = "➕ 加行") -> void:
|
||||
_cols = col_specs
|
||||
_add_label = add_label
|
||||
_rows_box = VBoxContainer.new()
|
||||
add_child(_rows_box)
|
||||
var add_btn := Button.new()
|
||||
add_btn.text = _add_label
|
||||
add_btn.pressed.connect(_on_add)
|
||||
add_child(add_btn)
|
||||
|
||||
func set_values(rows: Array) -> void:
|
||||
if _rows_box == null:
|
||||
return
|
||||
for c in _rows_box.get_children():
|
||||
_rows_box.remove_child(c)
|
||||
c.free()
|
||||
for r in rows:
|
||||
_add_row(r)
|
||||
|
||||
func get_values() -> Array:
|
||||
var out: Array = []
|
||||
if _rows_box == null:
|
||||
return out
|
||||
for h in _rows_box.get_children():
|
||||
var row: Array = []
|
||||
var ci := 0
|
||||
for ch in h.get_children():
|
||||
if ch is SpinBox:
|
||||
var v: float = (ch as SpinBox).value
|
||||
var is_int: bool = bool(_cols[ci].get("int", true)) if ci < _cols.size() else true
|
||||
row.append(int(v) if is_int else v)
|
||||
ci += 1
|
||||
out.append(row)
|
||||
return out
|
||||
|
||||
func _on_add() -> void:
|
||||
_add_row([])
|
||||
|
||||
func _add_row(vals: Array) -> void:
|
||||
var h := HBoxContainer.new()
|
||||
for i in _cols.size():
|
||||
var c: Dictionary = _cols[i]
|
||||
var lbl := String(c.get("label", ""))
|
||||
if lbl != "":
|
||||
var l := Label.new(); l.text = lbl
|
||||
h.add_child(l)
|
||||
var sp := SpinBox.new()
|
||||
sp.min_value = c.get("min", 0)
|
||||
sp.max_value = c.get("max", 100000)
|
||||
sp.step = c.get("step", 1)
|
||||
sp.value = float(vals[i]) if i < vals.size() else float(c.get("default", c.get("min", 0)))
|
||||
sp.size_flags_horizontal = Control.SIZE_EXPAND_FILL
|
||||
h.add_child(sp)
|
||||
var del := Button.new()
|
||||
del.text = "🗑"
|
||||
del.pressed.connect(func(): _rows_box.remove_child(h); h.queue_free())
|
||||
h.add_child(del)
|
||||
_rows_box.add_child(h)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 校验**
|
||||
|
||||
调用 `mcp__godot-mcp-pro__validate_script`，`path = "res://addons/game_designer/tuple_list_editor.gd"`。Expected: 通过。
|
||||
|
||||
- [ ] **Step 3: 提交**
|
||||
|
||||
```bash
|
||||
git add addons/game_designer/tuple_list_editor.gd
|
||||
git commit -m "feat(designer): 新增整数元组列表行编辑器组件"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: `core_tab.gd` — edges 改行编辑器
|
||||
|
||||
**Files:**
|
||||
- Modify: `addons/game_designer/core_tab.gd`
|
||||
|
||||
（4 处 Edit，精确匹配，保留 TAB 缩进。）
|
||||
|
||||
- [ ] **Step 1: 成员变量类型**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var _edges: TextEdit
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var _edges: Control
|
||||
```
|
||||
|
||||
- [ ] **Step 2: `_ready()` —— edges 文本框换行编辑器**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var el := Label.new(); el.text = "电路边(CIRCUIT，JSON)"; add_child(el)
|
||||
_edges = TextEdit.new(); _edges.custom_minimum_size = Vector2(0, 50)
|
||||
_edges.placeholder_text = '[{"from":0,"to":1},{"from":0,"to":2}]'
|
||||
add_child(_edges)
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var el := Label.new(); el.text = "电路边(CIRCUIT，from → to)"; add_child(el)
|
||||
_edges = preload("res://addons/game_designer/tuple_list_editor.gd").new()
|
||||
_edges.setup([
|
||||
{"label": "from", "min": 0, "max": 63, "step": 1, "int": true},
|
||||
{"label": "→ to", "min": 0, "max": 63, "step": 1, "int": true}], "➕ 加边")
|
||||
add_child(_edges)
|
||||
```
|
||||
|
||||
- [ ] **Step 3: `_on_select()` —— 载入边**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
_edges.text = JSON.stringify(d.get("edges", []))
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var erows := []
|
||||
for e in d.get("edges", []):
|
||||
erows.append([int(e.get("from", 0)), int(e.get("to", 0))])
|
||||
_edges.set_values(erows)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: `_on_apply()` —— 组装边**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var edges = JSON.parse_string(_edges.text) if _edges.text.strip_edges() != "" else []
|
||||
if not (edges is Array):
|
||||
edges = []
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var edges := []
|
||||
for r in _edges.get_values():
|
||||
edges.append({"from": r[0], "to": r[1]})
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 校验**
|
||||
|
||||
`mcp__godot-mcp-pro__validate_script`，`path = "res://addons/game_designer/core_tab.gd"`。Expected: 通过。
|
||||
|
||||
- [ ] **Step 6: 提交**
|
||||
|
||||
```bash
|
||||
git add addons/game_designer/core_tab.gd
|
||||
git commit -m "feat(designer): Core 电路边改行编辑器（去 JSON）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: `balance_tab.gd` — aether_thresholds 改行编辑器
|
||||
|
||||
**Files:**
|
||||
- Modify: `addons/game_designer/balance_tab.gd`
|
||||
|
||||
- [ ] **Step 1: 成员变量类型**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var _aether: TextEdit
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var _aether: Control
|
||||
```
|
||||
|
||||
（注意：该 `var` 声明位于文件顶部成员区，缩进为单 TAB；按文件实际缩进匹配。）
|
||||
|
||||
- [ ] **Step 2: `_ready()` —— aether 文本框换行编辑器**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var al := Label.new(); al.text = "碎片奖励阈值 aether_thresholds（JSON [[波次,碎片],...]）"; add_child(al)
|
||||
_aether = TextEdit.new(); _aether.custom_minimum_size = Vector2(0, 50)
|
||||
_aether.text = JSON.stringify(_data.get("aether_thresholds", [[1, 0], [5, 3], [10, 8], [15, 14], [20, 20]]))
|
||||
add_child(_aether)
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var al := Label.new(); al.text = "碎片奖励阈值 aether_thresholds（波次 → 碎片）"; add_child(al)
|
||||
_aether = preload("res://addons/game_designer/tuple_list_editor.gd").new()
|
||||
_aether.setup([
|
||||
{"label": "波次", "min": 1, "max": 9999, "step": 1, "int": true},
|
||||
{"label": "碎片", "min": 0, "max": 9999, "step": 1, "int": true}], "➕ 加行")
|
||||
add_child(_aether)
|
||||
_aether.set_values(_data.get("aether_thresholds", [[1, 0], [5, 3], [10, 8], [15, 14], [20, 20]]))
|
||||
```
|
||||
|
||||
- [ ] **Step 3: `_save()` —— 读取阈值**
|
||||
|
||||
old:
|
||||
```gdscript
|
||||
var thresholds = JSON.parse_string(_aether.text) if _aether.text.strip_edges() != "" else []
|
||||
if not (thresholds is Array):
|
||||
thresholds = []
|
||||
```
|
||||
new:
|
||||
```gdscript
|
||||
var thresholds := _aether.get_values()
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 校验**
|
||||
|
||||
`mcp__godot-mcp-pro__validate_script`，`path = "res://addons/game_designer/balance_tab.gd"`。Expected: 通过。
|
||||
|
||||
- [ ] **Step 5: 提交**
|
||||
|
||||
```bash
|
||||
git add addons/game_designer/balance_tab.gd
|
||||
git commit -m "feat(designer): 平衡碎片阈值改行编辑器（去 JSON）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 全量验证（重启 + 回读往返）
|
||||
|
||||
**Files:**
|
||||
- 无（MCP 验证）
|
||||
|
||||
- [ ] **Step 1: 重启编辑器清类缓存**
|
||||
|
||||
core_tab/balance_tab 在 dock 中以旧类驻留，需重启。**先征得用户同意**，然后调用 `mcp__godot-mcp-pro__execute_editor_script`，`code = "EditorInterface.restart_editor(true)"`（连接会断开，等待 ~20s 重连）。
|
||||
|
||||
- [ ] **Step 2: 重连后查错**
|
||||
|
||||
`mcp__godot-mcp-pro__reload_project`（如需）→ `mcp__godot-mcp-pro__get_editor_errors`（max_lines 40）。Expected: 无与本次相关报错。
|
||||
|
||||
- [ ] **Step 3: Core edges 回读往返**
|
||||
|
||||
`mcp__godot-mcp-pro__execute_editor_script`，`code`：
|
||||
```gdscript
|
||||
var tab = load("res://addons/game_designer/core_tab.gd").new()
|
||||
EditorInterface.get_base_control().add_child(tab)
|
||||
var raw = JSON.parse_string(FileAccess.get_file_as_string("res://data/cores.json"))
|
||||
var fails = []
|
||||
for cid in raw:
|
||||
var found = false
|
||||
for i in tab._list.item_count:
|
||||
if String(tab._list.get_item_metadata(i)) == cid:
|
||||
tab._on_select(i); found = true; break
|
||||
if not found:
|
||||
fails.append(cid + ":未在列表"); continue
|
||||
var got = []
|
||||
for r in tab._edges.get_values():
|
||||
got.append([int(r[0]), int(r[1])])
|
||||
var orig = raw[cid].get("edges", [])
|
||||
if got.size() != orig.size():
|
||||
fails.append("%s:edges数 %d!=%d" % [cid, got.size(), orig.size()])
|
||||
else:
|
||||
for i in got.size():
|
||||
if got[i][0] != int(orig[i].get("from",0)) or got[i][1] != int(orig[i].get("to",0)):
|
||||
fails.append("%s:edge#%d %s vs %s" % [cid, i, str(got[i]), str(orig[i])])
|
||||
_mcp_print("CORE FAILS=%d %s" % [fails.size(), str(fails)])
|
||||
tab.queue_free()
|
||||
```
|
||||
Expected: `CORE FAILS=0 []`。（`circuit_fork` 两条边 [0,1]/[0,2]；其余 core 无 edges → got 空、orig 空数组，size 均 0，等价。）
|
||||
|
||||
- [ ] **Step 4: Balance aether 回读往返**
|
||||
|
||||
`mcp__godot-mcp-pro__execute_editor_script`，`code`：
|
||||
```gdscript
|
||||
var tab = load("res://addons/game_designer/balance_tab.gd").new()
|
||||
EditorInterface.get_base_control().add_child(tab)
|
||||
var raw = JSON.parse_string(FileAccess.get_file_as_string("res://data/balance.json"))
|
||||
var orig = raw.get("aether_thresholds", [])
|
||||
var got = tab._aether.get_values()
|
||||
var fails = []
|
||||
if got.size() != orig.size():
|
||||
fails.append("size %d!=%d" % [got.size(), orig.size()])
|
||||
else:
|
||||
for i in got.size():
|
||||
if int(got[i][0]) != int(orig[i][0]) or int(got[i][1]) != int(orig[i][1]):
|
||||
fails.append("row#%d %s!=%s" % [i, str(got[i]), str(orig[i])])
|
||||
_mcp_print("BALANCE FAILS=%d %s" % [fails.size(), str(fails)])
|
||||
tab.queue_free()
|
||||
```
|
||||
Expected: `BALANCE FAILS=0 []`（5 行 [[1,0],[5,3],[10,8],[15,14],[20,20]]）。
|
||||
|
||||
- [ ] **Step 5: 目测（用户确认）**
|
||||
|
||||
重启后由用户在 Core 页/平衡页确认：电路边为 from/to 行、平衡碎片为 波次/碎片 行，均可 ➕加/🗑删。若 Step 3/4 触发修复则相应 `git add && git commit`；否则本任务无提交。
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**Spec 覆盖：**
|
||||
- §2 组件 `tuple_list_editor.gd`（setup/set_values/get_values/加删行）→ Task 1 ✅
|
||||
- §3 core edges 集成（dict↔array）→ Task 2 ✅
|
||||
- §4 balance aether 集成 → Task 3 ✅
|
||||
- §6 验证（validate + 回读往返 core/balance）→ Task 4 ✅
|
||||
- §7 spell 其它(JSON) 不动 → 无任务触碰 ✅
|
||||
|
||||
**占位符扫描：** 无 TBD/TODO；每步含完整代码或精确命令。✅
|
||||
|
||||
**类型/命名一致性：** `_edges`/`_aether` 由 TextEdit→Control（Task 2/3 定义，Task 4 回读用 `tab._edges`/`tab._aether`）；`setup`/`set_values`/`get_values`（Task 1 定义，Task 2/3/4 调用一致）；行数据模型 `Array[Array]` 全程一致。✅
|
||||
|
||||
**已知取舍：** LINEAR/MATRIX 法杖应用后仍会写 `edges:[]`（既有行为，非本次引入）；回读把「空数组 == 缺 edges 键」按 size 0 视为等价。
|
||||
Reference in New Issue
Block a user