用AI优化关卡与策划

写在最前

到这里你应该已经有了一个能跑通一局的弹珠肉鸽骨架。但你打开自己的工程，把朋友拉来玩 5 分钟，大概率会听到：

"诶，怎么一直只有那一种道具？"
"这球数加多少减多少是怎么定的？我感觉差了一点。"

这一节课要向游戏添加更多可玩性，更多"策划"：

道具系统不够"肉鸽"：肉鸽的灵魂是"局内每次都不一样"和"build流派"。道具要互相配合，形成清楚的玩法方向。你需要一个三选一道具机制，从"道具一共分几大类"到"具体每件道具的文本/数值/触发效果"，全部跑通。
快速进行数值调整：每次想调一下"奖励袋洞 +3 改成 +2 试试"，你都要去翻 03_rules.md、改导出参数、重启项目、重新跑一局——一个改动 5 分钟，迭代 20 次就是一下午。你需要一个游戏运行时就能直接拖滑条改数值的小面板，改完立刻生效，改满意了一键存成 JSON 配置文件。

💡 为什么这一节课特别值得花时间？ 因为这节课要做的，是让你(和你的设计师朋友)能更舒服工作的工具。这一节课的产出不止"道具机制策划案"，而是你的整个设计工作流。

一、动手前先翻一次 Bible

老规矩：写代码前，先翻 Bible。这节课要做的两件事，对照 05 课的 _index.md 速查表，涉及如下：

你要改什么	读哪个文件	对应到本次任务
加新实体（道具是新实体）	02_entities.md	✅ 涉及（要新增"道具"实体大类，并在下面挂 6 个子类）
调数值 / 写规则	03_rules.md	✅ 涉及（数值面板里所有可调字段都在这里有声明）
改 UI / HUD	05_ui_hud.md	✅ 涉及（三选一选择面板、数值面板都是 UI）
加新模块 / 调目录	07_file_layout.md	✅ 涉及（新增 design/items/、scripts/debug/、scenes/debug/）
加调试与开发工具	08_dev_tools.md（本节首次使用）	✅ 涉及（测试面板、快捷键、日志通道）

第一件事，新建 bible/08_dev_tools.md，未来所有调试 / 测试 / 编辑器工具的约定都进这里。

写代码前，先问 AI：这次要做的功能，需要先在 Bible 里补哪些基础约定？把它返回的写进 Bible：

二、模块 A · 三选一道具：从脚手架到具体道具

这一段是最长的一段。你会看到三轮对话：

第 1 轮：让 AI 给你生成一个"道具脚手架"——目录结构 + 数据格式 + 命名规范，不要写任何具体道具。（同时设计6-9个能形成2-3个build方向的道具，例如多球、高倍率、控制或风险收益。）
第 2 轮：让 AI 填充每个一级类下的具体道具——文本 + 效果参数 + 稀有度，30 条数据 JSON。
第 3 轮：让 AI 写单道具效果脚本 + 测试面板——快捷键触发、独立测试场景、运行时日志。

2.1 第 1 轮对话：生成"道具脚手架"，不要具体道具

打开 CodeBuddy，新建会话。让它先读 Bible 的相关段落，然后给出"脚手架级别"的设计：

Prompt 1.A · 道具脚手架(不要具体道具,不要代码)

请你先完整阅读以下文件：bible/_index.md、bible/02_entities.md、bible/03_rules.md、bible/07_file_layout.md。

看完之后，帮我把"道具系统"的整体框架画出来。这一轮先别写具体道具，也别写代码，用大白话告诉我就行。

请回答下面这几个问题：

1. 02_entities.md 里已经定下来的 6 大类(ball_count / trajectory / peg_effect / pocket_effect / time_effect / meta)，你觉得每件道具最少要包含哪些信息(比如名字、效果类型、参数、什么时候触发)?能否组成2-3个build流派？在代码里用什么方式来描述一件道具?请给我两个不同的写法,并告诉我你更推荐哪个、为什么。

2. 这 30 件道具的数据,是写在每个 .gd 脚本里好(每件一个文件),还是统一写在一个 items.json 里好?请把两种做法各自的好处和坏处列给我。

3. 帮我规划一下 design/items/ 和 scripts/items/ 这两个文件夹下面应该放哪些文件,每个文件做什么事,一句话说清楚。

4. 过关时弹出来的"三选一"面板,应该怎么放进现有的界面?请直接引用 05_ui_hud.md 里已经有的界面节点,不要新发明。

5. 你看完之后,如果发现 Bible 有哪里写得不够清楚、需要我先拍板的,请用 (C1)、(C2)、(C3)... 编号列出来,我会在下一轮一起回答。

⚠️ 新手最常踩的坑：第 1 轮就让 AI 列 30 条具体道具。AI 会非常乐意——但你会发现 30 条里有"狂战士之怒"这种风格不搭、还有 6 条效果一模一样只是换了个名字的"垃圾道具"。先让 AI 把"几大类"和"道具长什么样"敲定,再让它在每类里独立填充——这样 AI 在每一类内部会自动避免重复,因为它能看到同类已经有什么。

AI 第 1 轮可能的回答(参考样本)

问题 1：每件道具最少需要的信息 + 两种写法 + 推荐

按 6 大类逐一拆解"道具最少需要什么"

(A) ball_count 类（影响球数增减）

信息	说明
名字	"多球"、"双倍收益"
效果类型	`ball_count`
触发时机	本局全局/每次落袋/发射时
参数	数值 `+N`（带符号）
单局/永久	本局有效，还是永久
可叠加	同名道具能不能拿多次
icon	小图

(B) trajectory 类（改变弹道）

信息	说明
名字	"扩散弹"、"精准瞄准"
效果类型	`trajectory`
触发时机	每颗球发射时（覆盖 Launcher 的默认偏角）
参数	角度偏移量 `±N` 度；或 `bounce` 修正值
图标	小图

(C) peg_effect 类（图钉相关效果）

信息	说明
名字	"磁力钉"、"弹跳增幅"
效果类型	`peg_effect`
触发时机	球碰撞图钉时
参数	如反弹系数 `+X`、吸引力度
是否消耗性	持久的还是一次性的
图标	小图

(D) pocket_effect 类（袋洞/普通区域结算修正）

信息	说明
名字	"袋洞双倍"、"失误减半"
效果类型	`pocket_effect`
触发时机	球落入袋洞/普通区域时（拦截 GameManager.adjust_balls）
参数	乘数 `×2`，或偏移 `-1→0`
图标	小图

(E) time_effect 类（倒计时相关）

信息	说明
名字	"时间冻结"、"额外时间"
效果类型	`time_effect`
触发时机	即时/每局开始/濒临归零时
参数	秒数 `+N`，或冻结持续秒数
图标	小图

(F) meta 类（跨系统通用）

信息	说明
名字	"护盾"、"重选"、"锁定发射器"
效果类型	`meta`
触发时机	取决于具体效果（扣球时/立刻/开局）
参数	可变（抵挡次数、重选次数）
图标	小图

一句话总结： 每件道具的最小字段集 = name + category + trigger_timing + params(dict) + one_shot_or_permanent + max_stacks + description + icon。

两种写法

写法 A：Resource 继承体系（当前方案）

multiball_item.gd

# multiball_item.gd
extends ItemData
class_name MultiballItem

func _init() -> void:
    item_name = "多球"
    description = "本局额外获得 3 颗初始弹珠"
    category = ItemData.Category.BALL_COUNT
    trigger_timing = ItemData.Timing.ON_EQUIP
    params = {"bonus_balls": 3}
    max_stacks = 1
    one_shot = true

func apply(gm: Node) -> void:
    gm.ball_count += params["bonus_balls"]
    gm.ball_count_changed.emit(gm.ball_count)

func remove(gm: Node) -> void:
    pass  # one_shot 道具不需要撤消

每种道具一个 .gd 文件，类名即标识，逻辑写在 apply/remove 里。

写法 B：纯数据驱动（JSON + 通用解析器）

items.json

// items.json
[
  {
    "id": "multiball",
    "name": "多球",
    "category": "ball_count",
    "trigger": "on_equip",
    "params": {"bonus_balls": 3},
    "max_stacks": 1,
    "one_shot": true,
    "description": "本局额外获得 3 颗初始弹珠"
  }
]

item_resolver.gd

# item_resolver.gd
func apply_item(item_dict: Dictionary, gm: Node) -> void:
    match item_dict["category"]:
        "ball_count":
            if item_dict["trigger"] == "on_equip":
                gm.ball_count += item_dict["params"]["bonus_balls"]

30 件道具全部写在一个 JSON 里，由一个解析器统一根据 category+trigger 分发。

我推荐写法 A 的变体：Resource + 轻量数据分离

理由：

写法 B 的问题： 30 件道具的 JSON 里只靠 category+trigger 分发太脆了——只要来一件"平时冻结时间、但落袋时额外 +1"的混合道具，match 逻辑就爆炸。你最终还是要给特殊道具写特殊分支，JSON 的优势就没了。
写法 A 的问题： 每件道具一份 .gd 文件，对于"多球"这种只有一行 gm.ball_count += 3 的道具来说，30 个文件里有一半都是样板代码。
折中方案： 保留 ItemData Resource 基类，把"纯数值型"道具（如 +3 球、偏角 ±15°、袋洞 ×2）做成一个 GenericParamItem 子类，在 Inspector 里填参数就行，不需要新建 .gd 文件。只有逻辑复杂、需要拦截多个信号的特殊道具（如"护盾格挡"、"冻结时间且球数 -1 时解除冻结"）才单独建 .gd。

这样可以做到：约 70% 的道具是 Resource 实例 + 通用类 + 参数配置，30% 的道具是需要单独 .gd 的特殊逻辑。

问题 2：30 件道具数据放哪？JSON vs .gd

维度	每件一个 .gd（继承 ItemData）	统一 items.json
可读性	✅ 每件道具逻辑独立，一目了然	❌ 30 个对象挤在一起，参数多了容易看错
复杂逻辑	✅ 可以随便写代码、连信号、调状态	❌ JSON 只能描述数据，特殊逻辑要另加分支
新增道具	一般：创建新文件 + class_name	✅ 只需要在 JSON 里加一条
策划友好度	❌ 策划不敢碰 .gd	✅ 策划可以直接改 JSON
类型安全	✅ Godot 编译期检查 class_name	❌ 字符串 key 写错没人告诉你
Godot 集成	✅ Resource 可在 Inspector 编辑	❌ JSON 无法直接用 Inspector 编辑
维护 30 件	❌ 30 个文件，样板代码多	✅ 一个文件找起来快
混合道具	✅ 新建脚本随便写	❌ match 分支会越来越多，最终变成大 if-else
存档/序列化	一般：需要自己序列化	✅ JSON 天然适合存档

结论： 不推荐纯 JSON。推荐 Godot Resource（.tres）+ 脚本兜底：

基础数值道具 → .tres Resource 文件（multiball.tres 继承 GenericParamItem.gd），Inspector 可视化编辑
复杂逻辑道具 → 独立 .gd 脚本

兼顾了策划友好（.tres 有 Inspector）和灵活性（复杂道具可以写代码）。

问题 3：design/items/ 和 scripts/items/ 文件规划

                      design/items/
                      
                    
design/items/                    # 设计文档层（不编译，纯策划用）
├── _index.md                    # 道具系统总览：30 件道具的 ID/名字/大类速查表
├── categories.md                # 6 大类定义：每类触发时机、预期设计范围
├── items_by_ball_count.md       # ball_count 类 5 件道具的详细设计说明
├── items_by_trajectory.md       # trajectory 类 5 件道具的详细设计说明
├── items_by_peg_effect.md       # peg_effect 类 5 件道具的详细设计说明
├── items_by_pocket_effect.md    # pocket_effect 类 5 件道具的详细设计说明
├── items_by_time_effect.md      # time_effect 类 5 件道具的详细设计说明
├── items_by_meta.md             # meta 类 5 件道具的详细设计说明
└── selection_rules.md           # 三选一随机规则、稀有度、出现条件

                      scripts/items/
                      
                    
scripts/items/                   # 代码层
├── item_data.gd                 # Resource 基类：name/desc/category/trigger/params/icon + apply()/remove()
├── generic_param_item.gd        # 通用数值道具子类：从 params dict 自动 apply，覆盖 70% 道具
├── item_manager.gd              # Autoload：已装备列表管理 + 随机抽选 + equip/unequip/clear
├── triggers/                    # 触发器绑定（连接 GameManager 信号）
│   ├── trigger_on_land.gd       # 球落袋洞/普通区域时触发效果
│   ├── trigger_on_peg.gd        # 球碰图钉时触发效果
│   ├── trigger_on_fire.gd       # 发射球时触发效果
│   └── trigger_on_equip.gd      # 装备瞬间触发效果
└── special_items/               # 复杂逻辑道具（每个需要特殊代码的放这里）
    ├── shield_item.gd           # 护盾：拦截 -1，消耗后销毁
    ├── time_freeze_item.gd      # 时间冻结：暂停倒计时 N 秒
    ├── reroll_item.gd           # 重选：下次三选一可免费刷新
    └── ...                      # 其他无法被 generic_param 覆盖的道具

一句话总结：

design/items/ → 策划写"这个道具应该干什么"
scripts/items/ → 程序员写"这个道具怎么干"
generic_param_item.gd → 简单道具不用写代码，填参数即可
special_items/ → 特殊道具一个文件一个效果

问题 4：三选一弹窗怎么放进现有 HUD？

当前 05_ui_hud.md 中已有的 HUD 节点结构是：

现有 HUD 节点结构

HUD (CanvasLayer)
├── TopBar/BallCount      (Label)
├── TopBar/Timer          (Label)
├── TopBar/Progress       (ProgressBar)
│   └── Label
├── SettleArea/SettleButton (Button)
├── WinPanel              (Panel)
│   └── VBox/FinalCount   (Label)
│   └── VBox/NextBtn      (Button)
└── LosePanel             (Panel)
    └── VBox/FinalCount   (Label)
    └── VBox/RetryBtn     (Button)

推荐方案： 在 LosePanel 同级加一个 ItemChoicePanel (Panel)，作为 HUD 的第三个面板。

                      新增 ItemChoicePanel
                      
                    
HUD (CanvasLayer)
├── ...（现有节点不动）
├── WinPanel              (Panel)     ← 已有
├── LosePanel             (Panel)     ← 已有
└── ItemChoicePanel       (Panel)     ← 新增
    ├── TitleLabel        (Label)     "选择一件道具"
    ├── CardContainer
    │   ├── ItemCard_0    (Control)   名字 + 描述 + 选择按钮
    │   ├── ItemCard_1    (Control)
    │   └── ItemCard_2    (Control)
    └── SkipButton        (Button)    "跳过"（可选）

为什么不沿用当前做法（GameManager spawn 到 root）：

当前 _spawn_item_choice_panel() 把面板挂在 /root 上，绕过了 HUD——这意味着面板不遵循 HUD 的 z-order、canvas 层管理。
面板应该和 WinPanel/LosePanel 平级：它们是一组"阶段性结算面板"——晋级弹 WinPanel，失败弹 LosePanel，晋级后弹 ItemChoicePanel。放在同一个 CanvasLayer 下更容易做显隐互斥（同时只有一个可见）。

流程：

round_finished(success=true) → HUD 显示 WinPanel
用户点击 NextBtn → HUD 关闭 WinPanel → 弹出 ItemChoicePanel
用户选完道具 → ItemChoicePanel 关闭 → GameManager.start_round() 下一局

这样 ItemChoicePanel 就是 HUD 的子节点，由 hud.gd 统一管理显隐，不需要 GameManager 越级 spawn。

问题 5：Bible 写不清楚，需要你先拍板的点

(C1) 02_entities.md 里图钉明确了 MVP 阶段"不奖励球、不扣球、不消失"，但 6 大类里有一个 peg_effect 类。那道具系统中的 peg_effect 类，是 MVP 就做，还是留给 P2+ 再动？如果 MVP 要做，那你允许道具打破"图钉无效果"这条铁律吗？（例如"撞击图钉时袋洞奖励临时 +1"）

(C2) 道具系统在 4 份 Bible 文件里一个字都没提。07_file_layout.md 里没有 scripts/items/ 的预留位，03_rules.md 没有道具对球数/时间/胜负的影响规则。你现在是否要把道具系统正式纳入 Bible？如果是，会影响哪些已有规则（如：道具效果是否允许超过"禁止的行为"里列的红线）？

(C3) 道具之间是否可叠加、是否有上限？比如"多球 +3"拿两次是变成 +6 还是只生效一次？护盾拿两次是挡 2 次还是 1 次？这个规则需要你定，否则 max_stacks 字段没法填。

(C4) 三选一的 3 件道具从哪来——是无脑从 30 件里随机抽 3？还是有稀有度分池（普通/稀有/史诗）？还是根据当前球数/剩余时间来聪明推荐（落后给强力道具，领先给花活道具）？这直接影响 get_random_choices() 的实现。

(C5) 道具的生效时机和 GameManager 的 Phase 状态机怎么交互？比如"时间冻结 10 秒"，如果冻结期间玩家手动点了结算，冻结应该立刻解除吗？如果冻结算期间倒计时刚好走完、且冻结还在——算不算输？这些边界条件不在 Bible 里，但代码必须处理。

(C6) 05_ui_hud.md 里晋级面板只有标题 + 球数 + "下一局"按钮，没提道具选择。如果把三选一插在"下一局"按钮之后，流程变成：点击下一局 → 缩起 WinPanel → 弹出 ItemChoicePanel → 选完才开始下一局——这个交互顺序你认可吗？还是三选一应该出现在结算前（比如球数刚到 60 时立刻暂停、弹出选择）？

以上 6 个待拍板点你可以按 (C1)~(C6) 编号在下一轮给我答复，拿到答案后我再画实现细节。

让 AI 把不清楚的地方主动说出来。所有这些问题如果你不在第 2 轮回答,AI 会在第 3 轮自己拍板——而它的拍板大概率不是你想要的。

示例回答：

(C1) MVP 就做 peg_effect 类。道具可以打破"图钉无效果"的默认状态，道具是对默认状态的覆盖。

(C2) 是，道具系统纳入 Bible。这节课做完后统一回写，scripts/items/ 补进 07_file_layout.md，道具对球数/时间的影响规则补进 03_rules.md。

(C3) MVP 阶段所有道具 max_stacks = 1，同一件买两次无效，不做叠加。

(C4) 按稀有度分池随机抽，3张里 2 common + 1 rare，epic 暂不进 MVP 池。不做智能推荐。

(C5) 冻结期间玩家点结算，冻结立即解除，正常判定。冻结期间倒计时归零，冻结失效，正常失败。

(C6) 顺序是：晋级 → WinPanel → 点下一局 → ItemChoicePanel → 选完开始下一局。

2.2 第 2 轮对话：填具体道具数据

第 2 轮做两件事：(a) 回答刚刚列举出的问题；(b) 让 AI 按一级类逐类填道具。

Prompt 1.B · 具体道具填充

现在请你按下面的规则，把 design/items/items.json 填好：

一类一类地填，先填完一个大类再填下一个，类与类之间空一行，方便我审阅。

数量按 02_entities.md 表格里的"当节产出件数"那一列：ball_count 6 件，trajectory 5 件，peg_effect 6 件，pocket_effect 5 件，time_effect 4 件，meta 4 件。一共 30 件。

每件道具必须填这 8 个字段：id、name、desc、category、rarity、effect_trigger、effect_id、params。

id 命名规范：{category}_{effect_id}_{档位}，比如 ball_count_add_balls_5。

name 用中文，3-7 个字，不要"狂战士之怒"那种风格的低质量文本，要弹珠机/老式街机/像素游戏厅那种感觉(比如"加倍发条"、"软心橡胶"、"加时器")。

desc 一句话不超过 25 个字，必须把"什么时候触发 + 数值"说清楚。

稀有度比例每一类内部都要均衡：每一类里 common ≥ rare ≥ epic。

不要凭空发明新的 effect_id——如果某个想法需要新的 effect_id，请单独写在 JSON 后面，用 // new_effects: 这种注释告诉我，由我来决定要不要加进 ItemRegistry。

这一轮还是只填数据，不要写代码。

⚠️ 新手最常踩的坑：让 AI 自由"发挥效果"。你会得到一堆"每过 7 秒触发一次连锁爆炸 + 减速 30%"这种依赖了 4 个新触发点的"复合效果"。要硬性规定 effect_id 必须从已经声明过的列表里选——想加新的必须先报备、由你拍板,这样系统不会越长越复杂。

AI 第 2 轮产出(节选示意)

items.json（节选）

{
    "id": "ball_count_pocket_bonus_1",
    "name": "袋洞嘉奖",
    "desc": "落入袋洞时额外+1球",
    "category": "ball_count",
    "rarity": "common",
    "effect_trigger": "on_land_bucket",
    "effect_id": "pocket_bonus",
    "params": { "amount": 1 }
  },
  {
    "id": "ball_count_penalty_reduce_1",
    "name": "落地软垫",
    "desc": "落入普通区损失-1→0",
    "category": "ball_count",
    "rarity": "common",
    "effect_trigger": "on_land_normal",
    "effect_id": "penalty_reduce",
    "params": { "amount": 1 }
  }

🎯 审阅清单：

打开 30 行 JSON 通读一遍，看名字风格是否统一。
同一类内部，common/rare/epic 比例是否符合 60/30/10 的概率？不符合直接让 AI 重排稀有度。
每件道具的 desc 是否 ≤25 字？长了让 AI 重写。
效果是否有"无聊重复"/无流派？比如 ball_count 6 件里 4 件都是不同档位的 +球，1 件是不同档位的 +袋洞——这是垃圾道具的开始。让 AI 在重复类做差异化。

AI生成的道具名字（"备用弹珠"、"高弹橡胶"、"精准弹道"）太功能性、太白板，可以增加一轮对话来让道具名称更贴合背景设定：

Prompt · 道具名称修饰

修改items.json，name 用中文，3-7个字。风格必须符合《糖狱逃脱》的黑暗甜品童话世界观。
参考已有道具名的正确风格：奶油加速器、救赎扩张符、焦糖护盾、双球令、时间糖浆、碎糖弹。
命名素材库：从以下元素里取词组合——
【甜品材料】焦糖、奶油、糖浆、马卡龙、松露、泡芙、蜜糖、糖衣、结晶糖、脆皮
【状态/动作】加速、爆裂、融化、凝固、反弹、渗透、冻结、碎裂、涌动
禁止出现的词风：武侠("狂战士之怒")、科幻("量子弹道")、过于现代("超级发条")。
禁止出现纯功能描述词当名字("精准弹道"、"高弹橡胶"这种)。

2.3 第 3 轮对话：实现 effect 脚本 + 测试面板

第 3 轮一次让 AI 做两件事：(a) 实现功能；(b) 写测试面板，让你不用打完整一局也能验证道具效果。

Prompt 1.C · 道具效果代码 + 测试面板

现在请你帮我把下面这些东西做出来：

A. 道具效果代码

1. 做一个总管道具的文件 scripts/items/item_registry.gd，让它在游戏一启动就自动跑起来。它的工作是：把 design/items/items.json 读进来，记住每件道具是什么，并且知道每个效果该怎么执行。
   它对外开放两个用法：
   - 我给它一个道具 id，它能把这件道具的完整信息还给我；
   - 我给它一件道具和当前的游戏情况，它能帮我把这件道具的效果触发出来。

2. 把"改球数"这一类的效果写在一个文件里：scripts/items/effects/ball_count.gd。
   这个文件里要能处理三种效果：加球（add_balls）、进袋洞额外加球（pocket_bonus）、进普通区不掉球（block_normal_loss）。

3. 把"改弹珠手感"这一类的效果写在一个文件里：scripts/items/effects/trajectory.gd。
   这个文件里要能处理四种效果：改反弹（set_restitution）、改摩擦（set_friction）、改重力（set_gravity）、改最大速度（set_max_velocity）。

4. 剩下的四类（peg_effect / pocket_effect / time_effect / meta）也照同样的方式，每一类一个文件，把这一类下面要做的事情写进去。

B. 测试面板（这部分最重要！）

5. 做一个单独的场景 scenes/debug/ItemTestConsole.tscn，它能独立打开，不依赖正式游戏流程。我希望按 F5 启动游戏后，主菜单里能看到一个"道具测试"的选项，点进去就到这个面板。

6. 这个面板长这样：
   - 左边：列出全部 30 件道具，按类分好组，能滚动。
   - 中间：摆一个简化版的弹珠场地——一个发射器、几颗钉子、一个袋洞，够我看到道具效果就行。
   - 右边：一块日志区域，每次有效果触发了，就在这里打一行字，告诉我"什么时间、触发了什么效果、当时游戏处于什么状态"。
   - 底部：放 5 个按钮——"重置局面"、"模拟过关开始"、"模拟进袋洞"、"模拟撞钉子"、"清空日志"。
   - 快捷键：键盘上的 1-9 这几个数字键，用来对左边选中的那件道具直接触发它对应的模拟事件；F1 在日志里打印一下当前游戏的整体状态；F2 把局面重置一下。

7. 我希望每件道具在这个面板里都能直接验证到效果，不用我去打完一整局才看到。

8. 这个面板不要影响正式游戏。我打开正式入口（Main.tscn）的时候，不应该看到这个面板的任何痕迹。

请按 A → B 的顺序输出。

图 6 · Godot运行ItemTestConsole的实机截图「按类分组 · C/R/E稀有度色标」「选中道具显示详情」「触发记录实时输出」

⚠️ 新手最常踩的坑：没有测试面板，靠"打一整局"来验证道具。结果你为了测一件 epic 道具(5% 概率掉落)，玩了 20 局都没掉到。测试面板是肉鸽项目的命——任何随机出现的内容(道具、敌人、事件、Boss 阶段)，都必须有"无视概率,直接调出来看"的快捷键。

⚠️ 新手最常踩的坑：信 AI 说的"我自测了所有道具"——它没有，它压根跑不了 Godot。让它在文件底部诚实写"我自测了 X 件，未自测 Y 件，原因是依赖 Z"，未自测的列表就是你的 QA 任务清单。

💡 小贴士：让ai给出验证/测试方法，写进 bible/08_dev_tools.md 里"道具系统测试"段落。下次有新道具加入时，再次矫正。Bible 不只写"是什么"，也写"怎么测"。

三、模块 B · 数值面板：可视化调节 + 导出 JSON

模块 A 你已经看出"AI 写工具"的威力了。模块 B 做一个游戏运行中就能用的数值面板，让你(和你的策划朋友)不再"改数字 → 重启 → 再改 → 再重启"。

3.1 数值面板要解决的真实痛点

回想你这一周的工作：

改 start_balls 50→40，要进编辑器、点 GameManager.tscn、改导出参数、保存、F5 测试，30 秒。
改完发现 40 太少，再 40→45，又是 30 秒。
一晚上你这个数字改了 12 次，6 分钟全花在"改 → 重启" 上。

数值面板要实现的目标：

游戏运行中直接拖滑条改 Bible 列出的字段。
改完立即生效——下一颗弹珠的物理参数已经变了，下一局的起始球数已经变了。
一键保存为 design/balance/values.json，也能一键回滚到 Bible 默认值。
JSON 里记录修改时间 + 修改人备注(一行 // L 调整:袋洞 +3 改 +2,因为玩家反馈过爽)。
正式打包时数值面板自动消失(只在调试运行时出现，打包发布版根本看不到)。

3.2 第 1 轮对话：让 AI 给方案，不要写代码

Prompt 2.A · 数值面板方案

请你先完整阅读以下文件：
- docs/bible/03_rules.md（重点看"可改数值字段清单 DEC-017"那一段）
- docs/bible/07_file_layout.md
- docs/bible/08_dev_tools.md

阅读完成后，用中文回答以下问题，不要写任何代码：

1. 我需要一个Godot 4的EditorPlugin，在编辑器顶部菜单栏出现「数值编辑器」入口，点开后在编辑器底部出现停靠面板，面板里每个字段用"滑条+输入框"双联控件显示。你打算把这个插件拆成哪几个文件？每个文件一句话说清楚它做什么事。

2. 面板里的10个字段（见03_rules.md的DEC-017表格），每个字段对应一个HSlider+SpinBox。拖动HSlider时SpinBox实时同步，反之亦然。在Godot 4里实现这个双向同步，你打算用什么信号？会不会出现循环触发的问题？你怎么解决？

3. 点「保存为JSON」后，数据写入 res://data/balance_config.json。游戏运行时GameManager.gd读这个JSON作为数值来源。请问GameManager读JSON这部分，你打算改动GameManager的哪个函数？改动范围有多大？

4. 你看完Bible之后，发现有哪些地方没说清楚、需要我先确认的？请用(C1)(C2)...编号列出。

⚠️ 新手最常踩的坑：把"立即生效"做成"每帧读 JSON"。AI 真的可能这么写——每一帧都打开文件 → 解析 JSON → 赋值。这会让你的 FPS 从 144 掉到 30。正确做法是:谁改了值,就广播一个通知,需要这个值的地方监听通知再去取——平时不管它。

AI 可能的回答(参考样本)

1. 插件文件拆分方案

基于 Bible 的 07_file_layout.md 中定义的模块化目录结构，我建议拆成以下文件：

文件	一句话职责
scripts/editor/balance_editor_plugin.gd	EditorPlugin 入口，注册菜单项、创建停靠面板实例
scripts/editor/balance_config_dock.gd	底部停靠面板的控制脚本，负责构建10个字段的UI、加载/保存JSON
scenes/editor/BalanceConfigDock.tscn	停靠面板的场景文件，包含ScrollContainer + GridContainer布局骨架
scripts/editor/balance_slider_spinbox.gd	可复用的"HSlider + SpinBox"双联控件（自定义Control子类），封装双向同步逻辑
scenes/editor/BalanceSliderSpinbox.tscn	双联控件的场景文件，包含HSlider + Label + SpinBox三个子节点
data/balance_config.json	被编辑器读写的JSON数值配置文件

这样拆的理由：遵循 Bible 中 scripts/ 和 scenes/ 分离的模式，且把双联控件独立为一个复用组件，面板只需 for 循环实例化10个即可。

2. 双向同步的信号处理

用到的信号：

HSlider.value_changed(value: float) — 滑条值改变
SpinBox.value_changed(value: float) — 输入框值改变

循环触发问题：一定会出现循环触发。拖动 HSlider → 更新 SpinBox → SpinBox 发射 value_changed → 回调又去更新 HSlider → 无限循环。

解决方案：用一个 bool 守卫变量 _updating：

任何一方被改变时，先设 _updating = true，更新另一方，再设 _updating = false。
两个 value_changed 回调的第一行都是 if _updating: return。
代码量极小（约 10 行），无需断开/重连信号，比 set_block_signals 方案更安全（不会影响该节点上其他信号连接）。

3. GameManager 读 JSON 的改动

改动函数：start_round()（在 scripts/autoload/game_manager.gd 第135行）。

改动范围：极小——两种实现方式：

方案A（推荐，改动最小）：在 _ready() 里加一次 _load_balance_config()，把 JSON 解析后的值存入与现有常量同名的变量。start_round() 内部把 START_BALL_COUNT → balance_config.start_ball_count，其余逻辑一行不动。

方案B：动态改常量 → 不推荐，Godot 的 const 编译期固定。

实际改动量预估：新增一个 _load_balance_config() 函数（约15行）+ 修改 start_round() 和 _reset_state() 中的约5处硬编码引用为配置变量引用。其他函数（add_balls、remove_ball、_finalize_round）中使用了 BUCKET_BONUS、NORMAL_PENALTY 等常量也需要改为从配置读取，约再多改3处。总共改 20~30 行，不涉及架构变化。

4. 需要确认的问题 (C1)~(C7)

(C1) 08_dev_tools.md 文件不存在。Bible的 _index.md 中也没有索引到它。这个文件是否还未创建？还是路径/编号变了？

(C2) 03_rules.md 中没有你提到的"可改数值字段清单 DEC-017"表格。当前文件只有球数规则、倒计时规则、图钉规则三张表。DEC-017 表格是否在别的文件中（比如你计划后续加入），还是需要我根据现有规则反推这10个字段？

(C3) 基于现有规则文档，我推测"10个可改数值字段"可能包含：初始球数(50)、晋级阈值(60)、倒计时秒数(90)、袋洞奖励(+3)、普通区扣除(-1)、小球半径、发射力度、图钉间距、重力系数等——但这里混入了物理参数。请确认 DEC-017 清单只覆盖游戏规则数值，还是也包含物理/UI参数？

(C4) GameManager 存在两份文件：autoload/GameManager.gd（老版本，用 round_won/round_failed 信号）和 scripts/autoload/game_manager.gd（新版本，用 round_finished(success) 统一信号）。根据 07_file_layout.md，注册的 Autoload 路径应该是 scripts/autoload/game_manager.gd。是否确认以 scripts/ 路径下的版本为准？

(C5) 07_file_layout.md 第37行把自己列在了 Bible 目录里（07_file_layout.md），但实际它位于 docs/bible/07_file_layout.md。这个自引用是否只是文档模板残留，不需要修正？

(C6) 编辑器插件中"保存为JSON"的路径你指定是 res://data/balance_config.json，但当前项目中没有 data/ 目录。需要我创建，还是你有其他偏好的路径（如 res://configs/）？

(C7) 数值编辑器的滑块范围——每个字段的 min/max/step 如何确定？比如"初始球数"滑块是 10~200 步长5，还是 1~500 步长1？没有 DEC-017 表格定义这些约束的话，我先用合理默认值还是等你提供？

示例回答

(C1) 08_dev_tools.md 还没创建，这节课做完后统一新建，现在先跳过，AI按没有这个文件的状态继续。

(C2) DEC-017表格在这节课正文里已经定义了，你现在手动把它补进 03_rules.md 再继续。10个字段就是正文表格里那些，只覆盖游戏规则数值，不包含物理参数（ball_restitution / ball_friction / gravity_scale / max_velocity 这四个也要加进去，一共10个）。

(C3) DEC-017清单包含全部10个字段，游戏规则数值和物理参数都在里面，就是Prompt 2.B配置字典里那10个，以那个为准。

(C4) 以 scripts/autoload/game_manager.gd 为准，这是新版本，老版本忽略。

(C5) 自引用是文档模板残留，不需要修正，忽略它。

(C6) 新建 data/ 目录，路径用 res://data/balance_config.json。

(C7) min/max/step直接用Prompt 2.B配置字典里已经写好的那份，不需要AI自己推断。

3.3 第 2 轮对话：回答 + 让 AI 写代码

Prompt 2.B · 数值面板实现

好的，我收到了你的问题，回答如下：
（把AI在2.A里列出的C问题逐条回答后粘在这里）

现在请你实现数值编辑器插件，输出以下文件的完整代码：

1. addons/balance_editor/plugin.gd
   - 继承EditorPlugin
   - _enter_tree()里：在编辑器顶部菜单「项目」下新增「数值编辑器」菜单项，点击后显示/隐藏底部停靠面板
   - _exit_tree()里：清理菜单项和停靠面板

2. addons/balance_editor/balance_panel.gd
   - 继承Control
   - _ready()里：用代码动态生成10行控件（每行一个HSlider+SpinBox），字段名和范围从下面的配置字典读取，不要硬编码10行重复代码
   - 字段配置字典（直接写在脚本顶部常量里）：
     - start_balls: {label:"起始球数", min:10, max:200, step:1, default:50}
     - round_seconds: {label:"倒计时(秒)", min:30, max:300, step:1, default:90}
     - pass_threshold: {label:"晋级阈值", min:1, max:500, step:1, default:60}
     - reward_pocket_gain: {label:"袋洞加球", min:1, max:20, step:1, default:3}
     - normal_zone_loss: {label:"普通区扣球", min:0, max:5, step:1, default:1}
     - ball_restitution: {label:"弹性系数", min:0.0, max:1.5, step:0.01, default:0.85}
     - ball_friction: {label:"摩擦系数", min:0.0, max:1.0, step:0.01, default:0.05}
     - gravity_scale: {label:"重力缩放", min:0.1, max:5.0, step:0.1, default:1.0}
     - max_velocity: {label:"最大速度", min:200, max:5000, step:50, default:1500}
     - item_choices_per_round: {label:"三选一数量", min:1, max:5, step:1, default:3}
   - HSlider和SpinBox双向同步，不能循环触发
   - 底部三个按钮：「保存为JSON」「载入JSON」「恢复默认」
   - 点「保存为JSON」写入 res://data/balance_config.json，保存成功后在编辑器底部状态栏显示「✅ 已保存到 balance_config.json」
   - 点「载入JSON」从同路径读取并更新所有控件的显示值
   - 点「恢复默认」把所有控件重置为default值

3. 修改GameManager.gd中的数值读取部分
   - 只输出需要新增/修改的函数，不要重写整个文件
   - 新增一个 load_balance_config() 函数，在_ready()最开始调用
   - 读取 res://data/balance_config.json，如果文件不存在就用代码里的默认值
   - 读取成功后把值赋给对应的变量（变量名和字段名一致）

约束：
- 只用Godot 4原生节点，不依赖第三方插件
- 代码注释用中文
- 每个函数不超过30行，超过就拆函数
- JSON路径定义为顶部常量 CONFIG_PATH，不要在函数里硬编码字符串
- 在文件最底部写一段注释，诚实列出：你自测了哪些功能、哪些没有自测、原因是什么

⚠️ 新手最常踩的坑：让 AI 重写 GameManager 来"接入"配置。你会得到一份 GameManager 几乎从头写过、改了 200 行的 diff，原本好好的代码逻辑断了——而 BallManager 它还顺手"重构"了。要硬性规定 AI"改动越小越好"——它越是想"重构"，越要拒绝。

验收数值编辑器插件（四步走）

代码跑完不等于链路通了。数值编辑器涉及三个环节——编辑器UI → JSON文件 → GameManager读取——任何一环断掉，调参就是在自欺欺人。按下面四步逐一验收，每步都有可以截图存档的判断标准。

第一步：确认插件已启用

打开 Godot 编辑器，点击顶部菜单「项目」→「项目设置」→「插件」标签页，找到「Balance Editor」，确认状态列显示绿色勾「启用」。如果这里没有出现插件，说明 addons/balance_editor/plugin.cfg 文件格式有问题，或者插件目录路径不对——把错误信息丢给 AI 让它修。

图9 · Godot编辑器「项目设置→插件」页面截图，Balance Editor状态为启用

第二步：确认面板可见 + 滑条双向同步

插件启用后，点击顶部菜单「项目」→「数值编辑器」，编辑器底部应该出现停靠面板，能看到10行滑条+输入框。做一个验证动作：拖动「袋洞加球」滑条从3拖到5，观察右侧输入框数字是否同步变成5。然后反向：在输入框里手动输入1，观察滑条是否同步移动到最左侧。两个方向都对才算通过。

图10 · 编辑器底部停靠面板截图，展示10行滑条+输入框，以及「保存为JSON」「载入JSON」「恢复默认」三个按钮

第三步：确认JSON写入成功

把「起始球数」改成70、「袋洞加球」改成5，点击「保存为JSON」。验收两件事：

① 编辑器底部状态栏出现「✅ 已保存到 balance_config.json」提示。
② 在Godot的FileSystem面板里找到 res://data/balance_config.json，双击打开，确认文件里同时出现 start_balls 字段值是 70、reward_pocket_gain 字段值是 5。如果状态栏没有提示或JSON文件不存在，说明写入路径有问题。

第四步：确认GameManager真的读到了新值（这步最容易断）

前三步只是"文件写对了"，这步才是"游戏真的用了新值"。操作步骤：确认JSON里 start_balls = 70、reward_pocket_gain = 5 → 按F5运行游戏 → 观察开局球数是否从默认的50变成了70 → 发射弹珠让它落入救赎袋 → 观察球数变成75（70+5）而不是73（70+3）。

两个值同时验证，一个都不对就说明链路断了——把现象描述给AI让它排查。

🎯 四步全部通过 = 链路完整。把第四步录成5秒GIF，是本节课最有说服力的验收证据。

四、最后一步：让 AI 回写 Bible

代码跑通了，按第 06 课的老规矩——让 AI 回写 Bible，但你手动 apply。这一节课要回写两条决策：

Prompt 3 · 回写 Bible

你刚刚完成了"道具系统脚手架"和"数值面板"两个模块。请按下面的流程同步 Bible:

1. 列出本次改动实际触及的 Bible 模块(对比一下最初的规划,看有没有偏差)。

2. 对每个被触及的模块文件:
   - 找出"事实层面"发生变化的条目(新增 / 修改 / 删除)。
   - 不要重写整个文件,只动需要动的段落。

3. 新增 2 条决策记录:
   - DEC-016 · 道具分类与 effect_id 注册规约:写明 6 大类、命名规范、新 effect_id 必须由 L 拍板。
   - DEC-017 · 数值热改与持久化协议:写明 user://values.json 是真值、Bible 范围是闸、改值必须写 author_note。

4. 新建 bible/08_dev_tools.md 章节,内容包括:
   - ItemTestConsole 的 5 步冒烟测试列表
   - 数值面板的快捷键(F12 切换、Reset 按钮、导出按钮)
   - 调试场景的统一规约:所有 scenes/debug/* 必须只在调试模式下才能进入

5. 不要直接修改代码本身,只更新 Bible。所有变化以 diff 格式输出,我会逐条 review 后手动 apply。

五、把这一节课的"工作流"留下来

这一节课你做了两件事——三选一道具系统 + 数值面板。但你真正学到的，是一个可以复用的设计工作流：

接下来的项目中，你可以一遍又一遍地用它：

模块	第 1 轮：脚手架	第 2 轮：数据	第 3 轮：代码 + 测试面板
道具系统	6 大类 + 道具长什么样	items.json 30 条	effect 脚本 + ItemTestConsole
敌人系统	敌人状态怎么切换	enemies.json	EnemyTestConsole
关卡布局	房间类型 / 钉子布局规则	rooms.json	RoomPreviewConsole
商人 / 事件	事件触发模型	events.json	EventReplayConsole

每一节课的测试面板，都用本节学到的数值面板来调它的数值字段——你会发现这个数值面板不是"只为道具做的"，它是项目的全局调参面板。

六、用体验指标验证设计是否成立

AI 给出的策划/数值方案，本质上是"假设"。改完之后凭感觉判断好不好玩，是最常见的翻车原因。正确的做法：在改之前先定指标 → 改之后用同一批指标对比。下面是 Roguelike / Build 类玩法里最常用的四个体验指标，每一个都给出明确的判定口径。

1. 回本率

定义：单局内通过商店、事件、奖励获得的总收益 ÷ 玩家总投入（金币、血量、回合数折算）。

怎么测：跑 200+ 局自动战或玩家局，按难度 / 关卡分桶统计中位数与方差。

怎么判：健康区间：0.8 – 1.2（略亏一点，才能逼玩家做选择）。重点看中位数和方差，不要只看均值——均值会被极端局拉偏。

2. 选择分布

定义：在三选一 / 分支节点上，每个选项被选择的频次占比。

怎么测：埋点记录每个节点的 (节点ID, 选项ID, 玩家段位)。

怎么判：健康：最高 / 最低占比差距 ≤ 2 倍（如 25% / 35% / 40%）。一定要按"高水平 / 低水平"玩家分桶看，避免新手数据淹没真实策略偏好。

3. 单局剩余球数（剩余资源通用指标）

定义：玩家通关或失败时，账面上未消耗的球 / 牌 / 能量数量。

怎么测：记录每局结束时的资源余量，按"胜利 / 失败"分桶。

怎么判：胜利局剩 1 – 3：最佳，说明压力恰到好处。失败局：重点看"差几颗能赢"，差 1–2 颗最理想。

4. 某个 Build 方向的成型概率

定义：单局结束时，该 Build 的核心件数 ≥ 成型阈值（例如 3 件核心 + 2 件辅助）的局数占比。

怎么测：给每个 Build 打 tag，跑 500+ 局随机 / AI 局，统计成型率以及成型后的胜率。

怎么判：成型率 15% – 30%：健康，有追求空间但不会必出。