> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Godot Bridge

> godot-bridge — 通过 MCP 把 Profy 接到本机 Godot：场景编辑、GDScript、冻结时间的确定性回放测试

# Godot Bridge

把 Profy 接到你本机的 Godot Engine，让专家能编辑场景树、写 GDScript、运行游戏，并做**确定性回放测试**。

最后这项是它区别于其他所有 3D/游戏桥接的地方：绝大多数 AI 游戏开发只能截图看，而 Godot 允许冻结时间、逐帧推进、注入输入、读取任意节点属性——**测试变成断言，不再是"看起来对"**。

<Warning>
  **当前实现状态（核对于 2026-08-11）**：本插件的 `mcpServers` 声明（`uvx godot-mcp`）在代码库中**没有任何消费方**——agent-runtime 的 `PluginManifest.mcp_servers` 被解析但从未读取，Core 侧只装配社区插件的 MCP（`buildCommunityMcpToolsAndConfig`），不覆盖内置 manifest。

  勾选后你会得到它的**技能与提示词**（下面的确定性回放方法论会真实影响模型行为），但**拿不到可调用的 Godot 工具**。
</Warning>

## 声明与激活

```json theme={null}
{
  "id": "godot-bridge",
  "name": "Godot Bridge",
  "version": "1.0.0",
  "mcpServers": [{ "name": "godot", "command": "uvx", "args": ["godot-mcp"] }],
  "activation": { "requires": { "desktop_connected": true }, "user_selectable": true }
}
```

两道门同时通过才激活：勾选（`user_selectable`）+ Desktop 已连接（`desktop_connected`，即 `PROFY_DESKTOP == "true"`）。云端网页对话里它不存在。

## 环境前置

| 要求                  | 说明                     |
| ------------------- | ---------------------- |
| Godot 4.3 或更高       | 低版本缺少所需的 MCP addon 支持  |
| Godot MCP addon 已启用 | 在编辑器内暴露 MCP 端点         |
| Python `uv` 已安装     | `uvx` 用于拉起 `godot-mcp` |
| Profy Desktop       | 云端不可用                  |

## 确定性回放测试

这是本插件的核心价值，值得单独理解。

普通的 AI 游戏测试是「跑起来，截图，看看像不像」。问题在于游戏是实时的：同一段代码两次运行，物理步长、帧率抖动、输入时机都不同，看到的画面也不同。**截图对不上，你不知道是代码错了还是这一帧恰好没到位。**

Godot 允许把时间冻住：

```gdscript theme={null}
# 冻结时间
Engine.time_scale = 0.0
```

之后每一帧都由测试显式推进。整个循环：

| 步骤 | 操作                               | 作用             |
| -- | -------------------------------- | -------------- |
| 1  | `run_game`                       | 启动游戏           |
| 2  | `set_time_scale(0)`              | 冻结时间，此后不会自己往前走 |
| 3  | `step_frame()` × N               | 精确推进 N 个物理帧    |
| 4  | `inject_input(action, pressed)`  | 模拟玩家输入         |
| 5  | `step_frame()` × N               | 让物理解算完成        |
| 6  | `read_node_property(path, prop)` | 读取状态并断言        |
| 7  | `screenshot`                     | 视觉确认           |
| 8  | 通过 → 下一个用例；失败 → 改代码 → 重来         |                |

### 例：测试跳跃

```
1. run_game
2. set_time_scale(0)
3. inject_input("jump", true)
4. step_frame() × 10
5. read_node_property("/root/Game/Player", "position.y")
   → 断言 > initial_y（确实跳起来了）
6. step_frame() × 30
7. read_node_property → 断言已落地（y ≈ 地面高度）
```

注意这里断言的是**数值**，不是像素。「跳起来了」变成 `position.y > initial_y` 这种可判定的命题，失败时你知道是跳跃高度不足还是根本没触发，而不是对着一张图猜。

## 开发工作流

```
1. 检查项目场景树
2. 创建/修改节点与脚本
3. 运行游戏测试
4. 用确定性回放验证
5. 关键时刻截图
6. 针对发现的问题迭代
```

前置检查三步：确认 MCP 连通（调 `get_project_info`）、确认 Godot 版本 ≥ 4.3、浏览项目结构（场景、脚本、资产）。

## 能力清单（MCP 接线补齐后可用）

| 类别       | 内容                  |
| -------- | ------------------- |
| 场景编辑     | 增/删/改节点             |
| GDScript | 创建、编辑、热重载           |
| 资产       | 导入贴图、音频、3D 模型       |
| 信号       | 连接节点信号              |
| 运行控制     | play / stop / pause |
| 确定性回放    | 冻结时间 + 注入输入 + 读取属性  |
| 调试       | DAP 断点、单步、变量查看      |
| 截图       | 游戏运行中截图             |
| 导出       | Web（HTML5）、桌面、移动端   |

## 安全规则

* 不经询问不改 `.godot/` 项目设置
* 只用 undo 安全的操作
* 跑测试前先保存
* 不删除有大量依赖者的节点

最后一条是 Godot 特有的：场景树里删一个被多处引用的节点，报错会出现在完全无关的地方。

## 代码风格约束

提示词层要求 GDScript 保持整洁：**静态类型** + `@export` 注解。这不是审美问题——静态类型让 Godot 在编辑期就报错，`@export` 让参数能在编辑器里调，两者都直接减少「跑起来才发现」的往返。

## 边界与失败态

* **没有 Desktop 就没有这个插件**，云端对话里不出现。
* **`Engine.time_scale = 0` 期间游戏不会自己前进**。如果测试脚本忘了 `step_frame()`，表现是「卡住了」而不是报错——这是预期语义，不是死循环。
* **MCP 声明当前未接线**（见页头），所以模型会给出方法论而非实际执行。
* **确定性回放只覆盖能读到属性的逻辑**。渲染正确性、shader 表现、音频这些读不出数值的部分，仍然只能靠截图与人工判断。
* **热重载有边界**。GDScript 可以热重载，但改变了导出变量结构或场景结构时通常需要重启游戏。

### 排错

| 症状                    | 原因                            | 处理                            |
| --------------------- | ----------------------------- | ----------------------------- |
| 插件面板里找不到 Godot Bridge | 不在 Desktop 中，或 Desktop 未连接    | 用 Profy Desktop 打开并确认连接       |
| 勾选了但模型说没有 Godot 工具    | `mcpServers` 未接线（见页头）         | 当前预期行为；技能层仍生效                 |
| 版本检查不通过               | Godot 低于 4.3                  | 升级；4.3 以下缺少所需 addon 能力        |
| `uvx` 找不到             | Python `uv` 未安装               | 先装 `uv` 并手动验证 `uvx godot-mcp` |
| 确定性测试每次结果不同           | 忘了 `set_time_scale(0)`，仍在实时运行 | 冻结时间后再推帧                      |

## 验证你的配置

1. 在 Profy Desktop 新对话的插件面板中应能看到 Godot Bridge。看不到 = Desktop 未连接。
2. 勾选后问「当前 Godot 项目的场景树是什么结构」。返回方法建议而非真实节点树，说明命中页头描述的未接线状态。
3. 让它「设计一个验证角色跳跃高度的测试」。正确回答必须包含 `set_time_scale(0)`、`step_frame`、`read_node_property` 断言三要素——这验证技能层已加载。

## 相关页面

<CardGroup cols={2}>
  <Card title="3D 与可视化开发" href="/zh/documentation/plugins/3d-development">
    云端 game-studio：Three.js / R3F / Phaser 网页游戏
  </Card>

  <Card title="Blender Bridge" href="/zh/documentation/plugins/blender-bridge">
    同族桥接：本机 Blender 建模与 GLB 导出
  </Card>
</CardGroup>

<Note>
  核对日期 2026-08-11。来源：`services/agent-runtime/src/plugins/builtin/godot-bridge/plugin.json`、`skills/godot-workflow/SKILL.md`、`prompts/GODOT.md`、`services/agent-runtime/src/plugins/registry.py`（`_check_activation`）。
</Note>