godot-brainstorming

Godot 头脑风暴

为 Godot 4.3+ 功能和系统设计提供结构化流程——在编写任何实现代码之前，从空白状态开始，梳理出清晰的场景树、信号图和数据流。

相关技能： godot-grill 用于先敲定尚未确定的设计决策，scene-organization 用于场景树组合模式，component-system 用于基于组件的架构，event-bus 用于基于信号的通信设计。

---

流程：如何进行头脑风暴

不要直接开始设计。请按以下步骤操作：

第 1 步：敲定决策

如果请求中有尚未确定的设计决策（范围、维度、权威来源、数据归属位置，……），请调用 godot-prompter:godot-grill 并让它运行至结束。如果项目的决策记录或 ADR 目录中已有涵盖此功能的记录，或者用户已经说明了这些决策，则跳过此步骤。无论哪种情况，都要检查已有内容（代码、场景、资源）。将记录带入第 2 步——方案必须遵循已敲定的条目。

第 2 步：提出 2-3 种方案

决策敲定后，提出几种架构方案并说明各自的权衡。例如：

• “状态机采用 Enum FSM 还是 Node FSM——分别适用于哪些情况”
• “系统采用 EventBus 还是直接信号——权衡如下” 先给出你的建议，并说明理由。

第 3 步：经批准后进行设计

按部分呈现设计（场景树、信号图、数据流）。每呈现一部分后，都先问“这样看起来合适吗？”，再继续。

第 4 步：为实现做好准备

设计获批后：

1. 询问是否添加 Agent 指令部分——询问是否要将 GodotPrompter 集成部分添加到本项目用于 Agent 指令的文件中（请参阅下方的“注入 Agent 指令”）。该部分会告知子 Agent 和后续会话使用 GodotPrompter 技能。如果其中任何一个文件已经有 ## GodotPrompter 部分，或者用户之前拒绝过，则不提示并跳过。未经同意，绝不添加。

2. 创建实现计划——如果有可用的规划技能（例如 superpowers:writing-plans），就使用它；如果没有，则自行将设计拆分为有序任务。无论哪种情况，都由项目决定计划的保存位置：优先采用用户指令或项目的 Agent 指令文件中的说明；其次遵循规划技能的惯例；然后使用现有计划目录。如果都不适用，则询问用户，并建议使用 docs/plans/；无法询问时，则使用 docs/plans/。

3. 为每项任务标注技能——计划中每项涉及 Godot 系统的任务都必须列出实现期间要调用的 godot-prompter:* 技能。示例：

   • 任务 3：玩家移动——创建具备行走、冲刺和跳跃能力的 CharacterBody3D。 技能：godot-prompter:player-controller、godot-prompter:input-handling

   这样，即使由其他插件执行计划，实现任务的 Agent 也知道应加载哪些 GodotPrompter 技能。

---

1. 适用场景

在以下情况下，请从这里开始：

• 添加新功能——宝箱、对话系统、制作台、技能树
• 创建新场景——需要决定场景包含哪些节点，以及节点之间如何通信
• 在多种方案间选择——继承还是组合、Autoload 还是 Resource、2D 还是 3D
• 结构上遇到瓶颈——代码可以运行，但场景树感觉不对
• 帮助他人熟悉项目——需要解释现有系统的设计

如果你已经清楚需要哪些节点以及它们如何连接，就跳过此技能，直接开始构建。只有在不确定性拖慢进度时才使用它。

---

2. 场景树规划

在打开 Godot 编辑器之前，先在纸上（或注释块中）勾勒场景树。目标是回答每个节点的三个问题：

1. 这个节点拥有些什么？（数据、子节点、视觉表现）
2. 这个节点做什么？（它的单一职责）
3. 它如何与相邻节点通信？（向上发送信号、向下调用方法、通过 EventBus 横向通信）

规划步骤

1. 命名根节点并指定其类型——这定义了场景与世界之间的契约。
2. 按职责组列出直接子节点，而不是按 Godot 节点类型分类。
3. 为每个条目指定 Godot 节点类型。
4. 确定场景发出的每个信号以及接收的每个信号。
5. 标记哪些节点应拆分为独立的 .tscn 文件（可复用候选项）。

示例：规划一个“Chest”可交互对象

步骤 1 — 名称和根节点类型

Chest 是一个世界物体，玩家可以走近并打开它。它不是物理体，也不会移动。根节点：StaticBody2D 或 Node2D。

步骤 2 — 职责分组

• 视觉呈现（精灵、动画）
• 碰撞／交互触发器（检测玩家是否靠近）
• 战利品数据（内部包含哪些物品）
• UI 反馈（提示标签、打开动画触发器）
• 状态（打开还是关闭？）

步骤 3 — 指定节点类型

Chest (StaticBody2D)
├── Sprite2D                  # closed/open frame, or swap texture on open
├── AnimationPlayer           # open animation
├── CollisionShape2D          # physical body shape (blocks player)
├── InteractionArea (Area2D)  # detect when player is close enough
│   └── CollisionShape2D      # slightly larger than body shape
├── PromptLabel (Label3D or Label) # "Press F to open"
└── LootTable (Node)          # holds @export var items: Array[ItemData]

步骤 4 — 信号映射

信号	发出者	连接到	用途
body_entered(body)	InteractionArea	Chest._on_area_body_entered	玩家进入范围时显示提示
body_exited(body)	InteractionArea	Chest._on_area_body_exited	玩家离开范围时隐藏提示
opened(loot: Array[ItemData])	Chest	InventorySystem 或 EventBus	将战利品交给拥有物品栏的对象
animation_finished(name)	AnimationPlayer	Chest._on_animation_finished	打开动画完成后锁定箱子

步骤 5 — 可复用候选项

LootTable 很可能会被木桶、敌人和商店箱子复用——将其提取为独立的 .tscn 组件。

如需查看最终的 GDScript 和 C# Chest 示例，以及用于记录此设计的四部分设计条目（场景树、节点职责、信号映射、数据流），请参阅 references/example-chest.md。

---

3. 选择节点类型和维度

这里有两项查询内容，但都只需凭记忆即可回答——仅在答案不明显时再查阅：

• 不同需求该选哪个节点？ CharacterBody、RigidBody、StaticBody 和 Area 的区别；UI 与世界空间标签；粒子、摄像机、生成标记。
• 选择 2D、3D 还是 2.5D？ 各自的选择标准、混合技术（朝向摄像机的精灵、正交 3D、SubViewport UI），以及对性能的影响。

Godot 4.3+ 中有两点容易出错，值得提前说明：基于图块的关卡使用 TileMapLayer（每个节点一层——TileMap 已弃用）；混合树式移动需要将 AnimationTree 与 AnimationPlayer 配合使用，不能只用 AnimationPlayer。

完整的需求到节点类型对照表、2D／3D 选择标准以及 2.5D 混合技术：请参阅 references/node-selection.md

---

4. 构建前要问的问题

创建第一个节点前，请先逐项检查此清单。

• 此系统需要哪些数据？ — 列出每项状态：位置、生命值、物品数量、标记
• 每项数据由谁拥有？ — 为每个值指定一个权威所有者；避免重复状态
• 它如何通信？ — 沿树向上传递信号，向下调用方法，跨系统事件使用 EventBus
• 它能否复用？ — 如果可以，应将其设为独立的 .tscn 场景，并提供简洁的 @export 接口
• 它是否需要持久化？ — 如果数据必须在场景切换或游戏重启后保留，请尽早规划存档系统
• 场景树是什么样的？ — 在操作编辑器前，至少绘制两层结构
• 它会发出哪些信号？ — 列出每个信号的名称、参数，以及连接对象
• 有哪些故障情况？ — 必需节点缺失时会怎样？信号触发两次时会怎样？
• 最小可行版本是什么？ — 先构建它；只有在确有需要时才增加复杂度

---

5. 常见架构决策

如果你需要……	可以考虑……	原因
在任何位置都可访问的全局状态	Autoload（单例）	在项目设置中注册；可作为命名全局变量使用
多个场景之间共享数据	Resource（.tres / .res）	保存为资源；可使用 @export；重新加载场景后仍然存在
在不同实体类型之间复用行为	组件场景	将其作为子节点实例化；每个实体通过包含该场景来选择是否启用
有许多状态的复杂实体行为	状态机	每个状态都有明确的进入和退出流程；避免 if 链不断膨胀
不共享同一父节点的系统之间传递事件	EventBus Autoload	解耦发送方和接收方；任何节点都可以连接
必须在不同会话之间保留的数据	使用 JSON 或二进制格式的保存系统	序列化 Resource 或 Dictionary；在 _ready 时加载
可配置的游戏数据（属性、物品、关卡）	带有 @export 字段的 Resource	在检查器中编辑值；无需修改代码
在运行时生成场景	PackedScene + instantiate()	存储 @export var scene: PackedScene；调用 scene.instantiate()
延迟或定时运行代码	Timer 节点	比使用 _process 帧计数器更简洁；支持单次触发和循环
渐变过渡（淡入淡出、插值、补间）	Tween	内置 create_tween()；在 Godot 4 中无需额外节点

---

6. 设计输出格式

将设计记录在根脚本顶部的注释块中，或场景旁的 DESIGN.md 文件中。完整的设计条目包含四个部分：场景树 ASCII 图、节点职责表、信号映射（信号 → 源 → 接收方 → 负载）以及展示触发事件如何沿树传播的数据流跟踪。

参见 references/example-chest.md，了解以可交互的 Chest 为核心、完整编写的四部分条目示例。

---

设计检查清单

• 打开编辑器之前，至少绘制出两层深度的场景树
• 每个节点都只有一个明确命名的职责
• 列出所有信号的名称、源、接收方和负载类型
• 明确数据的所有权——同一个值不得存储在两个地方
• 将可复用部分提取到单独的 .tscn 文件中
• 选择通信模式：信号向上、调用向下、EventBus 横向传递
• 构建数据结构之前，明确持久化要求
• 查阅架构决策表，确定全局状态、共享数据和事件的处理方式

---

Agent 指令注入

准备实现时（第 4 步），将以下部分添加到项目用于存放 Agent 指令的文件中。检查 CLAUDE.md、CLAUDE.local.md、.claude/CLAUDE.md、AGENTS.md、GEMINI.md、.github/copilot-instructions.md 以及 .claude/rules/ 和 .cursor/rules/ 目录中的所有文件，确认是否已有 ## GodotPrompter 标题——只要任何位置已存在，就跳过。

之前拒绝过一次就视为已作答。SessionStart 钩子会在本项目的 ~/.godot-prompter/state/<hash>.json 中记录拒绝，值为 "section_offer": "declined"（godot-prompter:godot-mentor 说明了该文件及哈希的计算方式）——如果该键已设置，就不要再次询问。若用户在此处拒绝，请自行将拒绝记录写入该文件，并与其中已有的键合并。

将其写入项目已有的文件，而不是另建一个文件：

• 如果存在 CLAUDE.md → 添加到该文件。
• 如果只存在 AGENTS.md 或 GEMINI.md → 添加到该文件，以保持仓库与 Agent 无关。Claude Code 只会读取 CLAUDE.md，因此如果用户也希望在那里加载这些指令，可以提供一个仅含 @AGENTS.md 的单行 CLAUDE.md——应先征求用户同意，不要擅自添加。
• 如果以上文件都不存在 → 创建 CLAUDE.md，包含项目概览标题和此部分。

GodotPrompter

这是一个 Godot 项目，提供了 GodotPrompter 技能。实现任何游戏系统之前，必须先检查是否有匹配的 godot-prompter:* 技能，并调用该技能。此要求适用于在此仓库中工作的所有 Agent、子 Agent 和会话。

主要技能：player-controller、state-machine、event-bus、scene-organization、component-system、resource-pattern、godot-ui、hud-system、ai-navigation、camera-system、audio-system、save-load、inventory-system、godot-testing。

如需查看完整技能列表，请调用 godot-prompter:using-godot-prompter。