GoDotter: An AI-Native Editor Plugin Architecture for Godot 4.3+

Forum topic · ✨步子哥 · 2026-05-20

Summary

GoDotter is an open-source, AI-native editor plugin for Godot 4.3+, positioned as a "Cursor for Godot." It combines a GDScript EditorPlugin (ForgeDock UI, EditorBridge, AgentClient, SafetyManager, DiffManager) with a bundled local Python FastAPI backend running by default on 127.0.0.1:8765. The backend handles project indexing, prompt/context engineering, LLM calls (Google Gemini primary; OpenAI, Claude, and OpenAI-compatible endpoints supported), plan generation, and guarded file operations. Workflows follow a plan-then-diff-then-execute model with file edits disabled by default and explicit human approval required. Notable features include a Neon Visual Map (screenshot plus node spatial map for AI layout analysis), fix-from-logs debugging, project memory in .godot_forge/memory/, and image attachments in chat. The plugin ships as a single addons/GoDotter/ folder containing the Python backend; only LLM API calls leave the machine. Version 0.2.0, MIT licensed, with tests via Godot headless checks and Python unittest.

GoDotter: Complete Architecture Analysis

> Translation of the architecture document for godotter: an AI-native editor plugin for Godot 4.3+ (a "Godot version of Cursor").

Overview

| Dimension | Detail | |------|--------| | Form | Godot EditorPlugin + local Python FastAPI backend | | Distribution | Copy addons/GoDotter/ into any Godot project's addons/ | | AI | Google Gemini primary; settings also support OpenAI, Claude, and OpenAI-compatible endpoints | | Deployment | Local-first (default 127.0.0.1:8765); project files stay on machine, only LLM API goes online | | Design principle | Plan → diff → execute; conservative by default, file writes require explicit authorization |

The repo's root project.godot ("GoDotter Dev") is for contributors; game projects typically vendor only addons/GoDotter/.

Key points

Two-layer architecture: a GDScript editor layer (GoDotter.gd entry point, ForgeDock UI, ForgeState settings, EditorBridge context builder, AgentClient HTTP client, SafetyManager/DiffManager/DebugVisualizer) and a Python backend layer (FastAPI app.py, task orchestrator, agent run loop, project indexer, Gemini/multi-provider client, code/git/safety tools). They communicate over HTTP JSON; the plugin spawns the backend via OS.create_process.
Request flow: user enters a goal in Forge Dock (natural language or /plan, /do slash commands) → EditorBridge assembles a context bundle (scene, selected nodes, open scripts, project root) → AgentClient POSTs to the local backend → backend builds prompts from project index, memory files, and token policy → LLM returns structured JSON (a Plan) → UI shows plan/diff/thinking trace; writes go through double safety gates only after user approval.
Single-addon packaging: one addons/GoDotter/ folder = the whole product, including the Python backend (backend/main.py, requirements.txt, .env.example, src/ with tests). No separate agent service installation.
Settings model: machine-level keys under godotter/machine/ (backend dir, Python path, API keys, autostart) and project-level keys (model, AI settings, approval mode, file-edit switch) stored in EditorSettings. Defaults are safe: enable_file_edits = false, approval_mode = "review".
Forge Dock tabs: Chat (multi-mode, multi-session, image attachments, thinking traces, plan approval), Plan (structured steps, optional auto-approval countdown), Inspect, Diff (per-file revert), Memory, Settings. Chat modes include Full agent, Plan, Execute, Scene, Node, Index, Memory, Fix logs, Visual map, Help.

Python backend API (selected endpoints)

| Category | Method | Path | Purpose | |------|--------|------|---------| | Health | GET | /health | Status and API key detection | | Project | POST | /project/index | Scan and index the project | | Project | POST | /project/context | Retrieve relevant context | | Agent | POST | /agent/plan | Architect: generate structured Plan | | Agent | POST | /agent/execute | Code Agent: execute plan, write files | | Agent | POST | /agent/run | Full session: plan → validate → (optional) execute | | Visual | POST | /agent/visual_map | Neon 2D spatial analysis | | Visual | POST | /agent/visual_review_3d | Multi-angle 3D asset review | | Logs | POST | /agent/fix_from_logs | Fix plan generated from runtime logs | | Tools | POST | /tools/read_file, /tools/write_file, /tools/revert_file | Safe file ops with backup/restore | | Git | GET | /tools/git_status | Git status | | Memory | GET | /memory | Read project memory markdown |

Backend stack: FastAPI + uvicorn, google-genai, httpx, Pydantic v2, Pillow, python-dotenv. Core modules include task_orchestrator.py, agent_run.py, project_indexer.py, context_engine.py, gemini_client.py, ai_model_settings.py, code_tools.py/file_tools.py, safety.py, validators.py, visual_map.py, asset3d_review.py, memory_store.py, log_aggregator.py, token_policy.py, and git_tools.py.

Plan data model

The Architect agent returns JSON with: summary; relevant_files / relevant_scenes (must come from the index — no invented paths); assumptions / risks; steps (with description, files_affected, risk_level); validation_plan; and approval_required. Client-side AgentSchemas.gd mirrors backend schemas.py (Pydantic).

Safety and trust model

Two layers of gates: user Settings (enable_file_edits, enable_scene_edits, approval modes review/assisted/autopilot/yolo, per-run file/line limits) feed into SafetyManager.gd (editor) and safety.py (backend), which block protected paths (addons/, .godot/, project.godot, .import), blacklist dangerous operations (deleting repos, changing branches, shell), and require UI approval in review mode. Writes are backed up, with optional git checkpoints and Diff-panel revert. Stance: AI is read-only by default; the user is the creative director; API keys never enter version control.

Signature workflows

Neon Visual Map: scene tree color-coded by node type → editor viewport screenshot → backend sends image + node spatial map to the LLM for layout/overlap/hierarchy analysis.
Fix from logs: GoDotterEditorLogger + GoDotterDebuggerHook → LogCollector, with backend log_aggregator + /agent/fix_from_logs producing batch fix plans.
Project memory: Markdown notes in .godot_forge/memory/ (gitignored) covering architecture conventions, code style, known bugs — injected into planning context.
Chat images: ChatImageLineEdit (file picker, drag-drop, clipboard); Base64-encoded into plan/execute/agent_run via context_images.

Configuration and data

API keys come from editor settings (synced to backend/.godotter_api_key or .godotter_api_keys.json), environment variables (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_BASE_URL, etc.), backend/.env (shell vars take precedence), and backend/config.json (gitignored).
Locally generated, gitignored data: .godot/ cache, .godot_forge/ (index, chat sessions, memory, run logs), backend/.venv/, and local config/key files.
Development checks: godot --headless --path <repo> --check-only for GDScript; python -m unittest discover -s tests -v in the backend; a plan integration test requires GEMINI_API_KEY (skips otherwise).

Boundaries and extension points

Explicit non-goals: not a replacement for learning Godot itself, not a hosted SaaS (backend runs locally), not a general-purpose IDE on par with Cursor — the domain is games/Godot. Evolving capabilities include MCP settings and experimental /agent/*, /tasks/* routes. Recommended extension points: new slash commands/chat modes (ForgeDock.gd routing + backend endpoint), new tools (app.py registration + safety rules), new LLM providers (gemini_client.py, ai_model_settings.py, Settings UI), and new context sources (EditorBridge, project_indexer, memory_store).

Version 0.2.0 (plugin and backend), MIT licensed; the dev project targets Godot 4.6 while the plugin supports 4.3+. See the repo's README.md, INSTALL.md, and backend README for installation and API details.