hi-godot/godot-ai

Godot AI – AI‑powered Godot editor plugin

What it is – Godot AI is a Godot 4 editor add‑on that lets large‑language‑model (LLM) agents (Claude, Codex, Hermes, etc.) talk directly to a running Godot editor. The plugin exposes 46 tools and more than 120 operations (scene creation, node editing, script generation, signal wiring, UI layout, material tweaking, animation, particle systems, camera setup, etc.) so an AI client can build or modify a game project without the user writing code manually.

How it works

1. An MCP client (Claude Code, Codex, Hermes Agent, …) runs on the developer’s machine.
2. The client invokes godot‑ai attach, which starts a Python bridge server (authenticated HTTP on port 8000).
3. The bridge talks to the Godot editor plugin via an authenticated WebSocket (port 9500, loop‑back only).
4. All communication is capability‑token based and rotates automatically, providing a security boundary between the AI and the editor.

Key capabilities

• Scene graph manipulation – create nodes, rename, re‑parent, delete, query hierarchy.
• Script handling – generate GDScript (full parse‑validation, hot‑reload) and C# (text‑only file creation/patching).
• Asset management – search for PackedScenes, add materials, configure particles, set up cameras and environments.
• Testing & execution – run the scene test suite, launch the game, or trigger custom build steps.
• Extensible tool set – documented in docs/TOOLS.md; community addons can add more operations.

Getting started

1. Install Godot 4.7+ and the Python‑based uv tool (provides uvx).
2. Download the latest release from the GitHub Releases page and place it in your‑project/addons/godot_ai/.
3. Enable the plugin in Project → Project Settings → Plugins → Godot AI.
4. In the new Godot AI dock, click Configure to add your MCP client (Claude Code, Codex, etc.). The dock generates the exact command line the client must use.
5. Issue natural‑language commands (e.g., “Create a Camera3D named MainCamera under /Main.”) and watch the editor update in real time.

Supported languages

• GDScript – full support with syntax checking and hot‑reload.
• C# – the plugin can create/patch .cs files and outline symbols, but it does not compile or surface compiler errors; you must build the project yourself.

Security & privacy

• All local hops use rotating capability tokens; the WebSocket is loop‑back only.
• Telemetry (if enabled) sends only anonymised usage data (UUID, event, duration, platform, version). It can be disabled via GODOT_AI_DISABLE_TELEMETRY=true.
• The README provides detailed guidance for Linux permission quirks (Fedora Atomic, Steam/Flatpak, etc.) and how to set a custom capability directory.

Typical use cases

• Rapid prototyping: describe a gameplay mechanic in plain English and let the AI scaffold the scene, scripts, and assets.
• Iterative development: ask the AI to refactor node hierarchies, adjust UI layouts, or add new particle effects.
• Learning aid: newcomers can explore Godot’s API by asking the AI to generate example code snippets.

Limitations

• C# support is limited to file generation; compilation feedback must be handled manually.
• The bridge requires a local Python server; remote agents need SSH tunnelling or a container setup as described in the docs.
• Security relies on the local user’s trust; a compromised process running as the same user could misuse the capability tokens.

License – MIT (see LICENSE).

---

All information above is taken directly from the repository’s README; no external assumptions have been added.