Bridge & Addon

Free All tools on this page are free, no license required.

Note

20 of these tools require the GodotIQ addon installed in your Godot project. 2 tools (godotiq_script_ops, godotiq_file_ops) are filesystem-only, and 1 (godotiq_ping) requires nothing. Install the addon with godotiq install-addon /path/to/project. See the Addon Reference for details.

How the Bridge Works

The GodotIQ addon (~500 lines of pure GDScript) registers an EngineDebugger peer inside Godot. When the editor starts, the addon opens a WebSocket server on port 6007 (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

godotiq_node_ops

Batch scene editing with full Ctrl+Z undo. Move, rotate, scale, set properties, add children, delete, duplicate, reparent, rename, and get_property, all in a single undoable action. All ops in one call = one undo 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": "godotiq_node_ops",
  "args": {
    "operations": [
      {"op": "move", "node": "Shelf", "position": [2, 0, 3]},
      {"op": "set_property", "node": "Shelf", "property": "visible", "value": true}
    ]
  }
}

---

godotiq_build_scene

Create multiple nodes in a scene using high-level patterns. One call = many nodes with Ctrl+Z undo. Modes: grid, line, scatter, explicit list.

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": "godotiq_build_scene",
  "args": {
    "grid": {"rows": 3, "cols": 4, "spacing": 2.0, "scene": "res://objects/shelf.tscn"},
    "parent": "/root/Main/Shelves"
  }
}

---

godotiq_save_scene

Persist editor changes to disk. Call after godotiq_node_ops or any scene modifications.

Parameters

None. Saves the currently open scene.

---

godotiq_script_ops

Read, write, or patch GDScript files with convention validation. Patch mode (find-and-replace) is safest.

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

godotiq_screenshot

Visual verification of the game or editor viewport. Use scale=0.25, quality=0.3 for token-efficient checks.

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": "godotiq_screenshot",
  "args": { "viewport": "game", "scale": 0.25 }
}

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

---

godotiq_camera

Editor 3D camera control: get current position, reposition, or focus on a node. Editor-side, no game needed.

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": "godotiq_camera",
  "args": { "action": "focus_node", "node": "Player" }
}

---

Runtime

godotiq_run

Start or stop the Godot game. Must call play before using any game-side tools.

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": "godotiq_run",
  "args": { "action": "play", "scene": "res://scenes/levels/test.tscn" }
}

Stop

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

---

godotiq_state_inspect

Query runtime property values. Cheaper than screenshots for checking state. Supports autoload lookup, node paths, nested properties, method calls.

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": "godotiq_state_inspect",
  "args": {
    "queries": [
      {"autoload": "EconomyManager", "properties": ["balance", "daily_revenue"]},
      {"node": "/root/Main/Player", "properties": ["position", "health"]}
    ]
  }
}

---

godotiq_watch

Persistent property monitoring. Start watching, then read accumulated changes over time.

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": "godotiq_watch",
  "args": {
    "action": "start",
    "watches": [{"node": "/root/Main/Player", "properties": ["position"]}],
    "sample_interval_ms": 500
  }
}

---

godotiq_verify_motion

Verify a node property changes over time (proves movement/animation). Takes two snapshots separated by a sleep and compares values.

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": "godotiq_verify_motion",
  "args": { "node": "Player", "property_name": "position", "duration": 2.0 }
}

---

godotiq_read_debug_console

Text-only access to Godot Debugger and console errors. Lets agents inspect runtime errors directly instead of asking you to copy/paste from the Debug window. Capture coverage depends on the active debugger and logger channels for your Godot version.

Parameters

Parameter	Type	Default	Description
limit	int	20	Max number of recent entries to return
clear	bool	false	Clear the captured buffer after reading

Example

Tool call

{
  "tool": "godotiq_read_debug_console",
  "args": { "limit": 20, "clear": false }
}

---

godotiq_verify_project_runs

Conservative verification that the project actually starts. Checks scripts, starts Play, waits briefly, reads debug errors, and optionally stops the game. Returns PASS, FAIL, or INCONCLUSIVE so agents do not silently treat missing evidence as success. Verifies startup and captured errors, not full gameplay correctness.

Parameters

Parameter	Type	Default	Description
scene	string	"main"	Scene to run: "main", "current", or a res:// path
settle_seconds	float	1.0	Seconds to wait after Play before reading the debug buffer
stop_after	bool	true	Stop the game after the check completes

Example

Tool call

{
  "tool": "godotiq_verify_project_runs",
  "args": { "scene": "main", "settle_seconds": 1.0, "stop_after": true }
}

---

godotiq_perf_snapshot

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

Parameters

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

Example

Tool call

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

---

Editor

godotiq_editor_context

Call FIRST alongside godotiq_project_summary. Returns editor state: open scenes, selected nodes, is game running, project path.

Parameters

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

---

godotiq_scene_tree

Live editor scene tree showing actual state with transforms, scripts, groups, and visibility. Unlike scene_map (reads .tscn from disk), this reads the editor’s live state.

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": "godotiq_scene_tree",
  "args": { "root": "/root/Main", "depth": 3 }
}

---

godotiq_undo_history

Review what was changed. Shows undo/redo state and recent GodotIQ action history.

Parameters

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

---

godotiq_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": "godotiq_check_errors",
  "args": { "scope": "scene" }
}

---

godotiq_exec

Execute GDScript code. Last resort; prefer dedicated tools. Code MUST contain ‘func run():’.

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

godotiq_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

godotiq_file_ops

Filesystem operations: list, read, write, move, delete, search, tree, uid_to_path, path_to_uid, rename with reference updates. Respects protected files from .godotiq.json.

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

---

godotiq_input

Simulate player input in the running game: actions, keys, UI taps, waits. Supports signal verification and side-effect tracking.

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": "godotiq_input",
  "args": {
    "commands": [
      {"actions": ["move_left"], "hold_ms": 500},
      {"wait_ms": 200},
      {"actions": ["jump"]}
    ]
  }
}

---

godotiq_ui_map

Map all UI elements on screen: positions, text, interactivity, visibility. Call BEFORE godotiq_input to know what’s on screen. 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

---

godotiq_nav_query

Live pathfinding via NavigationServer3D. “Can A reach B?” Returns path, distance, reachability, navmesh status.

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": "godotiq_nav_query",
  "args": { "from_node": "Player", "to_node": "Exit" }
}

---

Related Tools

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

Tools Overview See all 24 GodotIQ tools.