API Reference

Archive documentation. This page describes an earlier tool or workflow. For current work, visit the games portfolio or the development harness.

Complete reference for GRB commands, environment variables, and MCP tools.

Commands by Tier

Tier 0 — Observe

Read-only commands. No side effects on game state.

Command	Description
`ping`	Health check. Returns server status
`auth_info`	Current authentication state and session tier
`capabilities`	List of available commands for current tier
`screenshot`	Capture current frame as PNG
`scene_tree`	Dump full scene tree hierarchy
`get_property`	Read a property from any node by path
`runtime_info`	Engine version, FPS, frame count, OS info
`get_errors`	Retrieve captured engine errors and warnings
`wait_for`	Block until a condition is met (node exists, signal emitted)
`audio_state`	Audio bus layout, volumes, effects
`network_state`	Network peer status and connection info
`grb_performance`	GRB-specific performance metrics
`find_nodes`	Search scene tree by name, class, or group

Tier 1 — Input

Inject user input events. Does not modify game code or state directly.

Command	Description
`click`	Inject mouse click at coordinates
`key`	Inject keyboard key press
`press_button`	Find and press a UI button by text or path
`drag`	Inject mouse drag from point A to point B
`scroll`	Inject mouse scroll events
`gesture`	Inject touch gestures (pinch, swipe)
`gamepad`	Inject gamepad button/axis input

Tier 2 — Control

Modify live game state. Use with caution.

Command	Description
`set_property`	Write a property on any node by path
`call_method`	Call a method on any node by path
`quit`	Gracefully quit the running game
`run_custom_command`	Execute a registered custom command

Tier 3 — Danger

Arbitrary code execution. Disabled by default.

Command	Description
`eval`	Execute arbitrary GDScript. Requires `GDRB_TIER=3` and `GDRB_ENABLE_DANGER=1`

Environment Variables

Variable	Default	Description
`GDRB_TOKEN`	(none)	Auth token. Enables the server. Auto-generates if `GODOT_DEBUG_SERVER=1`
`GDRB_PORT`	`0`	TCP port. `0` = OS-assigned random port
`GDRB_TIER`	`1`	Maximum session tier (0–3)
`GDRB_INPUT_MODE`	`synthetic`	`synthetic` = inject InputEvents without OS cursor. `os` = move real cursor
`GDRB_FORCE_WINDOWED`	(none)	`1` = force windowed mode at startup
`GDRB_ENABLE_DANGER`	(none)	`1` = allow `eval` command. Also requires `GDRB_TIER=3`
`GODOT_DEBUG_SERVER`	(none)	Legacy activation. `1` = enable server with auto-generated token

MCP Tools

The MCP bridge exposes GRB commands as MCP tools that Cursor and Claude Code can call directly. Each GRB command maps to a corresponding MCP tool with the grb_ prefix.

Configuration

MCP tools are configured in .cursor/mcp.json:

{
  "mcpServers": {
    "godot-runtime-bridge": {
      "command": "node",
      "args": ["/path/to/godot-runtime-bridge/mcp/index.js"],
      "env": {
        "GODOT_PATH": "/path/to/godot"
      }
    }
  }
}

Available MCP Tools

MCP Tool	GRB Command	Description
`grb_launch`	—	Launch Godot with the current project
`grb_screenshot`	`screenshot`	Capture the current frame
`grb_scene_tree`	`scene_tree`	Dump the scene hierarchy
`grb_click`	`click`	Click at screen coordinates
`grb_key`	`key`	Press a keyboard key
`grb_get_property`	`get_property`	Read a node property
`grb_set_property`	`set_property`	Write a node property
`grb_runtime_info`	`runtime_info`	Get engine and performance info

For the complete MCP tool reference, see mcp/README.md in the GRB repository.

Custom Commands

Path: res://addons/godot-runtime-bridge/runtime_bridge/GRBCommands.gd

Add it in Project → Project Settings → Autoload, then register callables in your game code:

func _ready():
    GRBCommands.register("reset_level", _reset_level)
    GRBCommands.register("set_difficulty", _set_difficulty)

func _reset_level(_args: Dictionary) -> Dictionary:
    get_tree().reload_current_scene()
    return {"status": "ok"}

func _set_difficulty(args: Dictionary) -> Dictionary:
    var level = args.get("level", 1)
    GameState.difficulty = level
    return {"status": "ok", "difficulty": level}

Invoke via the run_custom_command GRB command or the corresponding MCP tool.