DOCSEARCHbyAlgolia
Submit Docs

Godot AI

repository·main·Indexed 11 days ago

https://github.com/hi-godot/godot-ai

A production-grade Model Context Protocol (MCP) server and set of AI tools for the Godot engine. It bridges AI assistants—such as Claude Code, Codex, and Antigravity—to the Godot editor, enabling them to programmatically manipulate scenes, nodes, scripts, and project files in real-time. Version 3.1.5 requires Godot 4.5 or higher (4.7+ recommended) and the uv Python package manager.

Tokens
48.4K
Snippets
104
Records
210
Agent score
77%

What's inside Godot AI

  1. Overview of Godot AI

    main

    Godot AI allows you to connect Model Context Protocol (MCP) clients directly to a live Godot editor. It provides over 120 operations across approximately 43 MCP tools, enabling AI assistants (such as Claude Code, Codex, Grok Build, Antigravity, and Hermes Agent) to interact with your Godot project.

    Capabilities include:

    • Building scenes
    • Editing nodes and scripts
    • Wiring signals
    • Configuring UI, materials, animations, particles, cameras, and environments.

  2. Overview of Godot AI MCP Tools

    main

    Godot AI exposes approximately 43 Model Context Protocol (MCP) tools. To stay within client-side tool limits, the API uses two primary patterns:

    1. High-traffic Verbs: 19 common actions (like node_create or scene_open) are exposed as individual, top-level tools.
    2. Domain Rollups: For less frequent actions, Godot AI uses a <domain>_manage pattern. Instead of many tools, you call one tool with an op parameter and a params dictionary (e.g., editor_manage(op="...")).

    Important Note on Command Execution: When using batch_execute, you must use the underlying plugin command names (e.g., create_node, set_property) inside the commands[].command field, not the MCP tool names.

  3. Handle concurrent MCP client commands during test runs

    main

    While a test_run is active and holding the editor, the plugin manages incoming commands from other MCP clients as follows:

    • Rejection: Commands arriving while the editor is busy are rejected immediately with a retryable EDITOR_NOT_READY error (with sub_code: EDITOR_TEST_RUNNING).
    • Action: You should retry the command after the run completes or fetch existing results using test_manage(op="results_get").
    • Command Flooding: If a command flood exceeds 2048 packets during a single run, the connection is closed (code 1013) to prevent buffering stale commands. The run will abort, but partial results are preserved.

  4. Capabilities of the Native MCP Scenario

    main

    The Godot AI MCP tools support a wide range of editor and runtime operations, including:

    • Scene & Node Management: Creating and saving scenes (scene_create/save), creating nodes, and modifying properties.
    • Resource & Material Management: Creating themes, materials, and presets (camera, particle, environment).
    • Scripting: Creating, reading, and attaching scripts; connecting and listing signals.
    • Input & UI: Managing input actions, bindings, and lists; creating UI layouts and draw recipes.
    • Project & Runtime: Running and stopping the project (project_run), reading game logs, and managing project settings.
    • Visuals & Screenshots: Capturing cinematic and viewport coverage screenshots, and retrieving screenshot metadata.
    • Execution: Using batch_execute for multiple operations.

  5. Understand the Session and Readiness Model

    main

    The server uses a session model to distinguish between live editor instances and prevent write operations when the editor is in an unsafe state.

    Session Metadata

    Each session is identified by a unique ID formatted as <project-slug>@<4hex> (e.g., godot-ai@a3f2). Metadata includes the project path, editor PID, Godot/plugin/server versions, and current readiness state.

    Readiness States

    • ready: Editor is stable.
    • importing: Filesystem is being processed (writes are held/retried).
    • playing: The game is running (writes are rejected).
    • no_scene: No scene is currently loaded (writes are rejected).

    Implementation Contract for Write Handlers

    To ensure safety, all write operations must check the session readiness.

    • Python Handlers: Must await require_writable_async() in handlers/_readiness.py to gate execution.
    • Self-Healing: The system uses a two-layer cache refresh. Every command response carries a readiness field in its envelope. If a cache is stale, require_writable_async performs a get_editor_state probe before rejecting.

  6. Verify pixel-level capture for editor-to-game boundary tools

    main

    For tools that cross the boundary between the Godot editor and the running game process, use pixel-level capture smoke tests. These tests ensure that the _mcp_game_helper autoload, the DEFERRED_RESPONSE dispatcher, and the McpConnection.send_deferred_response pipeline are working correctly.

    These tests run with a real rendering driver (e.g., opengl3 on Linux via xvfb-run) and validate that colors captured from the game process match expected values in a test scene.

  7. Understand the Godot AI server lifecycle in development

    main

    The Godot AI plugin manages a Python server process to facilitate MCP communication.

    Plugin-Managed Servers

    When the plugin starts, it checks if port 8000 is in use. If not, it spawns the server using the local .venv (preferring it over system installs) with the command: .venv/bin/python -m godot_ai --transport streamable-http --port 8000.

    External Servers (Adoption)

    If you start the server manually (e.g., via CI scripts or a hand-started dev server), the plugin will 'adopt' it using server_lifecycle.gd::adopt_compatible_server.

    Crucial Note on Ownership: When the plugin adopts an external server, it does not take process ownership. The plugin sets _server_pid = -1 and clears managed PID files. Consequently, closing the Godot editor will not kill an externally started server; it will continue running.

  8. Understand the Godot AI testing strategy and layers

    main

    Godot AI uses a multi-layered testing strategy to ensure new capabilities are stable and safe. The strategy is divided into several layers depending on the scope of the feature:

    • Unit tests: Focus on request validation, protocol serialization, pagination, session routing, readiness checks, error mapping, and runtime handlers that don't require a live editor.
    • Integration tests: Focus on tool orchestration (using mocks), reconnection behavior, stale reference handling, partial batch failures, and Python/server-side runtime behavior.
    • Contract tests: Validate the plugin/server boundary, including handshakes, versioning, command envelope shapes, response/error schemas, and capability signaling.
    • Godot-side test suites: In-editor GDScript suites used for scene/node mutation, signals, autoloads, filesystem handlers, and tools depending on Godot editor APIs (like undo semantics).
    • End-to-end and release-smoke tests: Real-project tests covering project opening, plugin connection, scene mutation, script attachment, and project execution.

    When adding new tool families, coverage should scale with complexity: simple read tools need unit/integration tests, while write tools require Godot-side behavioral tests. Runtime or release tools require smoke coverage.

  9. Understand Godot AI telemetry data collection

    main

    Godot AI collects anonymous, privacy-focused telemetry to improve tools and performance.

    Privacy Protections

    • Anonymous: Uses a randomly generated UUID per installation. No personal identifiers (email, IP, account) are collected.
    • Salted Session IDs: Project directory slugs are hashed using sha256(customer_uuid + slug) to prevent cross-user correlation.
    • Non-blocking: Telemetry is handled via an in-process queue and a daemon worker; failures do not affect tool execution.
    • Never Collected: Source code, scene contents, file paths, project names (unhashed), and editor logs/console output.

    Collected Data Types

    • Tool & Resource Execution: Name, sub_action (for rollup tools), success status, duration, and error categories (structured error codes or exception class names).
    • Startup: Server version, ws_port, startup latency, and diagnostic hint policy status.
    • Connection Events: Godot version, plugin version, protocol version, and session counts.
    • Plugin Events: Specific lifecycle events like dock_startup, plugin_reload, self_update, and dev_server_toggle.

  10. Understand the MCP tool surface and tool-count management

    main

    The Model Context Protocol (MCP) tool surface in Godot AI is optimized to handle two types of clients:

    1. Search-enabled clients (e.g., Anthropic tool-search clients): These use BM25 or regex to find tools. Non-core tools are tagged with meta={"defer_loading": True} so they are only loaded when searched for.
    2. Tool-capped clients (e.g., Antigravity): These clients may refuse to start if there are too many tools (typically >40). To prevent this, Godot AI uses rollups.

    Tool Organization

    • Core Tools: Always loaded (no meta= tag). These include editor_state, scene_get_hierarchy, node_get_properties, and session_activate.
    • Named Verbs: High-traffic tools registered as individual tools.
    • Rollups (<domain>_manage): Long-tail verbs are collapsed into a single tool per domain. Instead of many tools, you call one tool with an op="<verb>" parameter and a params dictionary. Schema-aware clients can still see every individual operation via the dynamic Literal[...] enum.
    • Namespacing: All tools follow a domain_action naming convention to avoid ambiguity.

    Managing Tool Counts

    If you are using a tool-capped client, you can reduce the tool count by excluding entire domains using the --exclude-domains CLI flag (e.g., --exclude-domains audio,particle).

  11. How MCP client configuration works

    main

    The Godot AI plugin uses a registry and strategy system to auto-configure 22 Model Context Protocol (MCP) clients. This system relies on two core principles:

    1. Descriptors are data only: Client descriptors (located in plugin/addons/godot_ai/clients/) must contain only data. They cannot contain Callable fields or control flow. Logic is handled by strategies that interpret this data.
    2. Declarative branching: Instead of using branching logic inside strategies, non-standard entry shapes are expressed declaratively on the descriptor using specific keys (e.g., entry_url_field, command_shape, config_path_candidates).

    To add a new client, you must:

    • Create a new file clients/<name>.gd that extends McpClient.
    • Append one preload statement to _registry.gd.

    No modifications to the dock, facade, or strategies are required.

  12. Understand test run outcomes and timeouts

    main

    Test runs in v3 follow a specific outcome contract. If a run exceeds the server budget (typically 300s, with a minimum floor of ~290s before aborting), it will return a TEST_RUN_TIMEOUT along with any partial results collected up to that point.

    Outcome Schema for run_suites_serviced(...): When calling the serviced runner, the response contains:

    • outcome: One of completed, timeout, transport_lost, or paused.
    • results: A dictionary containing the test results (compatible with what get_results() returns).

    Important Limitation: Servicing (processing MCP commands) occurs between atomic phases. If a single phase (e.g., a very long test body, a massive script load, or a heavy suite_setup) lasts longer than the heartbeat window (~20–40s), it can still cause a transport starvation and a heartbeat disconnect.