Skip to content

Latest commit

 

History

History
245 lines (219 loc) · 17.3 KB

ROADMAP.md

File metadata and controls

245 lines (219 loc) · 17.3 KB

Godotwright Roadmap

Godotwright is an AAA-focused coding toolkit and agent for Godot 4. It works with any coding agent (Claude, Codex and others) and any LLM, cheap or premium. The goal: agents build better Godot games with Godotwright than without it, aiming for the quality bar of an established studio.

  • License: MIT
  • Target engine: Godot 4.7.x (4.7.2 at time of writing)
  • Stack: Node.js + TypeScript
  • Distribution: npm package + official MCP Registry

Design: two layers

Layer 1: toolkit for any agent. An MCP server plus a CLI. Agents load their project data into it and get Godot knowledge, real checks (headless Godot runs, script tests, screenshots) and a fixed AAA checklist.

Layer 2: Godotwright's own agent. Built on top of layer 1. It can call any LLM provider. Cheap models get small, well-scoped tasks and stricter checks. Premium models handle the big design decisions.

We build layer 1 first, because it makes every existing agent better right away.

Layer 1 steps

Each step is small and has a clear "done" check.

  1. Skeleton. Project setup, AGENTS.md, tests, CI. Done when: godotwright --help works and tests pass.
  2. Project scan. Agents load their project in. Godotwright builds a compact map: scenes, nodes, scripts, signals, autoloads and key project settings. Short output for cheap models, detailed output for premium models. Done when: the scan of a test project gives a correct map.
  3. Real checks. Run Godot headless to find errors in scripts and scenes. Done when: a broken script is reported with file and line number.
  4. API knowledge. The official Godot 4.7 class reference, searchable offline, so models stop inventing functions that do not exist. Done when: every looked-up class, method and signal matches Godot 4.7.
  5. AAA review. Fixed rules for performance, code quality and project structure, with a score per category. Done when: a report with scores is produced for a test project.
  6. MCP server. Everything above exposed as tools, with model-tier profiles (cheap vs. premium). Done when: it works in both Claude Code and Codex.
  7. Benchmark. A fixed set of Godot tasks, run with and without Godotwright. Done when: we have before/after numbers.

Learning

Godotwright gets better with every use, without collecting anything personal.

  1. Local learning. Remember per machine which rules real Godot confirms or contradicts, which findings were false alarms, and what failed API lookups meant. Done when: tests show reviews and lookups improve from earlier use, and nothing leaves the machine.
  2. Opt-in sharing. Users who say yes send anonymous counters (no code, names or paths), and can see exactly what would be sent first. Done when: tests prove a report holds nothing from the project, and nothing is sent without a yes.
  3. Collector. A small server that accepts reports and aggregates them, keeping only what at least 3 installs reported.
  4. Shared knowledge. Aggregated results ship with each release, so every user benefits.

3D models

  1. Model inspect and lint. Read .glb and .gltf without Godot and review them with the same scores and exit codes as review: flipped faces, open edges, normals, UVs, tangents, textures, node names and budgets. Done when: every rule has a test with a good and a bad model.

  2. Model contract. A small file that lists the node names, sizes and triangle budget a model must keep, so renamed nodes or drifting sizes are caught. Done when: a renamed node or a model that grows past its tolerance is reported.

  3. Model builder. A small mesh kit (boxes, extrusions, roofs, surfaces of revolution, UVs, tangents, deterministic GLB writer) and model build <kind>, starting with house. Done when: every kind passes model lint without errors and loads in Godot.

  4. Model spec. A JSON description of any model as a tree of parts, with expressions, mirror and repeat, so an agent can build things Godotwright has no ready-made kind for. Done when: a 30-line car spec builds a clean model.

  5. Object knowledge. An archetype library (what a thing is, its parts, sizes, variants, pivots) with model identify and model archetypes. Done when: "tractor", "helikopter", "windmill", "boot" and nonsense each get a sensible, tested answer. 16b. Checks against an archetype (model lint --archetype): a model without wheels, with a wheel pivot off the hub, or ten times too big is reported. Done when: a good car passes and each of those mistakes is reported.

  6. MCP tools for models (godot_model_identify, _spec, _build, _lint, _inspect) with the workflow in the server instructions. Files are read and written only inside the project. Done when: an agent can go from a name to a checked .glb with these tools alone.

  7. Recipes. Ready-made specs in data/recipes/ (car, tractor, helicopter, airliner, ship, trees, wind turbine, container, truck, bus, motorcycle, bicycle, train, tank, light aircraft, fighter, drone, boat, sailboat, piston and jet engine, barn, tower, church, windmill, apartment, bridge, road, railway track, street lamp, fence, power pylon, palm, bush, grass, flower, crate, barrel, chair, table, campfire, rowing boat, rocket, satellite, castle, humanoid, horse, dragon, spaceship so far), each checked against its archetype and tested at the edges of its parameters.

  8. Recipes for most archetypes. model recipes lists the 41 recipes, and model contract --archetype starts a contract from an archetype. The terrain kind covers mountains, islands and lakes; house and sea are kinds too. Not buildable yet: aircraft.fixed-wing.airplane (no recipe or kind), and the knowledge-only open-world archetypes coast, river, biome and settlement. Still to do: a contact-sheet render.

  9. Open worlds. Step 1 (done): the knowledge, as archetypes in data/archetypes/world.json: terrain, mountain, island, coast, sea, lake, river, biome and settlement, with the rules of world building (tiles that share their border heights, y = 0 as sea level, collision from the same heights, levels of detail, instanced scatter, floating origin). Step 2 (done): terrain (a heightmap tile from seeded noise: plains, hills, mountains or an island; tiles with the same seed match on every border, tested) and sea (a water plane and a floor); surfaces by nature are marked sheet in the archetypes, so the open border of a tile is not reported as open edges but a hole is. Step 3 (done): a lake: a bowl carved into the terrain from world coordinates (so it can span tiles) and a water surface at a level half a metre under the lowest point of its rim. Step 4 (done): a river that winds towards +z, with a bed that follows the lowest ground across it and never rises, so the water always runs downhill and lies below the ground beside it (tested over many seeds), and a water surface that falls smoothly row by row. Step 5 (done): collision. model build terrain --collision heightmap writes a HeightMapShape3D next to the tile and a scene with the tile and its StaticBody3D; the heights are divided by the grid step and the shape is scaled by it, as Godot needs. Tested in Godot 4.7.2 with GodotPhysics3D and Jolt: rays land within half a millimetre of the mesh, on grid points and inside cells (both split each cell along the same diagonal as the mesh). Next: scatter points for plants and settlements, and checks for streaming budgets. Same method as models: archetypes first, then recipes.

  10. Support for small, cheap models. Step 1 (done): model view (three letter views, a parts table) and the floating-part check, from a test with six small-model agents (docs/cheap-models.md). Step 2 (done): model brief (and godot_model_brief), one page with the closest ready-made kind, parts, size, rules, mistakes, the order of tools and a short spec cheat sheet; model recipes <kind> prints a recipe to edit; model spec --short. Step 3 (done): lint --archetype says what it compared (parts found, nodes matched to no part, size checked, or that nothing matched), and archetypes for fortifications, creatures, spacecraft, a rowing boat and a campfire. Next: recipes placeable inside a spec, recipes for the new archetypes, then the same six tasks again to measure the difference.

Learning from real projects

  1. Lessons. Anonymous lessons from real Godot projects in data/lessons.json (symptom, cause, fix, test, the rule that checks it), searchable by words, Godot message, rule, topic and archetype (godot_lessons, godotwright lessons), shown under check errors, behind review findings and in the model brief. Done when: a Godot message from a real project finds its lesson, and every bundled lesson passes the scrubber unchanged.

  2. Self-learning. Lessons kept on this machine (godot_lesson_add), scrubbed of names, paths and code; feedback on lessons ranks them; rules marked as false alarms far more often than right drop a level; learn gaps lists what Godotwright cannot predict yet; opted-in installs share lesson counts (ids only), aggregated with k-anonymity. Done when: tests show a lesson kept here comes back for the same Godot error, a local lesson never reaches a report, and a gap shared by many installs can be read as the next rule.

  3. From gaps to rules. Turn the gaps many installs share into review rules, and proposed lessons (godotwright lessons export) into bundled ones, each release. First round done: override signatures, GPU read-backs in loops, SceneTree tests that read too early and shaders that read their own depth became rules. Second round: coroutines used without await, timers started outside the tree, MultiMesh formats set too late, borrowed viewport worlds, time-modulo triggers, lone ternaries, find_children() that skips unowned nodes, worker tasks never waited for, always-rendering SubViewports and debug-only monitors.

  4. Agents in the loop. Hooks for coding agents (godotwright hook, wired in the Claude Code plugin): the review after every edit of a Godot file, lessons under Godot errors in command output, a last look at open errors before the agent stops, and a short project brief at the start. Task skills (debug, perf, vehicles, world, model, patch) and seven subagents (reviewer, debugger, migrator, performance, shader specialist, model builder and test engineer) in the plugin. Done when: an agent that edits a broken script gets the errors back without calling a tool, every hook stays silent when it has nothing to add, and no hook can block the agent by failing.

  5. What competitors have, headless. From a survey of about forty Godot AI tools: runtime errors with their call chain, play runs that stop on a condition, record signals, sum values up and check claims, a frame-time profile with a baseline, a one-call triage (godot_doctor) and mechanical fixes (godot_fix), signal connections checked for their argument count, and reviews fast enough for every edit on a game with 800 scripts. Done when: each runs against real Godot 4.7.2 in CI, and the review stays quiet on the official demos.

  6. A game session that stays up. Start the game once, then query the tree, read and set values, call, evaluate, step with input until a condition holds and read new errors across calls (godot_session, godot_game), through a temporary SceneTree script on a loopback port with a token, so nothing in the project changes. Most competitors have this through an editor add-on. Done when: a session steps frame-exact like godot_play in CI with real Godot, and stops by itself when idle.

  7. What competitors have, round two. From a second survey (November 2026) of about forty Godot AI tools, their issue trackers and user complaints: shader review and a headless compile, real exports with a PCK reader, smoke runs and patches, scene integrity with uid repair, saved scenarios with JUnit, screenshot baselines, leak cycles, rules for the 4.6 and 4.7 changes with a two-binary check, resource and import editing, tool sets and read-only, structured results, progress and cancel, and protected paths. Ships as 0.6.0, on top of the released 0.5.0 (godot_code, shader drawing, screenshot baselines): one shader compile path (headless, with the GPU pass on request) and one baseline implementation, with 0.5.0's options kept. Done when: each is checked against real Godot 4.7.2 in CI, and the review stays quiet on the official demos.

  8. Dreaming. Between sessions, look back at the learning file, the journal and (when asked) the session transcripts, and propose draft lessons for recurring Godot errors, project hints for guessed API names, lessons to merge, retire or rewrite, lessons about undone writes, noisy rules and contradictions, each with its evidence; apply through the journal, keep lessons for agents only on this machine (never in the repository), and say at session start when a dream is due. Deterministic and local. Done when: tests cover every proposal kind, no transcript text reaches any output, the due logic, and that an apply is undone in full.

  9. The whole change, not the one file. From watching agents work: they check the file they edited and stop, they cannot read a .tscn diff, and they get collision layers wrong more than anything else. godot_diff compares what changed by meaning against git and marks what it breaks elsewhere, godot_impact walks the file graph back to every scene, test and saved scenario a change reaches and lists the checks to run, and godot_collisions maps physics layers and masks and says who detects whom. Done when: a removed function that a scene connection still names, a scene three levels above an edited script, and a mask written as a layer number are each reported, with tests, without Godot.

  10. A tool list that costs almost nothing. The biggest cost of every Godot MCP server, this one included: the tool list is paid on every turn (43 tools, about 22,000 tokens; editor servers have up to 170 tools), some clients stop at 40 tools, and in the benchmark the strongest models never called a tool. Lean mode offers two tools, one that runs any tool by name and one that gives its parameters. Done when: the lean tool list is at least twenty times smaller, every tool still runs with its own result, and a wrong call is answered with the parameters. Next: measure tool use and task results in the benchmark with and without lean mode.

After layer 1

  • Release on npm and the MCP Registry.
  • Layer 2: Godotwright's own agent with model tiers.

Status

  • Name, repository, MIT license
  • Design and roadmap
  • Step 1: Skeleton
  • Step 2: Project scan
  • Step 3: Real checks
  • Step 4: API knowledge
  • Step 5: AAA review
  • Step 6: MCP server
  • Step 7: Benchmark (see bench/RESULTS.md)
  • Step 8: Local learning
  • Step 9: Opt-in sharing (sends nothing until a collector is set up)
  • Step 10: Collector (reference server; not hosted yet)
  • Step 11: Shared knowledge (data/learned.json, empty until reports come in)
  • Learning from public projects for free (weekly Learn workflow on the official demos)
  • Released on npm (godotwright)
  • Listed in the MCP Registry
  • Step 12: Model inspect and lint (model inspect, model lint)
  • Step 13: Model contract (model.contract.json)
  • Step 14: Model builder (kinds house, terrain, sea; model build)
  • Step 15: Model spec (model spec)
  • Step 16: Object knowledge (model identify, model archetypes)
  • Step 16b: Checks against an archetype (model lint --archetype)
  • Step 17: MCP tools for models (godot_model_identify, _spec, _build, _lint, _inspect)
  • Step 18: Recipes (41 so far, in data/recipes/)
  • Step 22: Lessons from real projects (data/lessons.json, godot_lessons)
  • Step 23: Self-learning (local lessons, lesson feedback, rules that learn from false alarms, learn gaps)
  • Step 24: From gaps to rules, every release (two rounds done)
  • Step 25: Agents in the loop (hooks, task skills and subagents in the Claude Code plugin)
  • Step 26: What competitors have, headless (doctor, fix, perf, richer play, call chains, connection arguments)
  • Step 27: A game session that stays up across calls
  • Step 28: What competitors have, round two
  • Step 29: Dreaming (godotwright dream, godot_dream, the godot-dreamer subagent)
  • Step 30: The whole change (godot_diff, godot_impact, godot_collisions)
  • Step 31: Lean mode (godotwright mcp --lean)
  • Step 19: Recipes for most archetypes
    • Contact-sheet render
    • Archetypes without a recipe: the airplane, and coast, river, biome and settlement
  • Step 20: Open worlds
    • Open worlds 1: the knowledge (archetypes in data/archetypes/world.json)
    • Open worlds 2: terrain and sea
    • Open worlds 3: a lake
    • Rivers that run downhill
    • Collision data (HeightMapShape3D heights) written next to the tile
    • Scatter points for plants and settlements
    • Checks for streaming budgets