Bridge & Addon

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

Note

18 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_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 22 GodotIQ tools.