FAQ
Compatibility
Section titled “Compatibility”What versions of Godot are supported?
Section titled “What versions of Godot are supported?”Godot 4.2 and later. GodotIQ reads .tscn, .gd, and .tres files in the Godot 4 format. Godot 3.x projects use a different file format and are not supported.
What Python version do I need?
Section titled “What Python version do I need?”Python 3.10 or later. GodotIQ uses modern Python features (type unions, match statements) that require 3.10+.
What platforms does GodotIQ run on?
Section titled “What platforms does GodotIQ run on?”Windows, macOS, and Linux. The MCP server is pure Python with no native dependencies. The Godot addon uses GDScript and works on all platforms Godot supports.
Which AI clients work with GodotIQ?
Section titled “Which AI clients work with GodotIQ?”Any MCP-compatible client. Tested with:
- Claude Code (recommended)
- Cursor
- Windsurf
- VSCode with Copilot
See the client guides for setup: Claude Code, Cursor, Windsurf, VSCode.
Free vs Pro
Section titled “Free vs Pro”What do I get for free?
Section titled “What do I get for free?”15 tools that work by reading your project files directly — no addon, no license required:
- Spatial:
scene_map,placement,spatial_audit - Code:
dependency_graph,signal_map,impact_check,validate - Flow:
trace_flow - Memory:
project_summary,file_context - Assets:
asset_registry,suggest_scale - Animation:
animation_info,animation_audit - Utility:
ping
These cover spatial intelligence, code analysis, flow tracing, project memory, asset management, and animation analysis.
What does Pro add?
Section titled “What does Pro add?”20 bridge tools that require the Godot addon and a live connection to the editor:
- Scene Editing:
node_ops,build_scene,save_scene,script_ops - Visual:
screenshot,camera - Runtime:
run,state_inspect,watch,verify_motion,perf_snapshot - Editor:
editor_context,scene_tree,undo_history,check_errors,exec - I/O:
file_ops,input,ui_map,nav_query
These enable real-time interaction: scene editing, capturing screenshots, running the game, runtime monitoring, editor integration, and I/O operations.
Does GodotIQ work without the addon?
Section titled “Does GodotIQ work without the addon?”Yes. The 15 free tools work entirely by reading project files. They don’t need the addon, a license, or even Godot to be running. Install GodotIQ, point it at a project directory, and start asking questions.
Performance
Section titled “Performance”Does GodotIQ affect Godot’s performance?
Section titled “Does GodotIQ affect Godot’s performance?”The free tools don’t interact with Godot at all — they read files on disk. Zero runtime impact.
The addon bridge adds a lightweight TCP listener inside the editor. It has no measurable impact on editor or game performance. The bridge only processes commands when your AI makes a tool call.
How does GodotIQ affect token usage?
Section titled “How does GodotIQ affect token usage?”Tool outputs contribute to your AI context window. GodotIQ provides three verbosity levels to manage this:
| Level | Token impact | Best for |
|---|---|---|
brief | ~80% fewer tokens | Large projects, routine operations |
normal | Baseline | General development |
full | ~40% more tokens | Debugging, investigation |
Set detail_level in .godotiq.json or pass detail per tool call.
Security & Privacy
Section titled “Security & Privacy”Does GodotIQ send data anywhere?
Section titled “Does GodotIQ send data anywhere?”No. GodotIQ is fully local:
- The MCP server runs on your machine.
- The addon communicates over localhost only.
- There is no telemetry, analytics, or phone-home behavior.
- No project data is sent to GodotIQ’s servers (there are none).
Your project data flows from GodotIQ to your AI client, which processes it according to that client’s privacy policy. GodotIQ itself transmits nothing externally.
Can GodotIQ modify my project files?
Section titled “Can GodotIQ modify my project files?”The free tools are read-only — they analyze but never modify project files.
Bridge tools (node_ops, exec, script_ops, file_ops, etc.) can modify scenes and resources through the Godot editor. Use protected_files and disabled_tools to restrict access.
Licensing & Pricing
Section titled “Licensing & Pricing”How much does Pro cost?
Section titled “How much does Pro cost?”One-time purchase. See the landing page for current pricing.
Is it a subscription?
Section titled “Is it a subscription?”No. One-time payment, lifetime updates. All future versions are included.
Can I use it commercially?
Section titled “Can I use it commercially?”Yes. The personal license allows commercial use. Use GodotIQ to build commercial games — no royalties, no restrictions on what you ship.
How many machines can I use it on?
Section titled “How many machines can I use it on?”The license is per-developer. Install it on as many of your own machines as you want. Each team member needs their own license.
Is the Community edition open source?
Section titled “Is the Community edition open source?”The free tools are MIT-licensed and open source. The Pro addon is proprietary.
Troubleshooting
Section titled “Troubleshooting””Tool not found” error
Section titled “”Tool not found” error”Your AI client can’t see GodotIQ’s tools. Check:
- The MCP server is running and configured in your client. See Installation.
- The tool isn’t listed in
disabled_toolsin.godotiq.json. - Restart your AI client — some clients cache the tool list at startup.
Bridge tools fail but free tools work
Section titled “Bridge tools fail but free tools work”The MCP server is running but the Godot addon isn’t connected:
- Check the addon’s bottom panel in Godot — is the status green?
- Verify the port matches in both
.godotiq.jsonand the addon settings. - See Addon Troubleshooting for detailed steps.
”Protected file” error
Section titled “”Protected file” error”A tool tried to modify a file matched by your protected_files patterns. This is working as intended — remove the pattern from .godotiq.json if you want to allow modifications.
GodotIQ is slow on my large project
Section titled “GodotIQ is slow on my large project”For projects with 100+ scenes, set "detail_level": "brief" in .godotiq.json. This reduces output size by ~80% and speeds up tool responses significantly.
How do I update GodotIQ?
Section titled “How do I update GodotIQ?”pip install --upgrade godotiqFor the addon, download the latest version and replace the addons/godotiq/ directory.