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”.

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.

Declaration and activation

{
  "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:

# 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

run_game
set_time_scale(0)
inject_input("jump", true)
step_frame() × 10
read_node_property("/root/Game/Player", "position.y")
   → assert > initial_y (the player did leave the ground)
step_frame() × 30
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

Inspect the project scene tree
Create / modify nodes and scripts
Run the game for testing
Verify with deterministic playtest
Capture screenshots at key moments
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

Godot Bridge should appear in the plugin panel of a new Profy Desktop conversation. If it does not, Desktop is not connected.
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.
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.

3D and visualization

Cloud-side game-studio: Three.js / R3F / Phaser web games

Blender Bridge

Sibling bridge: local Blender modelling and GLB export

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).

Get Started

Core Concepts

Guides

Platform & Account

Deep Dive

Godot Bridge

Godot Bridge

Declaration and activation

Prerequisites

Deterministic playtesting

Example: testing a jump

Development workflow

Capability inventory (available once MCP is wired)

Safety rules

Code style constraints

Boundaries and failure modes

Troubleshooting

Verify your setup

3D and visualization

Blender Bridge

​Godot Bridge

​Declaration and activation

​Prerequisites

​Deterministic playtesting

​Example: testing a jump

​Development workflow

​Capability inventory (available once MCP is wired)

​Safety rules

​Code style constraints

​Boundaries and failure modes

​Troubleshooting

​Verify your setup

​Related

3D and visualization

Blender Bridge

Godot Bridge

Declaration and activation

Prerequisites

Deterministic playtesting

Example: testing a jump

Development workflow

Capability inventory (available once MCP is wired)

Safety rules

Code style constraints

Boundaries and failure modes

Troubleshooting

Verify your setup

Related