Godot Runtime Bridge

Runtime automation and AI-driven testing for Godot 4.x

A lightweight TCP debug server that lets AI assistants (Cursor, Claude Code) and automation scripts launch, control, observe, and test your running Godot game — no editor required.

Quick Start

1. Install the Addon

Copy addons/godot-runtime-bridge/ into your project's addons/ folder. Enable the plugin in Project → Project Settings → Plugins.

2. Run Your Game with the Bridge Enabled

# Auto-generated token, random port, tier 1 (observe + input)
GODOT_DEBUG_SERVER=1 godot --path /your/project

# Or with explicit token and tier
GDRB_TOKEN=my_secret_token GDRB_PORT=9999 GDRB_TIER=2 godot --path /your/project

On startup, the server prints:

GDRB_READY:{"proto":"grb/1","port":54321,"token":"xK9m...","tier_default":1}

3. Send Commands

Connect via TCP to 127.0.0.1:<port> and send newline-delimited JSON:

{"id":"1","cmd":"ping"}
{"id":"2","cmd":"screenshot","token":"xK9m..."}
{"id":"3","cmd":"click","args":{"x":100,"y":200},"token":"xK9m..."}
{"id":"4","cmd":"scene_tree","args":{"max_depth":3},"token":"xK9m..."}

4. Use with an MCP Client (Cursor, Claude Code)

A companion MCP package (godot-runtime-bridge-mcp) is available separately for integration with AI clients like Cursor and Claude Code. It handles launching Godot, parsing the READY line, and exposing all commands as MCP tools. See the project repository for details.

Security

The bridge is designed with security-first defaults:

• Off by default — does nothing without activation env vars
• Localhost only — binds to 127.0.0.1, never exposed to network
• Random port — OS-assigned by default, prevents predictable port attacks
• Token auth — every command requires a valid token
• Capability tiers — commands grouped by risk (observe/input/control/danger)
• eval disabled by default — requires two explicit opt-ins

See SECURITY.md for the full threat model and recommendations.

Commands

See PROTOCOL.md for the complete command reference.

Environment Variables

Background Testing

By default (GDRB_INPUT_MODE=synthetic), all input commands inject Godot InputEvent objects without touching the OS cursor. This means you can run automated tests in the background while you work — your mouse and keyboard remain yours.

If you need OS-level input (rare edge cases), set GDRB_INPUT_MODE=os.

For projects configured with fullscreen display settings, set GDRB_FORCE_WINDOWED=1 to override the project's window mode at startup. The bridge enforces windowed mode with a non-screen-sized resolution to work around a known Godot issue where screen-sized windows prevent proper fullscreen/windowed toggling.

Important: do not minimize the game window. Godot drastically throttles processing when its window is minimized to the taskbar, which will slow or break tests. Covering the game window with other applications is perfectly fine — only minimizing causes throttling. For best results, leave the game window open somewhere on screen (behind other windows is OK) while you work.

Production Builds

The server is completely inert without activation environment variables. No TCP server, no port, no overhead. Safe to ship in production builds without removing the addon.

License

MIT — see LICENSE.