Skip to main content
Glama

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

yield, export var, KinematicBody2D: Godot 3 habits

each line flagged with the Godot 4 fix; migrate rewrites the mechanical part

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 .uid files

rename changes code, scenes, connections and .uid files together, dry run first

says "it works"

without running anything

check, test and play run it headless and report file:line

writes a shader

hint_albedo, SCREEN_TEXTURE, ALBEDO in a 2D shader

reviewed against Godot 4.7's shader tables and compiled headless; fix renames the Godot 3 names

copies a scene or writes a .tscn by hand

duplicate or invalid uids, edits Godot drops on the next save

caught from the files alone; fix repairs uids across files, with undo

says the build works

never exports it

export run exports headless, reads the .pck, checks it against what the game loads and runs it; patch packs too

changes the HUD

cannot see what changed

screenshot baselines with a pixel diff, in scenarios and in CI

needs a 3D model

needs Blender

model build makes a clean .glb from one of 59 kinds, then lints it

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-game

You 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/Godotwright

3. 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

/plugin install godotwright --marketplace laaielichter/Godotwright (MCP server, hooks, eleven skills, eight subagents)

Claude Desktop

Download godotwright.mcpb and open it

Cursor

Add to Cursor (one click)

VS Code (Copilot)

Install in VS Code (one click)

Codex

codex mcp add godotwright -- npx -y godotwright mcp --tier premium

Gemini CLI

gemini extensions install https://github.com/laaielichter/Godotwright

opencode

Add to opencode.json

Windsurf, Zed, others

JSON for your client

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_shader reviews 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 without source_color) and compiles it with Godot headless, which finds every language error without a GPU; gpu: true also draws it, for what only the driver rejects.

  • The real build. godot_export_run exports headless, reads the .pck without 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_fix across files.

  • Proof that stays. godot_scenario keeps 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_leaks names what grows per cycle and where it is made.

  • Upgrades. Godot 4.6 and 4.7 changes as review rules and fixes, target for a project on an older 4.x, and compare_godot to see what a 4.8 beta breaks.

  • Resources and imports. godot_resource_edit edits .tres files and import settings and verifies the reimport.

  • The whole change, not the one file. godot_diff reads 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 @export value a scene still saves; godot_impact walks back to every scene, test and saved scenario the change reaches and lists the checks to run; godot_collisions maps 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 --lean offers two tools instead (godot runs any tool by name, godot_help gives its parameters): about 900 tokens, 96% less, with the same tools and results behind them.

  • For agents and teams. Tool sets (--tools core is 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, not Node2D.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 back

It 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 in the library, rendered in Godot 4.7

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 --spec

godotwright 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

godot_doctor

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

godot_scan

Map the project: scenes and node trees, scripts, signals, autoloads, input map

godot_api

Exact Godot 4.7 lookup: signatures, inheritance, Godot 3 names

godot_api_search

Search the Godot 4.7 class reference

godot_review

AAA review with scores; also reviews unsaved code (code + file), or only what changed (only_new); from/target for upgrades between 4.x releases

godot_checklist

Every AAA rule with its fix

godot_feedback

Mark a review finding as wrong or right, or say whether a lesson helped, so Godotwright learns from it

godot_lessons

Lessons from real Godot projects (symptom, cause, fix, test) by words, Godot error, rule or topic; gaps lists what it cannot predict yet

godot_lesson_add

Keep a lesson learned here, scrubbed of names, paths and code; it comes back when the same error does

godot_dream

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 apply

godot_usages

Every place a name or res:// path is used: code, scenes, connections, groups, settings

godot_diff

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 @export value, callers with the wrong argument count)

godot_impact

What a change reaches: every scene that loads the changed files (default: what differs from git), whether it is global (autoload, project.godot), the tests and saved scenarios that cover it, and the checks to run

godot_collisions

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)

godot_rename

Rename a name or move a file everywhere at once, keeping connections, node paths and .uid files right

godot_project_edit

Change settings, input actions and autoloads in project.godot, touching only that entry

godot_scene_edit

Add or remove nodes, set properties, connect signals, attach scripts and make instances editable in a .tscn; refuses a change Godot would drop on the next editor save

godot_resource_edit

Edit a .tres (properties, sub_resources, uids kept) and import settings (.import options, per-animation, mesh, material and node options, importer switch); a written .import is reimported headless and checked

godot_migrate

Rewrite Godot 3 GDScript and shaders to Godot 4 where that is mechanical, and list what is left

godot_shader

Review every shader against Godot 4.7's shader tables and compile it with Godot headless; gpu: true also draws it for GPU driver errors; errors as file:line

godot_code

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

godot_deps

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

godot_undo

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

godot_fix

Apply the mechanical fixes for review findings, each labelled safe or check, uid repairs across files included; shows them first, then reviews the changed files again

godot_check

Run Godot headless (load every script and scene, compile every shader) and report errors as file:line, runtime errors with their call chain; shaders: true also draws every shader; compare_godot diffs against a second Godot

godot_test

Run GUT or GdUnit4 tests headless; only what failed, with file:line

godot_play

Run a scene with an input timeline and return the values you watch per frame; until a condition, signals with their frame, summary per value, expect claims

godot_export

Before an export: files the presets leave out although the game loads them, plain data files missing from include_filter, paths built under excluded folders; with pck, what an exported pack holds

godot_export_run

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

godot_scenario

Keep a passing godot_play run as a regression test in the project (save runs it once more first), list them, run one or all with every failing claim, its value and frame

godot_session

Load a scene once and keep the game running between calls, headless and paused, until you stop it

godot_game

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

godot_perf

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

godot_leaks

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

godot_screenshot

Render a scene or a .glb to a PNG and say how much is drawn and whether it is blank; with baseline, a visual test: unchanged as text only, or the percent changed, the areas of change and moves, and a diff picture

godot_model_brief

One page before you build, for small models: the kind to start from, parts, size, rules and the order of tools

godot_model_identify

What a thing is: parts, pivots, typical size with its source, variants (English or Dutch)

godot_model_spec

The model spec format, an example and the ready-made kinds

godot_model_library

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

godot_model_build

Build a clean .glb from a kind or a spec (inside the project), and lint it

godot_model_lint

Score a .glb; with archetype also check it is what it should be

godot_model_view

See a .glb as text: front, side and top views, parts with sizes, parts that do not touch

godot_model_inspect

What is in a .glb: nodes, triangles, textures, size

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 --convert-3to4

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; migrate rewrites scripts

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 (godot_session)

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 .pck and run the build

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

--lean (2 tools, ~900 tokens for all 43), tool sets, --read-only

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

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

MIT

Available Tools

43 tools
godot_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_checkCheck with real GodotA
Idempotent

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 checklistA
Read-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 serverA
Idempotent

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 whomA
Read-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 loadsA
Read-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 breaksA
Read-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 itA
Idempotent

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 holdA
Read-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 itA
Destructive

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 mechanicallyA
Destructive

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 runA
Read-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 hereA
Idempotent

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 4A
DestructiveIdempotent

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 modelA
Read-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 codeA
DestructiveIdempotent

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?A
Read-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 modelA
Read-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 recipesA
Read-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 modelA
Read-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 formatA
Read-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 textA
Read-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 inputA
Idempotent

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 autoloadsA
Destructive

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 everywhereA
Destructive

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 settingsA
Destructive

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 projectA
Read-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 testsA
Idempotent

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 sceneA
Destructive

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 modelA
Idempotent

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 shadersA
Idempotent

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 testsA
Idempotent

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 writesA
Destructive

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 usagesA
Read-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

    A3.9/5.0

    Scored across 43 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      23
      MIT