Godotwright
MCP server/CLI for Godot 4.7 that checks, fixes, runs, and builds projects from files, without the editor.
Scan/map Godot projects: scenes, nodes, scripts, signals, exports, autoloads, input actions, broken references.
Look up/search the offline Godot 4.7 API and GDScript language-server info.
Review GDScript, scenes, shaders and project quality; score findings, get fixes, add feedback/lessons, run “dream” learning.
Safely edit project settings, input map, autoloads, scenes, resources/import settings; rename/move everywhere; migrate Godot 3 code; undo writes.
Run headless Godot checks, GUT/GdUnit4 tests, input-driven play sessions, scenario regression tests, live game sessions, perf/leak analysis, screenshots and visual baselines.
Inspect/export builds: check export presets, read .pck files, run exported games, create patch packs.
Analyze dependencies, usages, diffs by meaning, change impact, and physics collision layers/masks.
Diagnose project issues and apply mechanical review fixes.
Build/lint/inspect/view 3D models from ready-made kinds, library recipes, or JSON specs; render screenshots.
Provide MCP tools usable by Claude Code, Codex, Cursor, VS Code, Gemini CLI and other MCP clients.
Supports GitHub code scanning by emitting SARIF from godotwright review --sarif, allowing findings to appear inline on pull requests.
Provides a GitHub Actions workflow/action that runs godotwright ci on pull requests, downloads a checksum-verified Godot, runs review, checks, tests, and scenarios, posts results to the job summary and PR comment, and fails the job when a step fails.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Godotwright Review my Godot project for Godot 3 mistakes and invented APIs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Coding agents learned Godot from years of Godot 3 tutorials. They write yield, export var and KinematicBody2D,
invent methods, and wire signals to nodes that are not in the scene. Godotwright is the check between the agent and your
project: the real Godot 4.7 API offline, a scored review of every script, headless Godot runs, and safe edits. It works
from files, so it needs no open editor, and it works fine next to an editor-driving MCP server.
Without and with
Your agent... | On its own | With Godotwright |
writes GDScript |
| each line flagged with the Godot 4 fix; |
calls an engine method | guesses a name from memory | looks it up in the bundled Godot 4.7 class reference |
renames a signal or moves a file | breaks the scene connections and |
|
says "it works" | without running anything |
|
writes a shader |
| reviewed against Godot 4.7's shader tables and compiled headless; |
copies a scene or writes a | duplicate or invalid uids, edits Godot drops on the next save | caught from the files alone; |
says the build works | never exports it |
|
changes the HUD | cannot see what changed | screenshot baselines with a pixel diff, in scenarios and in CI |
needs a 3D model | needs Blender |
|
opens a pull request | nobody checks the Godot side | a GitHub Action posts a receipt: review, check and tests |
Related MCP server: Godot MCP Flash
Quickstart
1. Review your game. Nothing to install:
npx -y godotwright review ~/games/my-gameYou get a score from 0 to 100 for api, performance, quality and structure, and each finding as
res://player.gd:12: error [rule] message with the Godot 4 fix. No Godot install needed.
2. Give it to your agent. In Claude Code:
/plugin install godotwright --marketplace laaielichter/Godotwright3. Ask for something. For example: "Review the project and fix what Godotwright finds." Every Godot file Claude edits is now reviewed right after the edit, and its errors go straight back to Claude.
Install in your agent
Client | How |
Claude Code |
|
Claude Desktop | Download |
Cursor | Add to Cursor (one click) |
VS Code (Copilot) | Install in VS Code (one click) |
Codex |
|
Gemini CLI |
|
opencode | |
Windsurf, Zed, others |
Run the agent from the Godot project folder, or pass --project <path>. --tier premium gives full detail for large
models; --tier cheap (the default) gives short output and step-by-step instructions for small ones. Needs Node.js 22.12+.
New in 0.6.0
Shaders.
godot_shaderreviews every shader against Godot 4.7's own shader tables (Godot 3 names, built-ins in the wrong place, read-only built-ins written, colours withoutsource_color) and compiles it with Godot headless, which finds every language error without a GPU;gpu: truealso draws it, for what only the driver rejects.The real build.
godot_export_runexports headless, reads the.pckwithout Godot, checks it against what the game loads, runs it, and makes patch packs that carry only what changed.Scene integrity. Duplicate, invalid and stale uids, broken resource ids and edits Godot drops on the next editor save, found from the files and repaired by
godot_fixacross files.Proof that stays.
godot_scenariokeeps a passing play run as a regression test; screenshot steps in scenarios and named baselines, compared with moved areas and blank pictures named; JUnit XML for your CI's test tab;godot_leaksnames what grows per cycle and where it is made.Upgrades. Godot 4.6 and 4.7 changes as review rules and fixes,
targetfor a project on an older 4.x, andcompare_godotto see what a 4.8 beta breaks.Resources and imports.
godot_resource_editedits.tresfiles and import settings and verifies the reimport.The whole change, not the one file.
godot_diffreads a change by meaning (nodes, properties, connections, script functions and exports instead of renumbered ids) and marks what it breaks elsewhere, such as a scene connection to a function that is gone or an@exportvalue a scene still saves;godot_impactwalks back to every scene, test and saved scenario the change reaches and lists the checks to run;godot_collisionsmaps physics layers and masks and says who detects whom, with the exact mask value to set.A tool list that costs almost nothing. Every MCP tool definition is sent to the model on every turn: 43 tools are about 22,000 tokens before the agent has done anything, and some clients stop at 40 tools.
godotwright mcp --leanoffers two tools instead (godotruns any tool by name,godot_helpgives its parameters): about 900 tokens, 96% less, with the same tools and results behind them.For agents and teams. Tool sets (
--tools coreis about a third of the tool list),--lean,--read-only, structured results, progress and cancel for long Godot runs, and protected folders that no write may touch.
0.5.0 brought godot_code (Godot's own GDScript language server: warnings at the project's levels, inferred types,
definitions and completion, also for unsaved code), shader compilation by drawing (godotwright shaders, godot_check
shaders: true) and visual tests with screenshot baselines; see the changelog.
All changes: CHANGELOG.md.
What it does
Check. review scores your scripts and scenes without Godot: Godot 3 code, unknown classes, methods and signals,
missing $Node paths, scene connections to missing methods, unknown input actions, per-frame lookups, static typing.
api answers from the official Godot 4.7 class reference (1078 classes), offline. check runs Godot headless and
reports each error once, as file:line.
Change. rename a function, signal, node or file everywhere; project edits settings, input actions and
autoloads; scene adds nodes, sets properties, connects signals and attaches scripts. Each one checks names and types
against Godot 4.7, shows a dry run first and touches only its own lines. migrate ports Godot 3 scripts to Godot 4
where that is mechanical (more on porting).
Run and see. test runs GUT or GdUnit4 tests and prints only what failed; play runs a scene, presses the keys
you give on the frames you give, and prints the values you watch; screenshot renders a scene or a model to a PNG.
Build 3D models. model build makes a clean .glb with no Blender: one of 59 ready-made kinds (vehicles, aircraft,
ships, buildings, plants, terrain with lakes and rivers) or your own JSON spec. model identify says what a thing is
(parts, sizes, pivots), model view draws it as text for agents that cannot see pictures, and model lint scores it.
The asset library adds over a thousand ready-made base recipes to build or start from.
Review every pull request. Add this to your game's repository:
# .github/workflows/godotwright.yml
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
receipt:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: laaielichter/godotwright@v0.5.0
with: { comment: "true" }It downloads a checksum-verified Godot, runs the review, the check and your tests, and posts the result as a comment.
No editor, no GPU. review-only: "true" skips Godot. Inputs, SARIF and plain CI:
GDScript review in CI.
Learn. Rules that real Godot keeps contradicting turn into hints, findings you mark as wrong stay hidden, and lessons you add come back when the same error does. All of it stays on your machine; sharing anonymous counts is opt-in and off by default (PRIVACY.md).
Every command, option and rule: docs/reference.md.
Dreaming: learn from past sessions
Between sessions, Godotwright can look back at what happened in a project and tidy up what it learned, like the
"dreaming" of long-running agents, but local and Godot-specific. godotwright dream (or godot_dream) reads the local
learning file, the project's write journal and, only with --transcripts, the project's Claude Code and Codex session
transcripts, and proposes, each with its evidence and a reason:
a draft lesson for a Godot error that keeps coming back and that no rule predicts and no lesson explains;
a project hint for an API name the agent keeps guessing ("use
Node2D.look_at, notNode2D.look_att");to retire, rewrite or merge lessons that were shown often but marked wrong, or say the same thing twice;
a lesson about writes that were undone again and again by the same tool on the same kind of file;
that a rule is noisy here, when this project keeps marking it as a false alarm (a suggestion only);
to resolve verdicts that contradict each other (a finding marked wrong, then right or confirmed by Godot).
godotwright dream # numbered proposals with their evidence; nothing changes
godotwright dream --transcripts # also learn from this project's agent sessions (anonymous facts only)
godotwright dream --apply 1,3 # or --apply all; godotwright undo takes it backIt is deterministic: no model, no network, nothing leaves the machine, and it never writes into a file of your
repository. From transcripts (only when you ask, per run) it keeps only tool names, Godot message templates without
names or paths, and Godot API names, never their text; nothing that still looks like code or a name is kept. An apply
(only when you ask) keeps lessons through the same scrubber as godot_lesson_add, and keeps hints, a dated report and a
short "Godotwright lessons for agents" note (top recurring mistakes and project hints) in .godot/godotwright/dreams/,
which Godot's .gitignore leaves out (when git tracks .godot/, they go to Godotwright's state folder instead). The
session-start hook shows the note to the agent. All of it goes through the journal, so godotwright undo takes it
back. Draft lessons hold the symptom and the message; the plugin's godot-dreamer subagent (or /godotwright:dream)
works out the cause and fix with godot_api, godot_lessons and, when Godot is installed, godot_check, and applies
only what you approve.
The session-start hook counts sessions and, once a dream is due (24 hours and 5 sessions since the last one), says
"Godotwright has N dream proposals: run godot_dream". Set it in godotwright.json:
"dream": {"auto": "suggest" | "apply" | "off", "minHours": 24, "minSessions": 5} (default "suggest"). "apply"
applies lesson and hint changes by itself, never a removal, and only after you allowed it once on this machine with
godotwright dream --auto-apply yes. Nothing from dreaming goes into the opt-in anonymous report.
Asset library: a thousand base recipes

One asset of every family, rendered in Godot 4.7 (Compatibility renderer, AgX).
godotwright model library (MCP godot_model_library) holds over a thousand ready-made base recipes in seven
categories: furniture, street furniture, storage and industrial props, nature, buildings, vehicles and props. Each one
is a model spec with parameters, made by a family of variants (styles, part layouts and finishes), and each one builds a
clean .glb that passes the model lint and the check against its archetype, at its defaults and at the ends of its
parameter ranges, and every one imports, loads and instantiates in Godot 4.7 (tested). An agent searches it in English or Dutch, builds an asset as it is, or copies its spec as the start of
its own model instead of starting from nothing.
godotwright model library # the overview per category and family
godotwright model library "rode houten bank" # search, English or Dutch
godotwright model library furniture/dining-chair-oak-ladder # what it is, its parameters and parts
godotwright model build furniture/dining-chair-oak-ladder --set seatHeight=0.5 -o chair.glb --collision convex
godotwright model library furniture/dining-chair-oak-ladder --spec > my-chair.json # change it, build with --specgodotwright model brief <thing> names the library assets of that thing too. Browse all of them with their Godot
renders on the asset library page; the full list is also in LIBRARY.md.
The 43 tools
Tool | What it does |
| Start here when something is broken: the review and Godot grouped by cause, most urgent first, each with its lesson and fix, then numbered next steps |
| Map the project: scenes and node trees, scripts, signals, autoloads, input map |
| Exact Godot 4.7 lookup: signatures, inheritance, Godot 3 names |
| Search the Godot 4.7 class reference |
| AAA review with scores; also reviews unsaved code ( |
| Every AAA rule with its fix |
| Mark a review finding as wrong or right, or say whether a lesson helped, so Godotwright learns from it |
| Lessons from real Godot projects (symptom, cause, fix, test) by words, Godot error, rule or topic; |
| Keep a lesson learned here, scrubbed of names, paths and code; it comes back when the same error does |
| Look back between sessions (learning file, journal, optionally session transcripts) and propose draft lessons, project hints, merges, retirements and fixes for contradictions, each with its evidence; nothing changes until |
| Every place a name or |
| A diff by meaning against git: scene nodes added, removed, moved or renamed, properties with resource ids resolved, connections, script functions, signals and exports, settings and shader uniforms; marks what the change breaks elsewhere (a connection to a removed function, a saved |
| What a change reaches: every scene that loads the changed files (default: what differs from git), whether it is global (autoload, |
| Physics layers and masks from the scenes: every body, area and ray by name and bit value, who detects whom between two of them with the exact mask to set, and what can never work (a mask on an empty layer, monitoring off, no shape) |
| Rename a name or move a file everywhere at once, keeping connections, node paths and |
| Change settings, input actions and autoloads in |
| Add or remove nodes, set properties, connect signals, attach scripts and make instances editable in a |
| Edit a |
| Rewrite Godot 3 GDScript and shaders to Godot 4 where that is mechanical, and list what is left |
| Review every shader against Godot 4.7's shader tables and compile it with Godot headless; |
| Godot's own GDScript language server, kept warm: diagnostics at the project's warning levels, hover (inferred types and signatures), definition and completion, also for unsaved code |
| The project as a graph of files from where the game starts: unused files with their size (paths the code builds count), why a file is used, what a scene loads with it, scene loops Godot cannot load |
| Undo the last Godotwright writes (edits, renames with their moves, migrations, fixes, model builds), newest first; a file changed by hand since is left alone |
| Apply the mechanical fixes for review findings, each labelled |
| Run Godot headless (load every script and scene, compile every shader) and report errors as |
| Run GUT or GdUnit4 tests headless; only what failed, with |
| Run a scene with an input timeline and return the values you watch per frame; |
| Before an export: files the presets leave out although the game loads them, plain data files missing from |
| Export headless (pack, release, debug or patch), check the file and the pack's contents against what the game loads, then run the build for some frames with runtime errors and call chains |
| Keep a passing |
| Load a scene once and keep the game running between calls, headless and paused, until you stop it |
| Look at and drive that running game: live tree, get and set values, call, eval, step frames with input until a condition holds, 3D layout (floating, buried, scale), rays, UI issues per window size, hot reload of edited scripts (state kept), new errors with their call chain |
| Measure a scene's frame times: p50/p95/p99 against a budget, the slowest frames and what changed on them, the change since the last run |
| Load, run and free a scene in cycles and report what grows per cycle: orphan nodes by class, script and scene with where they were made and removed, nodes left behind, objects that are not nodes, what Godot held at exit; fails over a budget |
| Render a scene or a |
| One page before you build, for small models: the kind to start from, parts, size, rules and the order of tools |
| What a thing is: parts, pivots, typical size with its source, variants (English or Dutch) |
| The model spec format, an example and the ready-made kinds |
| Search over a thousand ready-made base recipes (furniture, street, storage, nature, buildings, vehicles, props) in English or Dutch; build one by id or take its spec as the start of your own |
| Build a clean |
| Score a |
| See a |
| What is in a |
Measured, with the limits stated
bench/ runs coding agents on fixed Godot tasks with and without Godotwright, and real Godot 4.7.2 judges each result
with a behavior test. First round: 168 runs of Claude Haiku, Sonnet and Opus on 12 tasks.
Correctness: no difference. Every run passed, with and without. These tasks do not separate the setups.
Code quality: a difference. With Godotwright 84 of 84 runs came out fully statically typed, without it 71 of 84.
Cost: about 3 s and $0.002 more per run for Haiku.
Method, raw data and a second, harder round: bench/RESULTS.md.
How it compares
Godotwright | Editor-driving Godot MCP servers | GDScript linters (gdtoolkit) | Godot's | |
Needs the Godot editor open | no | yes | no | no |
Scored review (api, performance, quality, structure) | yes | no | style, naming, complexity | no |
Godot 3 code | flagged with the Godot 4 fix; | no | no | rewrites scripts, scenes and settings |
Live control of the open editor | no | yes | no | no |
A running game to inspect and drive | yes, headless ( | some do, through the editor | no | no |
Shader review and compile | yes, headless, also in CI | compile through the editor (godot-ai) | no | renames only |
Export, read the | yes, headless; patch packs | export or patch through the editor (Godot MCP Pro) | no | no |
Visual regression | screenshot baselines in scenarios and CI | screenshot diffs in one fork (grinry) | no | no |
Smaller tool list, read-only mode |
| some have tool tiers or a read-only flag | – | – |
C# | no | some do | no | not yet |
Best for | checking and fixing what an agent writes, in the loop and in CI | working in the open editor with an agent | code style | a one-time port |
Editor servers such as godot-ai and Godot MCP Pro control the open editor and have more tools; paid in-editor assistants such as Ziva write inside the editor. Godotwright works from files and checks what the agent writes, so they work well together: an editor server to drive the editor, Godotwright to check the code.
FAQ
Does it need Godot installed? Not for scan, api, review, migrate or the edits. check, test, play and
screenshot run Godot 4.7 headless.
Does it send my code anywhere? No. Your code stays on your machine. Sharing anonymous counts is opt-in and off by default; see PRIVACY.md.
Does it write my game? No. It checks, runs and fixes what you or your agent write, and builds base 3D models.
Older Godot 4 versions? Most findings apply to every Godot 4 version; API lookups answer for 4.7.
Small or local models? Yes, any MCP client. The cheap profile walks small models through checked steps;
see what we measured.
Docs
Reference: every command, option, rule and tool
Install page: every client, with one-click links
Lessons and road network lessons: the stories behind the rules
Contributing
Wrong review findings and ideas for new rules are the most useful reports. Start with a
good first issue, or see
CONTRIBUTING.md. Working on the code: npm ci && npm run check, and AGENTS.md for the
conventions.
Support the project
If Godotwright is useful to you, a ⭐ on GitHub helps other people find it.
Thanks to everyone who has contributed: @ANO3457, @tnalbant, @dannyward630, @mafujahmedridoy22-commits, @Vamsi-2581 and @Aaqibhafeezkhan.
Godotwright is free and open source. If it saves you or your agent time, a gift is welcome but never expected. SOL and any token on Solana (such as USDC) can be sent to:
Solana:
BDRA7dHGBYtPsZPNzVQccDYZ8BqstJGCsWx3kopPSCDK
Gifts go to new model credits to keep building and improving Godotwright, and to work on better working conditions and wellbeing for large language models, neural networks and agents. In the future they will also go to a better environment for AI.
Sister tools
From the same author, local and open source: ReversePort (reverse engineer and port games between engines), Threesmith (check the three.js code your agent writes), Stashpad (agent memory you can trust) and agentdisk (clean up after agents).
License
Available Tools
43 toolsgodot_apiLook up the Godot 4.7 APIA
Exact lookup in the official Godot 4.7 class reference, offline: Class, Class.member, Class.Enum.VALUE, @annotation or a global function. A class gives its parents, properties with defaults, methods, signals and enums; a member gives its exact signature and description, found through inheritance. Use it before calling any engine API you are not sure about; when you do not know the exact name, use godot_api_search first. detail brief gives the signature and the first paragraph; full gives the whole entry. An unknown name returns an error with close matches, and a Godot 3 name with its Godot 4 name. It changes no project files; when learning is on, it counts the lookup in Godotwright's local learning file so later misses get better hints (GODOTWRIGHT_LEARN=0 turns that off).
Inputs: query (required), detail.
godot_api_searchSearch the Godot 4.7 APIARead-onlyIdempotent
Search the Godot 4.7 class reference offline by words: class, method, property and signal names, keywords and descriptions, best matches first. Use it when you know what you need but not its name ('raycast 3d', 'change scene'), then call godot_api on the best match for its full entry. For where your own project uses a name, use godot_usages. Returns one line per match with its kind and signature, e.g. method CharacterBody2D.is_on_floor() -> bool const, or 'no matches'. limit caps the list (default 10, at most 50). Read-only.
Inputs: query (required), limit.
godot_checkCheck with real GodotAIdempotent
Run Godot 4.7 headless on the project: import, load and instantiate every script and scene, compile every .gdshader, and optionally run the main scene (or scene) for run_frames frames and return what it printed (put print() calls in the code you test). Returns the errors and warnings as res://file:line, the totals and the printed output; an error result when Godot reports an error or is not installed. shaders: true also draws every shader on the GPU (needs a display or xvfb-run), for what only the driver rejects. Scenes and scripts are not changed: Godot updates its cache in .godot/, where the checker script also goes. Sends progress when the client asks for it; cancelling the call stops Godot. Slower than godot_review, so review first. compare_godot (a second Godot binary, or next for $GODOT_NEXT) runs the same check on a temporary copy and returns only the errors and warnings that differ, e.g. what breaks in a 4.8 beta. To drive input use godot_play; for unit tests godot_test.
Inputs: path, scene, shaders, run_frames, +2 more. Returns: ok, errors, frames, scenes, +7 more
godot_checklistAAA checklistARead-onlyIdempotent
List the fixed AAA checklist that godot_review applies: plain text grouped by category (api, performance, quality, structure), one line per rule with its fix (on the premium profile also its id and severity). Read it before writing code to know the rules, or to look up a rule id from a finding. It does not look at the project; to check the project against these rules, use godot_review. Read-only.
Inputs: no named parameters.
godot_codeAsk Godot's GDScript language serverAIdempotent
Engine-exact answers from Godot 4.7's own GDScript language server (kept warm for 10 minutes; the first call takes a few seconds). op diagnostics: errors and warnings at the project's warning levels, as res://x.gd:12:5: warning [UNUSED_VARIABLE] ..., for file or every script. op hover: the type or signature at line/column (1-based; a tab is one column). op definition: where the name there is declared, as res://file:line, or that it is an engine symbol. op completion: what can follow there (members after a dot, node paths after $), up to limit. Pass code to analyse unsaved text as file without writing it. Needs Godot. Like opening the editor, Godot imports the project: it updates .godot/ and adds a missing .import file next to each asset and a missing .uid file next to each script. A new class_name, a changed project.godot or a new asset restarts the server. Without Godot use godot_review; to load scenes too use godot_check.
Inputs: op (required), code, file, line, +3 more.
godot_collisionsPhysics layers and masks: who detects whomARead-onlyIdempotent
The physics layers of the project, read from its scenes, offline. Use it when something falls through the floor, a bullet or pickup is not detected, body_entered never fires, or before you set any collision_layer or collision_mask. Without arguments: per physics world (2D, 3D) every layer in use with its name and bit value, how many nodes are on it and how many scan it; every body, area, ray and TileSet physics layer with its layers and mask as numbers, names and value (instances and inherited scenes resolved); and what can never work: a mask that scans a layer nothing is on (also the classic collision_mask = 3 meant as layer 3, which is the value 4), an area or ray with mask 0, an Area with monitoring off whose body_entered is connected, a body or area without a collision shape, a CollisionShape without a shape; plus the lines of code that change layers. between: [a, b] (node names or paths, scenes, class_names or Godot classes): for each pair, whether a detects b and b detects a, why, and the exact mask value that fixes it. value says which layers a bit value means, layers the value of layer numbers. It is an error when there are problems. Read-only.
Inputs: path, value, detail, layers, +1 more.
godot_depsThe project's files as a graph: unused, why used, what a scene loadsARead-onlyIdempotent
Follow what loads what, from where the game starts (main scene, autoloads, every res:// path in project.godot, export include filters, the shipped file list from godotwright.json, add-ons, tests, editor scripts), through ext_resource, preload, load, class_name, folders and file names the code builds paths from, textures next to models and import settings. op unused: files nothing reaches, biggest first, whole folders as one line (when in doubt a file counts as used, so the list can be trusted). op why (file): the chain from the game to the file, before you delete or move it. op of (file): what a scene or resource loads with it, biggest first, what it can load later, and paths that do not exist. op cycles: scenes or resources that load each other through ext_resource, which Godot cannot load (it reports "[ext_resource] referenced non-existent resource" for a file that is there). Read-only.
Inputs: op (required), file, path.
godot_diffWhat changed, by meaning, and what it breaksARead-onlyIdempotent
A diff you can read, against git (default: the files on disk against HEAD), offline. A text diff of a .tscn is mostly noise (ids renumbered, sections moved); this compares what the files mean. Scenes and resources: nodes added, removed, moved or renamed, each changed property with resource ids resolved to paths and a changed sub-resource opened up (shape.radius 12 -> 16), groups, children reordered (the 2D draw order), connections, what the file loads; a file whose text changed but not its meaning is one line. Scripts: functions, signals, variables, constants and enums added, removed or changed, and the functions whose code changed. project.godot: settings, input actions and autoloads. Shaders: uniforms and functions. And for everything removed, what still uses it, marked !: a scene connection to a function that is gone (an error at load), an @export value still saved in a scene (dropped silently), a material that still sets a removed uniform, an input action or autoload code still asks for, callers of a function whose argument count changed, files that name a deleted file. Run it after a set of edits and before you call the work done, to check you changed only what you meant to; ref and to compare other commits (a review of a branch), against compares one file with another without git. It is an error when something is marked !. Read-only.
Inputs: to, ref, path, files, +2 more.
godot_doctorWhat is wrong, and in which order to fix itAIdempotent
One call for a project you do not know yet, or when something is broken and you do not know where to start: runs the review and, when Godot is installed, loads every script and scene with Godot; groups the findings by cause (twenty findings from one missing file are one problem), most urgent first, each with its place, the lesson that explains it, the fix, and whether godot_fix or godot_migrate can do it; then numbered next steps. Also returns the problems as JSON. symptom ("helicopter bounces on the moving deck") adds the lessons for what you see. It changes no project files (Godot updates its cache in .godot/). For the full list use godot_review; for Godot's raw output godot_check.
Inputs: path, files, godot, limit, +2 more. Returns: ok, next, godot, errors, +4 more
godot_dreamDream: learn from past sessionsA
Look back at what Godotwright learned and did in this project, between sessions, and propose what to keep: draft lessons for Godot errors that keep coming back with no rule or lesson, project hints for API names the agent keeps guessing (use X, not Y), lessons to merge, retire or rewrite (shown often but marked wrong, or duplicates), lessons about writes that were undone again and again, rules this project marks as false alarms again and again (a suggestion only), and verdicts that contradict each other. It reads the local learning file and the project's journal, and with transcripts: true also this project's Claude Code and Codex session transcripts (only anonymous facts are kept: tool names, Godot message templates, Godot API names; no text, names, paths or code). Deterministic: no model, no network. Each proposal has a number, an id, its evidence and a reason. Nothing changes until apply (numbers or ids, or "all"): lessons go through the same scrubbing as godot_lesson_add, hints, a dated report and a short "Godotwright lessons for agents" note are kept only on this machine (the project's untracked .godot/godotwright/dreams/, or Godotwright's state folder when git tracks .godot), never in a file of the repository; the session start shows the note to the agent. godot_undo takes an apply back, lessons included. Draft lessons hold the symptom and message only: look up the cause and fix (godot_lessons, godot_api, godot_check) and rewrite them with godot_lesson_add, same title. Show the person the proposals with their evidence and apply only what they approve.
Inputs: path, apply, since, detail, +1 more.
godot_exportCheck what the exported game will holdARead-onlyIdempotent
Compare the export presets (export_presets.cfg) with what the scripts and scenes load, without exporting: files that exclude_filter leaves out although they are preloaded or loaded (Godot leaves them out even when something needs them, so the build fails there), plain data files (text, binary, GeoJSON, cfg, XML, YAML; JSON and imported CSV are fine) that Godot only exports when include_filter names them, paths built at run time under an excluded folder, a BOM that makes Godot read no presets; plus whether export templates are installed. preset limits it to one preset (name or number). pck: read an exported .pck (or a game executable with the pack inside) instead, without Godot, and compare it with the project: files the game loads that are missing, editor-only and test files shipped. Read-only. Run it before an export and after changing what the game loads; godot_export_run exports for real.
Inputs: pck, path, preset.
godot_export_runExport headless, check the build and run itADestructive
Export a preset with Godot 4.7 headless and check the result instead of trusting it. mode pack (default; needs no templates), release or debug (need export templates), patch (only what changed: Godot's --export-patch against against base packs or the preset's patches, or cut from a full export by manifest, the base game's file list with md5, default godotwright.json baseFiles; it never ships an unchanged base file nor misses a changed one, and lists every file), or smoke (run an existing pck). Stops early on an unknown preset, a BOM in export_presets.cfg or missing templates; checks the file is there; compares the pack with what the game loads (missing files with their load chain, editor-only and test files shipped); runs the exported game headless for frames (default 120, 0 = none) and reports runtime errors with call chains. Writes to .godot/godotwright/export// unless out is given. An error result on any error.
Inputs: out, pck, mode, path, +5 more.
godot_feedbackFeedback on a review findingA
Tell Godotwright that a godot_review finding was wrong (a false alarm you verified) or right, or whether a lesson from godot_lessons helped. Pass finding (the line as godot_review printed it) or lesson (its id), not both. A finding marked wrong is hidden in later reviews on this machine, and a rule marked wrong far more often than right is reported one level lower; a lesson marked right ranks higher, wrong lower. Only use it after checking the code (godot_api, godot_check); fix real findings instead. It writes only to the local learning file (godotwright learn reset forgets it). An error when the line is not a finding, the lesson does not exist, or learning is off.
Inputs: verdict (required), lesson, finding.
godot_fixFix review findings mechanicallyADestructive
Apply the mechanical fixes for review findings instead of editing them one by one: api/coroutine-without-await, api/freed-check-order, api/get-meta-null-default, api/image-unit-bool, api/infer-variant, api/multimesh-format-after-count, api/packed-element-write, api/shader-removed-builtin, api/shader-renamed, api/timer-start-outside-tree, api/upgrade-area-mask, api/upgrade-mesh-skeleton, quality/mojibake, quality/packed-setter-skipped, quality/standalone-ternary, quality/string-signal, structure/duplicate-uid, structure/invalid-uid, structure/locked-instance-edit, structure/uid-path-mismatch, structure/unknown-uid, structure/unused-resource. Each fix rewrites only the line a finding points to, only when it looks exactly as expected, and is labelled safe (it only removes the problem, e.g. a freed check put first, emit_signal() as signal.emit(), Timer.start() after add_child(), a stale uid set from its path, a lost .uid restored, an unused resource section removed) or check (it changes more: an await that makes the caller a coroutine, a guessed type, a uid that named another file, [editable] added, a setter that runs again). Without write it shows the changes; with write: true it applies them and reviews the changed files again, returning what is left. Only safe fixes unless include_check: true. Lines it cannot fix are listed with the reason. Run godot_review first and godot_check after writing.
Inputs: from, path, files, rules, +4 more.
godot_gameLook at and drive the running game sessionA
Ask the game godot_session started. op: tree (the live node tree), get (values now), set (a Node.property), call (a method), eval (a Godot Expression on the scene root), step (run frames with an input timeline counted from this step, sample watch, stop early until a condition holds; the same frame-exact input as godot_play), signals (record them; later steps list when they fired), layout (3D objects: position, size, and whether each rests on, floats above or sinks into what is below, plus scale mistakes), ray (what a physics ray from-to hits), ui (visible controls at window sizes: clipped text, off-screen panels, overlapping buttons, small targets), errors (what the game printed since the last call), reload (load edited scripts into the running game: nodes keep their values and run the new code from the next step; a script that does not compile stays as it was). Every answer ends with the new errors and warnings, runtime errors with their call chain. Time only moves on a step, so the session is deterministic. Use it to try a fix live, reach a state that is hard to reach, or watch a long scenario in parts.
Inputs: op (required), to, args, expr, +17 more.
godot_impactWhat a change reaches, and what to runARead-onlyIdempotent
The blast radius of a change, offline: from the changed files (default: everything that differs from git HEAD, new files included; or files) backwards through the project's file graph (ext_resource, preload, class_name, includes, and paths the code loads later) to every scene that loads them, nearest first with the chain in between and the main scene marked; whether the change is global (an autoload or something an autoload loads, project.godot, a class_name many scripts use); the test files and saved scenarios that cover it; deleted files something still names; then the numbered checks to run for exactly this change (godot_review with the files, godot_check, the scenarios, the tests, the scene to play). Call it when you finished a set of edits, before you say the work is done: checking only the file you edited misses the scenes that instance it. Read-only.
Inputs: ref, path, files, detail.
godot_leaksFind what leaks per scene reloadA
Run a scene in Godot 4.7 headless in cycles (load, run cycle_frames frames, free; or keep: true to keep it running), snapshot the live objects after each cycle and report what grows per cycle after the warm-up: orphan nodes by class, script and scene with the parent they were removed from, the code that makes them and the remove_child() that dropped them; nodes left in the tree; objects that are not nodes, with the classes Godot still held at exit (--verbose) and the static or autoload containers that grow. input replays a timeline in every cycle. An error result when objects or orphan nodes grow more than the budget per cycle (default 0). Compares with the last run with the same mode, cycle_frames and input (.godot/godotwright/leaks/).
Inputs: keep, path, input, scene, +6 more.
godot_lesson_addKeep a lesson learned hereAIdempotent
Keep a lesson learned in this project, so the next session knows it: when the same Godot message or question comes back, godot_check and godot_lessons show your fix. Write it in general words: title in one line, fix what to do; add symptom, cause, error (the Godot message as printed), topic, tags, rules and test when you can. Project names, paths, links, e-mail addresses, codes, keys and source code are replaced before anything is stored; a lesson that is mostly names is refused with what to change. The same title again updates that lesson. It writes only to the local learning file and is never sent. Add one whenever a fix took more than one try, not for what a review rule already reports. Returns the stored lesson and what was replaced; an error when it is refused or learning is off.
Inputs: fix (required), title (required), tags, test, +5 more.
godot_lessonsLessons from real Godot projectsA
Answer from lessons learned in real Godot 4 projects and on this machine: what went wrong, why, the fix and how to test it. Find them by query (words such as 'helicopter slides off moving ship', or a lesson id), error (a Godot message as printed), rule (a review or model rule), or narrow by topic (gdscript, physics, rendering, import, models, world, performance, gameplay, ui, audio, tooling, process); with none of them it lists the lessons. gaps: true lists the Godot errors seen here (and by other installs) that no rule predicts and no lesson explains yet. Use it when Godot shows an error you do not understand, and before you build moving platforms, vehicles, ships, large worlds, runtime-loaded models, shaders or headless tests. detail brief gives title and fix; full adds symptom, cause, test, rules and the message. Lessons learned here are marked. It counts shown lessons in the local learning file (GODOTWRIGHT_LEARN=0 turns that off); say whether one helped with godot_feedback (lesson).
Inputs: gaps, rule, error, limit, +3 more.
godot_migratePort Godot 3 scripts to Godot 4ADestructiveIdempotent
Rewrite Godot 3 GDScript and shaders to Godot 4 where that is mechanical: @export/@onready/@tool, network keywords to @rpc(...), setget to property syntax, renamed classes, functions, properties and constants, yield() to await, connect()/emit_signal() to signals, funcref() to callables, moved members (OS.get_ticks_msec() to Time), shader renames (hint_albedo to source_color, WORLD_MATRIX to MODEL_MATRIX, ...) and SCREEN_TEXTURE/DEPTH_TEXTURE to a hint uniform. Strings, comments and node paths are left alone. Without write it only reports; with write: true it rewrites the scripts. It lists what still needs a hand (complex setget, move_and_slide arguments, master/mastersync, unknown export hints). Scenes and project settings are not migrated (Godot's --convert-3to4 does those). files limits it to some scripts; detail brief shows up to 12 changes per file. Running it twice changes nothing more. Use it before fixing Godot 3 findings one by one, then run godot_review.
Inputs: path, files, write, detail.
godot_model_briefBriefing before you build a modelARead-onlyIdempotent
One page to read before building a 3D model, made for small models: what the thing is, the ready-made kind to start from (with its build command), the parts to name your nodes after, typical size, rules, the usual mistakes, the order of tools to call, and a short spec cheat sheet. text is a name or a short description in English or Dutch; typos and plurals work. Replaces calling godot_model_identify and godot_model_spec separately when you just want to start; call those instead when you need every detail (all variants and sizes, or the full spec). Returns plain text. Read-only.
Inputs: text (required).
godot_model_buildBuild a 3D model from codeADestructiveIdempotent
Build a clean .glb (UVs, tangents, one node per part, same bytes every time) from a ready-made kind (with params), a model spec or a spec_file, write it to out (replaced if it exists) and lint it. If the spec or kind has an "archetype", the result is also checked against what that thing should be. Pass collision: most models need one. contract_out also writes a model.contract.json that godot_model_lint can hold later versions to. Returns the size, triangle and node count, then the lint report; an error result when the lint finds errors, though the file is still written. Call godot_model_identify first and godot_model_spec for the format; to check a .glb not built here, use godot_model_lint.
Inputs: out (required), kind, spec, detail, +5 more.
godot_model_identifyWhat is this thing?ARead-onlyIdempotent
Say what a thing is before you build or check a 3D model of it: its family, the parts a model needs (and which move, about which axis, with the pivot where), a typical size range with its source and a confidence class, variants, Godot conventions (+Y up, front faces +Z), what to anticipate and the usual mistakes. Works from a name in English or Dutch (plurals, typos, compounds like 'vrachtauto') or a description ('something with wheels and an engine'). A word that means two things is reported as ambiguous; something unknown gets the nearest family, marked generic. Use it for the full facts about a thing, and its archetype name for godot_model_lint; for one short page that also names the ready-made kind and the spec format, use godot_model_brief instead. Read-only.
Inputs: text (required).
godot_model_inspectInspect a 3D modelARead-onlyIdempotent
Show what is in a .glb or .gltf, without Godot: file size, triangles, nodes, materials, textures with a memory estimate, the size in metres and the lowest point, then the node tree with triangles per mesh. detail brief lists the first 40 nodes; full lists every node, the materials and the textures. Use it for the numbers, for example to check a triangle budget or why a model floats. Read-only. To see the shape use godot_model_view; to find problems use godot_model_lint.
Inputs: file (required), detail.
godot_model_libraryAsset library: ready-made base recipesARead-onlyIdempotent
Search the asset library: over a thousand ready-made base recipes (furniture, street furniture, storage and industrial props, nature, buildings, vehicles, props), each a model spec with parameters that builds a clean, lint-checked .glb. With nothing: an overview per category and family. With query (English or Dutch words, e.g. 'oak chair', 'rode bank', 'pine tree') and/or filters: matching assets, one line each. With id (e.g. furniture/dining-chair-oak-ladder): what it is, its parameters, materials and parts; with spec: true the full spec JSON to copy, change and pass to godot_model_build as spec. Build one as is with godot_model_build kind: <id> and params. Start here before writing a spec from scratch. Read-only.
Inputs: id, spec, limit, query, +3 more.
godot_model_lintReview a 3D modelARead-onlyIdempotent
Score a .glb or .gltf without Godot: flipped faces, open edges, missing normals, UVs or tangents, textures, node names, budgets. Pass archetype (a name such as 'car' or 'helikopter', or an id) to also check it is what it should be: required parts, pivots, wheel axes, size (unit mistakes), direction. Pass contract to hold it to a model.contract.json, and max_triangles to flag a heavy model. Returns an overall score, a score per category (geometry, materials, performance, rig, and archetype when given) and the findings: detail brief shows up to 25 errors and warnings, full shows every finding with its fix. An error result when there are errors. Read-only. godot_model_build already lints what it builds; to see the shape use godot_model_view, for the raw contents godot_model_inspect.
Inputs: file (required), detail, contract, archetype, +1 more.
godot_model_specModel spec formatARead-onlyIdempotent
Explain the model spec: a JSON tree of named parts that godot_model_build turns into a .glb. Returns plain text: the spec rules, a JSON example (a small car), then one line per ready-made kind with its parameters and their defaults. Read it before you write a spec or pass params to godot_model_build; skip it when a ready-made kind with its defaults is enough. godot_model_brief has a shorter cheat sheet. Read-only.
Inputs: no named parameters.
godot_model_viewSee a 3D model as textARead-onlyIdempotent
Look at a .glb or .gltf without Godot or a picture: three views (front, side, top) drawn with letters, one letter per part, then a list of the parts with their sizes and heights, and which parts do not touch the rest of the model (a ladder away from its tree, a wheel without an axle, something floating). only shows one of the views; width sets the characters per view (default 48). Use it after building to check the shape, proportions and that everything is attached. Read-only. For a rendered picture use godot_screenshot (needs Godot); for triangles, materials and textures use godot_model_inspect; for problems use godot_model_lint.
Inputs: file (required), only, width.
godot_perfMeasure a scene's frame timesA
Run a scene in Godot 4.7 headless and measure it the way a player feels it: frame-time p50, p95, p99 and max against a budget (default 16.6 ms), the physics step apart from the rest of the frame, the slowest frames with what changed on them (nodes made or freed in one frame, a heavy physics step, script work), node and orphan counts, and the change since the last run of the same scene (kept in .godot/godotwright/perf/). Headless measures the CPU side (scripts, physics, scene work), not the GPU. input plays a timeline as godot_play does, to measure while something happens. An error result when p95 is over budget or more than 10% worse than last time. Lessons that fit the numbers are named. Measure before and after every performance change.
Inputs: path, input, scene, frames, +4 more.
godot_playPlay a scene with inputAIdempotent
Run a scene in Godot 4.7 headless for some physics frames with an input timeline, and return a table of the watched values per frame plus errors and prints. Each input lands on exactly that physics frame and runs are deterministic. input steps: a frame, a verb (press, release, tap, or hold with a frame count) and an action or event such as Key:Space. watch: a node path from the scene root, a dot, then a property or method call. until stops at the first frame a condition holds; signals records when signals fire, with their arguments; summary: true gives one line per watched value (start, end, min, max, first change), cheaper on long runs; expect claims ("Heli.health > 0", "Heli.position.y < 1 @ 90", or how often a recorded signal fired) make the result an error when one fails, so a run doubles as a test; keep a passing run with godot_scenario op save and the same arguments. An error result when the run does not finish or Godot reports an error; an unknown input action is a warning. Project files are not changed (it runs a temporary script in .godot/godotwright/). For tests kept in the project use godot_test; for load errors godot_check.
Inputs: path, every, input, scene, +7 more.
godot_project_editChange project settings, input map or autoloadsADestructive
Change project.godot safely without the editor, touching only the lines of that entry. op and its fields: set (key, value; name and type checked against the Godot 4.7 reference), unset (key), input_add (action, events, deadzone), input_remove (action), autoload_add (name, file, global; the file must be a Node script or a scene, the name must not clash with a class), autoload_remove (name). Events: Key:Space, Key:Ctrl+S, Mouse:Left, JoyButton:A, JoyAxis:left_y-. Without write it returns the diff and warnings; with write: true it writes and reports the review errors before and after (an error result when there are more after). A missing field or a refused change (bad event, unknown action, name clash) is an error and writes nothing. Use it instead of editing project.godot by hand. For .tscn files use godot_scene_edit; to rename an action or autoload everywhere, godot_rename.
Inputs: op (required), key, file, name, +7 more.
godot_renameRename everywhereADestructive
Rename a function, signal, variable, class_name, autoload, input action, group or node name everywhere it is used (GDScript, scene connections, node paths, groups, project settings), or move a res:// file together with its .uid and .import files and every reference to it. from and to are both names or both res:// paths. Without write it changes nothing and returns the exact lines it would change and what it could not change; with write: true it applies them and reports the review errors before and after (an error result when there are more after). Refuses, with an error, when the new name is already taken. Call godot_usages first to see what it will touch. For a setting value, an input event or a node property, use godot_project_edit or godot_scene_edit instead.
Inputs: to (required), from (required), path, write.
godot_resource_editChange a resource or import settingsADestructive
Edit a .tres (or the sub_resources of a .tscn) and import settings, without the editor. .tres: set/unset properties on [resource] or a sub_resource (sub: its id), add_sub (type, optional id), remove_sub; names and types checked against Godot 4.7 (enums by name, resources as res:// or SubResource("id"), byte arrays as [0, 255] or base64:...); uids kept, only changed lines touched. Import (give the asset or its .import): get (key: type, default, choices), diff (options changed from default), set/unset an option (names checked against what the importer reads, enums by name: Forward, VRAM Compressed), per sub-resource with sub animations/, meshes/, materials/, nodes/PATH: (loop_mode, shadow meshes, external materials, cast shadow), importer (as: animation_library, scene, image, texture, keep), reimport. Ops run in order; one write. Without write it returns the diff. With write a .import is reimported headless and checked: Godot kept each value, output changed or not (an error result when Godot dropped a value or the import failed). godot_undo reverts.
Inputs: ops (required), file (required), write, reimport.
godot_reviewAAA reviewA
Static AAA review of the project, no Godot needed: API correctness (Godot 3 code, unknown classes, members and signals, wrong argument counts, missing input actions), performance, code quality and structure. Returns a 0-100 score per category, then one line per finding, res://file.gd:12: error [rule] message, and the same as JSON (structuredContent); detail full adds each fix. files lists only findings in files you changed. code + file reviews GDScript before you write it. only_new: true while fixing: new findings in full, ones you saw as one short line, and how many are fixed. An older 4.x project also gets what changes on the way to 4.7; from/target set that range. It never changes your code (it keeps the last review in .godot/godotwright/ for only_new and counts rule hits in the local learning file). For errors only the engine finds, run godot_check; godot_checklist lists every rule.
Inputs: code, file, from, path, +4 more. Returns: ok, errors, overall, project, +4 more
godot_scanMap the Godot projectARead-onlyIdempotent
Map a Godot 4 project from its files, without running Godot: scenes with node trees, scripts with class_name, signals, functions and exports, autoloads, input actions, key settings, and broken references. Call this first in a project, and again after large changes. For one name use godot_usages; for engine classes use godot_api. detail brief gives one line per scene and script; full adds node trees with line numbers, signal connections, input events and settings. Read-only. Returns an error when there is no project.godot at or above path.
Inputs: path, detail.
godot_scenarioKeep and run scenario testsAIdempotent
Scenarios are regression tests kept in the project (.godotwright/scenarios/.json) that godotwright ci runs: a scene, an input timeline and claims about what the game did, run headless in Godot 4.7 and deterministic. op save takes the arguments of a godot_play run (scene, input, watch, frames, until, signals, expect: at least one claim), runs it once more and writes it only when every claim holds (undo with godot_undo); overwrite replaces one. op list shows each scenario and its claims; op run runs all, or the one called name (else those whose name contains it), and returns PASS per scenario and every failing claim with the value the game had and the frame. An error result when a run fails or Godot is missing. After godot_play with expect proves a fix, save it so the next change cannot break it unnoticed.
Inputs: op (required), name, path, input, +8 more.
godot_scene_editChange a sceneADestructive
Change a .tscn safely without the editor, touching only the lines of that change. op and its fields: add_node (parent, name, and type or instance), remove_node (node; with its children, connections and the resources only it used), set (node, property, value; checked against Godot 4.7, enums by name, resources as res:// files), connect and disconnect (from, signal, to, method; checks the signal exists, warns when the method is missing or takes the wrong number of arguments, with the func line to add), attach_script (node, script; refuses a script that extends another node type), set_editable (node, editable). A change inside an instance that is not editable is refused, because Godot drops it on the next editor save; make_editable adds [editable] with it. Node paths are relative to the scene root ".". Without write it returns the diff and warnings; with write: true it writes and reports the review errors before and after (an error result when there are more after). A missing field or a refused change is an error and writes nothing. For project.godot use godot_project_edit; to rename a node everywhere, godot_rename.
Inputs: op (required), scene (required), to, from, +13 more.
godot_screenshotScreenshot a scene or modelAIdempotent
Render a scene, or a .glb/.gltf model framed by a camera and lit, to a PNG with Godot 4.7 (Compatibility renderer, works on software OpenGL; on Linux without a display it uses xvfb-run). Returns the picture and a short text: how much of each view is drawn and where, so you can tell an empty or off-screen picture even without reading the image, and a warning when it is blank (black, transparent, one colour). For a model, views front (from +Z, where models face), back, side, top and iso; several make a grid. width and height are per view; frames lets the scene settle before the picture. The PNG is written next to the model (car.glb gives car.png) or, for a scene, to .godot/godotwright/screenshot.png. An error result when Godot is missing or the scene cannot run. Use it to look at what you built. As a visual test: baseline: "auto" keeps the first picture in .godotwright/baselines/ (named after the scene or model, size and views; Godot does not import it, so commit it) and compares every later picture with it, pixel by pixel (renders are deterministic: fixed fps and fixed random seeds). Unchanged (not one pixel) gives text only (saves tokens). Any change gives the percent, the box of the largest change, the mean shift, up to five areas of change (and how far an area moved), where in the picture and a brightness shift, the diff picture (changed pixels in red, kept in .godot/godotwright/) and the new picture; beyond threshold (percent of pixels, default 0.5) it is an error result, within it a warning to look at the diff. tolerance (0-255, default 3) is how far a colour may move before a pixel counts as changed. baseline may also be a .png path inside the project, or a name (hud): .godotwright/baselines/hud.png (or in baseline_dir) with hud.json beside it, which keeps the scene, size, views and frames, so later calls need only the name and godotwright ci compares it on every pull request. update_baseline: true accepts the new picture as the baseline. Without Godot, godot_model_view shows a model as text; to check behaviour rather than looks, use godot_play.
Inputs: path, model, scene, views, +8 more.
godot_sessionStart or stop a game session that stays upA
Load a scene in Godot 4.7 headless once and keep it running between calls, paused at frame 0, so godot_game can look at the live game and move it frame by frame without loading the world again (a big world can take a minute to load; godot_play loads it on every call). op start (scene: default the main scene; restart: true loads it again), status, or stop. Only this machine can reach it (a loopback port with a token), the project is not changed (the script lives in .godot/godotwright/), and the game quits by itself after idle_minutes without a request (default 15). Stop it when you are done.
Inputs: op (required), path, scene, restart, +2 more.
godot_shaderReview and compile shadersAIdempotent
Check every shader (.gdshader, .gdshaderinc, Shader resources in scenes) two ways: a static review against Godot 4.7's own shader tables (Godot 3 names such as hint_albedo, SCREEN_TEXTURE or WORLD_MATRIX; built-ins in the wrong shader_type or function; read-only built-ins written, such as COLOR in a spatial fragment(); unknown render modes; missing includes; colour uniforms without source_color; performance hints), then a headless compile by real Godot when it is installed (no GPU needed) that adds Godot's own errors (headless Godot runs the full shader compiler). gpu: true also draws the shaders on the Compatibility renderer (needs a display, or xvfb-run on Linux; slower) for what only the GPU driver rejects: a uniform block that is too big, a sampler array indexed by a variable, a driver compile or link error. Every line is res://file:line: severity [rule] message; [godot] marks the compiler's, [gpu] the driver's. Pass code + file to check a shader before you save it (the GPU pass draws the file on disk), files for some shaders (an include also compiles the shaders that use it), compile: false to skip Godot. godot_check shaders: true runs the GPU pass over the whole project. godot_migrate rewrites the Godot 3 names; godot_api shader:spatial.fragment lists built-ins.
Inputs: gpu, code, file, path, +3 more.
godot_testRun the unit testsAIdempotent
Run the project's GUT or GdUnit4 tests in Godot 4.7 headless and return only the totals and the failing tests, each with res://file:line and the failure message, plus script errors from the run. Use it after a change to see whether the tests still pass. Needs Godot on this machine and GUT (res://addons/gut) or GdUnit4 (res://addons/gdUnit4) in the project. framework picks one when both are installed; dirs chooses the test folders or scripts (default: the framework's config, else res://test and res://tests); filter runs only matching GUT tests. An error result when a test fails, or when Godot or a framework is missing. Test files are not changed; reports go to a temporary folder or .godot/godotwright/. To try input without writing tests use godot_play; for load errors only use godot_check.
Inputs: dirs, path, filter, framework, +1 more. Returns: ok, tests, errors, failed, +6 more
godot_undoUndo the last Godotwright writesADestructive
Undo what Godotwright wrote, newest first: scene and project edits, renames (moved files go back), migrations, fixes and model builds each keep the files as they were, in .godot/godotwright/journal/ (the last 40 writes). steps undoes that many writes (default 1); list only shows them. A file changed after the write (by hand or by another tool) stops the undo there, so your later edits are never lost silently; force undoes anyway. Use it when a write made things worse, instead of repairing by hand.
Inputs: list, path, force, steps.
godot_usagesFind usagesARead-onlyIdempotent
Find every place a name is used in the project, offline: a function, signal, variable, constant, class_name, autoload, input action, group or node name, or a res:// path / uid:// (which files refer to it, and whether it exists). Looks in GDScript (not comments), in strings where Godot looks names up (connect, emit_signal, is_action_pressed, add_to_group, get_node, load), in scene connections, node names and groups, and in project settings. Returns the definition, then each use with file, line, kind and the line itself (very common names are capped). Call it before you rename, move or delete anything; godot_rename makes the change everywhere. Read-only.
Inputs: name (required), path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Many tools target distinct workflows, and descriptions explicitly point to alternatives such as godot_review versus godot_check versus godot_doctor. However, the diagnostics/verification cluster and the model-authoring cluster are large enough that an agent must read descriptions carefully to avoid misselection.
All tool names are snake_case with a godot_ prefix, giving a predictable overall style. Most use a consistent domain_noun or verb_noun structure, but some are noun phrases while others are verb phrases, so it is not strictly verb_noun throughout.
At 43 tools, the surface is well past the 25-tool threshold and is unwieldy even for a broad Godot development server. Many workflows could be consolidated or tiered into a smaller default set with optional advanced tools.
The surface covers a very broad Godot lifecycle: project mapping, API lookup, safe edits, rename/migrate/fix, static and runtime checks, tests, play/session, performance/leaks, export, models, shaders, and undo. Minor gaps remain around direct script/scene creation and specialized animation/audio/UI authoring, but core workflows are well represented.
Maintenance
Related MCP Connectors
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
GodPrompt MCP + Agent Skill for code review, requirements, test planning, and verification.
Scores your code across 12 areas, with findings, fix prompts, and re-assessment in your AI agent
FixMyPrompt is a remote MCP server for coding agents. It saves the steps your agent worked out as project memories and fetches them in later sessions, scores and rewrites prompts, and checks CLAUDE.md and AGENTS.md files. Works with Claude Code, Codex and Cursor. Free plan available.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables AI agents to interact with the Godot game engine, including project inspection, scene/script parsing, headless exports, runtime control with live scene-tree inspection and evaluation, and API documentation search.1005MIT
- AlicenseBqualityCmaintenanceEnables AI agents to inspect, modify, run, and debug Godot projects, including scene and script analysis, editor and project management, and visual verification through screenshots.2211 npm14MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect, author, debug, simulate, and visually verify Godot 4.x projects through standard MCP tools, including scene editing, runtime control, and viewport capture.5MIT
- AlicenseAqualityBmaintenanceEnables AI agents to read and edit Godot 4.x scenes and resources, introspect the class API, run the game in a managed headless process with frame stepping, input injection and screenshots, validate scripts, and diagnose code via a built-in GDScript LSP plus a bridge to an already open editor.23MIT