Bridge & Addon

Pro — $19 All tools on this page require the Godot addon.

Caution

These tools require the GodotIQ addon installed in your Godot project. The addon creates a TCP bridge between your AI and the running editor. See the Addon Reference for installation instructions or Installation for the full setup guide.

How the Bridge Works

The GodotIQ addon registers an EngineDebugger peer inside Godot. When the editor starts, the addon opens a TCP server on port 6550 (configurable in .godotiq.json). GodotIQ’s Python MCP server connects to this port, enabling real-time two-way communication.

This architecture means your AI can:

• Read live game state (scene tree, node properties, UI elements)
• Control the game (run, stop, simulate input)
• Edit scenes (create, move, delete nodes with full undo support)
• Capture screenshots of the editor and game viewports

---

Scene Editing

node_ops

Batch scene editing with full Ctrl+Z undo. Move, rotate, scale, set properties, add children, delete, duplicate, and reparent nodes — all in a single undoable action.

Parameters

Parameter	Type	Default	Description
operations	array	required	List of operations: {op: "move"|"rotate"|"scale"|"set_property"|"add_child"|"delete"|"duplicate"|"reparent", ...}
scene_data	object	null	Optional scene context for validation

Example

Tool call

{
  "tool": "node_ops",
  "args": {
    "operations": [
      {"op": "move", "node": "Shelf", "position": [2, 0, 3]},
      {"op": "set_property", "node": "Shelf", "property": "visible", "value": true}
    ]
  }
}

---

build_scene

Create multiple nodes using high-level patterns. One call = many nodes with undo.

Parameters

Parameter	Type	Default	Description
grid	object	null	Grid pattern: {rows, cols, spacing, scene}
line	object	null	Line pattern: {points, spacing, scene}
scatter	object	null	Scatter: {items: [{scene, position}, ...]}
nodes	array	null	Explicit node list: [{type, name, position}, ...]
parent	string	""	Parent node path
target_scene	string	""	Target .tscn for context

Example

Tool call

{
  "tool": "build_scene",
  "args": {
    "grid": {"rows": 3, "cols": 4, "spacing": 2.0, "scene": "res://objects/shelf.tscn"},
    "parent": "/root/Main/Shelves"
  }
}

---

save_scene

Persist editor changes to disk.

Parameters

None. Saves the currently open scene.

---

script_ops

Read, write, or patch GDScript files with convention validation.

Parameters

Parameter	Type	Default	Description
op	string	"read"	Operation: "read", "write", "patch", "create"
path	string	required	File path (res:// or relative)
content	string	""	File content (for write/create)
patches	array	null	List of {search, replace} dicts (for patch)
validate_before_write	bool	true	Run GDScript validation before writing
dry_run	bool	false	Validate without writing

---

Visual

screenshot

Visual verification of game or editor viewport.

Parameters

Parameter	Type	Default	Description
viewport	string	"game"	Which viewport: "editor", "game", "both"
scale	float	0.25	Image scale factor
format	string	"webp"	Image format
quality	float	0.5	Compression quality
camera_position	array	null	Camera position (editor only)
camera_target	array	null	Camera target (editor only)

Example

Tool call

{
  "tool": "screenshot",
  "args": { "viewport": "game", "scale": 0.25 }
}

The tool returns a base64-encoded image that your AI client renders inline.

---

camera

Editor 3D camera control: get position, reposition, focus on node.

Parameters

Parameter	Type	Default	Description
action	string	required	"get_position", "look_at", or "focus_node"
position	array	null	Camera position (for look_at)
target	array	null	Target point (for look_at)
node	string	null	Node name to focus on (for focus_node)

Example

Tool call

{
  "tool": "camera",
  "args": { "action": "focus_node", "node": "Player" }
}

---

Runtime

run

Start or stop the Godot game from the editor.

Parameters

Parameter	Type	Default	Description
action	string	"play"	"play" or "stop"
scene	string	"main"	Scene to run: "main", "current", or res:// path
timeout	float	auto	Timeout in seconds (auto-detected)

Example

Start

{
  "tool": "run",
  "args": { "action": "play", "scene": "res://scenes/levels/test.tscn" }
}

Stop

{
  "tool": "run",
  "args": { "action": "stop" }
}

---

state_inspect

Query runtime property values. CHEAPER than screenshots — use first.

Parameters

Parameter	Type	Default	Description
queries	array	required	List of {node: "path", properties: ["prop1", "prop2"]} or {autoload: "Name", properties: [...]}
detail	string	"normal"	"brief" (values only), "normal", "full"

Example

Tool call

{
  "tool": "state_inspect",
  "args": {
    "queries": [
      {"autoload": "EconomyManager", "properties": ["balance", "daily_revenue"]},
      {"node": "/root/Main/Player", "properties": ["position", "health"]}
    ]
  }
}

---

watch

Persistent property monitoring across game interactions.

Parameters

Parameter	Type	Default	Description
action	string	"read"	"start", "stop", "read", or "clear"
watches	array	null	For start: [{node: "path", properties: ["prop"]}]
sample_interval_ms	int	500	Sampling interval (min 50)
detail	string	"normal"	Output verbosity

Example

Start watching

{
  "tool": "watch",
  "args": {
    "action": "start",
    "watches": [{"node": "/root/Main/Player", "properties": ["position"]}],
    "sample_interval_ms": 500
  }
}

---

verify_motion

Verify node property changes over time (proves movement/animation).

Parameters

Parameter	Type	Default	Description
node	string	required	Node path or name
property_name	string	"position"	Property to monitor
duration	float	2.0	Seconds between snapshots

Example

Tool call

{
  "tool": "verify_motion",
  "args": { "node": "Player", "property_name": "position", "duration": 2.0 }
}

---

perf_snapshot

FPS, draw calls, memory, node count from running game.

Parameters

Parameter	Type	Default	Description
detail	string	"normal"	"brief" (fps + draw_calls only), "normal", "full"

Example

Tool call

{
  "tool": "perf_snapshot",
  "args": { "detail": "normal" }
}

---

Editor

editor_context

Editor state: open scenes, selected nodes, is game running, project path. Call FIRST.

Parameters

None. Returns editor state. Falls back to filesystem info if addon is disconnected.

---

scene_tree

Live editor scene tree with transforms, scripts, groups, visibility.

Parameters

Parameter	Type	Default	Description
root	string	""	Root node path
depth	int	3	Maximum depth (1-10)
filter_type	string	""	Filter to specific node type
include	array	null	Node types or groups to include
detail	string	"normal"	Output verbosity

Example

Tool call

{
  "tool": "scene_tree",
  "args": { "root": "/root/Main", "depth": 3 }
}

---

undo_history

Review what was changed — undo/redo state and action history.

Parameters

None. Returns can_undo, can_redo, current_action, and GodotIQ action list.

---

check_errors

Check GDScript files for compilation/parse errors.

Parameters

Parameter	Type	Default	Description
scope	string	"scene"	"scene" (current scene + autoloads), "project" (all .gd), or "res://path/to/script.gd"

Example

Tool call

{
  "tool": "check_errors",
  "args": { "scope": "scene" }
}

---

exec

Execute GDScript code. Last resort — prefer dedicated tools.

Parameters

Parameter	Type	Default	Description
code	string	required	GDScript code containing func run():. Return value is stringified.
context	string	"game"	"game" (sandbox) or "editor" (full editor access)
timeout_ms	int	5000	Max execution time in milliseconds

Caution

exec has broad access. It runs code with full privileges in the chosen context — use it carefully and prefer dedicated tools when available.

---

I/O

file_ops

Filesystem operations within Godot project: list, read, write, move, delete, search, tree.

Parameters

Parameter	Type	Default	Description
op	string	"list"	Operation: "list", "read", "write", "move", "delete", "search", "tree", "rename"
path	string	""	File or directory path
query	string	""	Search query (for search op)
filter	string	"all"	Type filter: "all", "scenes", "scripts", "images", "audio", "fonts", "models", "shaders", "resources"
recursive	bool	false	Recursive listing
content	string	""	Content for write op
destination	string	""	Destination for move/rename ops

---

input

Simulate player input: actions, keys, UI taps, waits.

Parameters

Parameter	Type	Default	Description
commands	array	required	Sequential commands: action {actions, hold_ms}, wait {wait_ms}, key {key, hold_ms}, UI tap {tap: "NodeName"}
track_side_effects	bool	false	Monitor autoload state changes
continue_on_error	bool	false	Continue on errors

Example

Tool call

{
  "tool": "input",
  "args": {
    "commands": [
      {"actions": ["move_left"], "hold_ms": 500},
      {"wait_ms": 200},
      {"actions": ["jump"]}
    ]
  }
}

---

ui_map

Map all UI elements: positions, text, interactivity, visibility. See also the dedicated UI Mapping page.

Parameters

Parameter	Type	Default	Description
root	string	""	Root node (empty = entire UI tree)
include_invisible	bool	false	Include hidden elements
max_depth	int	10	Maximum tree traversal depth
detail	string	"normal"	Output verbosity

---

nav_query

Live pathfinding via NavigationServer3D. Can A reach B?

Parameters

Parameter	Type	Default	Description
from_node	string	null	Source node name
to_node	string	null	Target node name
from_position	array	null	Source coordinates [x, y, z]
to_position	array	null	Target coordinates [x, y, z]
optimize	bool	true	Optimize the path
detail	string	"normal"	"brief" (reachable + distance only), "normal", "full"

Example

Tool call

{
  "tool": "nav_query",
  "args": { "from_node": "Player", "to_node": "Exit" }
}

---

Related Tools

• Spatial tools — placement pairs with screenshot for visual verification
• UI mapping — Dedicated page for ui_map with detailed workflows
• Installation — Full setup guide including addon installation
• Guides: Workflows — Common bridge tool workflow patterns

Tools Overview See all 35 GodotIQ tools.