> ## 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 — connect Profy to your local Godot Engine over MCP: scene editing, GDScript, and deterministic playtesting with frozen time

# Godot Bridge

Connect Profy to the Godot Engine instance on your machine so an expert can edit the scene tree, write GDScript, run the game, and perform **deterministic playtesting**.

That last capability is what separates this from every other 3D or game bridge. Most AI-assisted game development can only take screenshots and squint at them. Godot lets you freeze time, step individual frames, inject inputs, and read any node property — which turns testing into **assertions instead of "looks about right"**.

<Warning>
  **Current implementation status (verified 2026-08-11)**: this plugin's `mcpServers` declaration (`uvx godot-mcp`) has **no consumer anywhere in the codebase**. `PluginManifest.mcp_servers` in agent-runtime is parsed but never read, and Core only assembles MCP for community plugin installations (`buildCommunityMcpToolsAndConfig`), which does not cover built-in manifests.

  Selecting it gives you the **skill and prompt layer** — the deterministic-playtest methodology below genuinely shapes model behaviour — but **no callable Godot tools**.
</Warning>

## Declaration and activation

```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 }
}
```

Both gates must pass: explicit selection (`user_selectable`) and a connected Desktop (`desktop_connected`, derived from `PROFY_DESKTOP == "true"`). The plugin does not exist in cloud browser conversations.

## Prerequisites

| Requirement             | Notes                                                |
| ----------------------- | ---------------------------------------------------- |
| Godot 4.3 or newer      | Earlier versions lack the required MCP addon support |
| Godot MCP addon enabled | Exposes the MCP endpoint inside the editor           |
| Python `uv` installed   | `uvx` launches `godot-mcp`                           |
| Profy Desktop           | Not available in the cloud                           |

## Deterministic playtesting

This is the plugin's central value and deserves to be understood on its own terms.

Ordinary AI game testing is "run it, screenshot it, does it look right". The problem is that games are real-time: run the same code twice and the physics step, frame pacing, and input timing all differ, so the frames differ too. **When a screenshot does not match, you cannot tell whether the code is wrong or the frame simply had not caught up yet.**

Godot lets you stop time:

```gdscript theme={null}
# Freeze time
Engine.time_scale = 0.0
```

From that point every frame is advanced explicitly by the test. The full loop:

| Step | Operation                                   | Purpose                                            |
| ---- | ------------------------------------------- | -------------------------------------------------- |
| 1    | `run_game`                                  | Start the game                                     |
| 2    | `set_time_scale(0)`                         | Freeze time; nothing advances on its own from here |
| 3    | `step_frame()` × N                          | Advance exactly N physics frames                   |
| 4    | `inject_input(action, pressed)`             | Simulate player input                              |
| 5    | `step_frame()` × N                          | Let physics resolve                                |
| 6    | `read_node_property(path, prop)`            | Read state and assert                              |
| 7    | `screenshot`                                | Visual confirmation                                |
| 8    | Pass → next case; fail → fix code → restart |                                                    |

### Example: testing a jump

```
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")
   → assert > initial_y (the player did leave the ground)
6. step_frame() × 30
7. read_node_property → assert landed (y ≈ ground height)
```

Note that the assertions are over **numbers, not pixels**. "It jumps" becomes the decidable proposition `position.y > initial_y`. When it fails you know whether the jump height was insufficient or the input never fired, instead of guessing from an image.

The design consequence worth internalising: any behaviour you want an agent to verify autonomously must be **readable as state**. If the only evidence is visual, the agent is back to squinting.

## Development workflow

```
1. Inspect the project scene tree
2. Create / modify nodes and scripts
3. Run the game for testing
4. Verify with deterministic playtest
5. Capture screenshots at key moments
6. Iterate on issues found
```

Pre-flight is three steps: confirm the MCP connection (call `get_project_info`), confirm Godot is 4.3+, and review the project structure — scenes, scripts, assets.

## Capability inventory (available once MCP is wired)

| Category               | Contents                                       |
| ---------------------- | ---------------------------------------------- |
| Scene editing          | Add / remove / modify nodes                    |
| GDScript               | Create, edit, hot-reload                       |
| Assets                 | Import textures, audio, 3D models              |
| Signals                | Connect node signals                           |
| Run control            | play / stop / pause                            |
| Deterministic playtest | Frozen time + input injection + property reads |
| Debugging              | DAP breakpoints, stepping, variable inspection |
| Screenshots            | Capture during gameplay                        |
| Export                 | Web (HTML5), desktop, mobile                   |

## Safety rules

* Never modify `.godot/` project settings without asking
* Only use undo-safe operations
* Save before running tests
* Do not delete nodes that have many dependents

The last one is Godot-specific. Deleting a node referenced from several places produces errors in completely unrelated parts of the project, which makes the failure expensive to trace back to its cause.

## Code style constraints

The prompt layer requires GDScript to stay clean: **static typing** plus `@export` annotations. This is not an aesthetic preference. Static types make Godot report errors at edit time, and `@export` makes parameters tunable in the editor. Both directly reduce the "only discovered at runtime" round trips that dominate the cost of agent-driven game development.

## Boundaries and failure modes

* **No Desktop, no plugin.** It does not appear in cloud conversations.
* **While `Engine.time_scale = 0`, the game does not advance on its own.** If a test script forgets `step_frame()`, the symptom is "it hangs" rather than an error. That is the intended semantics, not a deadlock.
* **The MCP declaration is currently unwired** (see the top of the page), so the model will offer methodology rather than execute.
* **Deterministic playtesting only covers logic you can read as a property.** Rendering correctness, shader behaviour, and audio produce no readable numbers and still depend on screenshots and human judgement.
* **Hot reload has limits.** GDScript hot-reloads, but changing exported variable structure or scene structure generally requires restarting the game.

### Troubleshooting

| Symptom                                             | Cause                                                                   | Fix                                                                           |
| --------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Godot Bridge missing from the plugin panel          | Not in Desktop, or Desktop not connected                                | Open Profy Desktop and confirm the connection                                 |
| Selected, but the model says it has no Godot tools  | `mcpServers` is unwired (see top of page)                               | Expected today; the skill layer still applies                                 |
| Version check fails                                 | Godot older than 4.3                                                    | Upgrade; the required addon capability is missing below 4.3                   |
| `uvx` not found                                     | Python `uv` is not installed                                            | Install `uv` and verify `uvx godot-mcp` manually                              |
| Deterministic tests give different results each run | `set_time_scale(0)` was skipped, so the game is still real-time         | Freeze time before stepping frames                                            |
| Assertion passes but the game visibly misbehaves    | The asserted property is not the one that governs the visible behaviour | Add a screenshot at the same frame and compare against the property you chose |

## Verify your setup

1. Godot Bridge should appear in the plugin panel of a new Profy Desktop conversation. If it does not, Desktop is not connected.
2. Tick it and ask "what does the current Godot project's scene tree look like?". Methodology advice instead of a real node tree means you have hit the unwired state described above.
3. Ask it to "design a test that verifies the character's jump height". A correct answer must contain all three of `set_time_scale(0)`, `step_frame`, and a `read_node_property` assertion — which confirms the skill layer loaded.

## Related

<CardGroup cols={2}>
  <Card title="3D and visualization" href="/en/documentation/plugins/3d-development">
    Cloud-side game-studio: Three.js / R3F / Phaser web games
  </Card>

  <Card title="Blender Bridge" href="/en/documentation/plugins/blender-bridge">
    Sibling bridge: local Blender modelling and GLB export
  </Card>
</CardGroup>

<Note>
  Verified 2026-08-11. Sources: `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>