# Godotwright (npm · godotwright) Godot 4.7 for coding agents: offline API, checks, review, safe edits, tests, play, 3D models. - Trust score: 81/100 (high trust) - Change this week: +2 - Registry status: active - Liveness: live - Owner verified: no - Last scored: 2026-11-05 ## Components - npm · `godotwright`: 81/100 (this document), [markdown](https://verifymcp.io/servers/laaielichter-godotwright/godotwright.md), [page](https://verifymcp.io/servers/laaielichter-godotwright/godotwright) ## Channel facts - Registry: `npm` - Package: `godotwright` - Version: `0.6.0` - Transport: `stdio` ## Trust breakdown How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog) Scored 2026-11-05. - **Supply Chain Security**: 98/100 - No malware found by supply-chain analysis. - No known CVEs affecting this package version or its production dependencies. - No install/post-install scripts declared. - 30 of 93 dependencies flagged as unhealthy. - **Provenance & Transparency**: 100/100 - Source repository is publicly reachable at the declared URL. - Cryptographically verified build provenance (signed, bound to laaielichter/Godotwright). - Clear OSI-approved license (MIT). - Actively maintained (last published 1 days ago). - Publishes a security disclosure policy (SECURITY.md). - **Schema Quality & AI Usability**: 59/100 - AI-judged instruction clarity (excellent). - Context-footprint check failed: tool/resource definitions use about 14080 tokens (~370/item across 38 items; 38 tools + 0 resources), over budget; trim descriptions and params. - Usage-examples check failed: none of the tools include examples. - **Stability & Change Management**: 23/100 - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses. - **Tool Coverage**: 100/100 - 100% of tools have a non-trivial description (not blank, and not just the tool's name). - 100% of tool parameters carry a description. - Structured output schemas are declared (11% of tools); any adoption earns full credit. - **Tool Safety**: 100/100 - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured. - We read all 38 captured tool definition(s), and no name or description among them implies an irreversible operation. - An AI judge read all 39 captured unit(s) of tool text and found none that tries to manipulate the model reading it. - **Capabilities**: 100/100 - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28. ## Install ### How do I install the Godotwright MCP server? Godotwright runs locally as an npm package, launched with npx -y godotwright. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation. ### Claude ```bash claude mcp add laaielichter-godotwright -- npx -y godotwright ``` ### Cursor ```json { "mcpServers": { "laaielichter-godotwright": { "command": "npx", "args": [ "-y", "godotwright" ] } } } ``` ### VS Code ```json { "servers": { "laaielichter-godotwright": { "command": "npx", "args": [ "-y", "godotwright" ] } } } ``` ### Codex ```bash codex mcp add laaielichter-godotwright -- npx -y godotwright ``` ### opencode ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "laaielichter-godotwright": { "type": "local", "command": [ "npx", "-y", "godotwright" ], "enabled": true } } } ``` ### OpenClaw ```bash openclaw mcp add laaielichter-godotwright --command npx --arg -y --arg godotwright ``` ### Hermes ```yaml mcp_servers: laaielichter-godotwright: command: "npx" args: ["-y", "godotwright"] ``` ### Netclaw ```json { "McpServers": { "laaielichter-godotwright": { "Transport": "stdio", "Command": "npx", "Arguments": [ "-y", "godotwright" ] } } } ``` ### Vellum ```bash assistant mcp add laaielichter-godotwright -t stdio -c npx -a -y godotwright ``` ### Other ```json { "mcpServers": { "laaielichter-godotwright": { "command": "npx", "args": [ "-y", "godotwright" ] } } } ``` ## Changelog Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims. ### 2026-11-04 (score 81, +1) No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes. ### 2026-11-03 (score 80, +15) - [security improvement] Malware scan: unverified → pass - [functional regression] Schema quality: 12237 → 14080 - [functional] First check of Tool coverage: 11 - [functional] Package version: 0.5.0 → 0.6.0 ### 2026-11-02 (score 65, −15) - [security regression] Known CVEs: pass → unverified - [security regression] Malware scan: pass → unverified - [functional regression] Schema quality: 218 → 370 - [functional regression] Schema quality: 218 → 351 - [functional regression] Schema quality: 218 → 331 - [functional regression] Dependency health: 0.86 → unverified - [functional] Schema quality: good → excellent - [functional] Package version: 0.2.0 → 0.5.0 - [functional] Package version: 0.2.0 → 0.4.0 - [functional] Package version: 0.2.0 → 0.3.0 ### 2026-11-01 (score 80, +1) - [security regression] Stability: 0.07 → unverified - [security regression] Tool safety: pass → unverified - [functional regression] Capabilities: pass → unverified - [functional regression] Tool coverage: 100 → unverified - [functional] First check of Schema quality: unverified - [functional] Package version: 0.1.0 → 0.2.0 ### 2026-10-31 (score 79, +15) - [security improvement] Malware scan: unverified → pass ### 2026-10-30 (score 64, −15) - [security regression] Malware scan: pass → unverified - [functional regression] Schema quality: 132 → 216 - [functional improvement] Tool coverage: 94% → 99% - [functional] Package version: 0.0.2 → 0.1.0 ### 2026-10-29 (score 79) First indexed and scored. ## MCP tools (38) ### `godot_scan` (~183 tokens) Map the Godot project 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`. Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) ### `godot_api` (~239 tokens) Look up the Godot 4.7 API 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). Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `query` (string, required): e.g. CharacterBody2D.move_and_slide, Node.ready, @export_range, lerp, Tween ### `godot_api_search` (~185 tokens) Search the Godot 4.7 API 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. Input parameters: - `limit` (integer): max results (default 10) - `query` (string, required): words, e.g. 'raycast 3d', 'change scene', 'is on floor' ### `godot_review` (~423 tokens) AAA review 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. Input parameters: - `code` (string): unsaved GDScript to review in place of the file on disk - `detail` (string): brief (capped lists) or full (everything); default brief - `file` (string): res:// path the code belongs to (required with code) - `files` (array): only show findings in these res:// files - `from` (string): release it comes from (default: the version saved in project.godot) - `only_new` (boolean): show only what changed since the last review of this project (saves tokens in a fix loop) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `target` (string): Godot release the project moves to, "4.1" to "4.7" (default 4.7) Output parameters: - `categories` (object) - `errors` (number) - `findings` (array) - `ok` (boolean) - `overall` (number) - `project` (string) - `truncated` (number) - `warnings` (number) ### `godot_usages` (~227 tokens) Find usages 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. Input parameters: - `name` (string, required): what to look for, e.g. take_damage, health_changed, Player, jump, res://scenes/enemy.tscn - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) ### `godot_rename` (~271 tokens) Rename everywhere 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. Input parameters: - `from` (string, required): the current name, or a res:// path - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `to` (string, required): the new name, or the new res:// path - `write` (boolean): apply the rename (default false: show the plan only) ### `godot_project_edit` (~495 tokens) Change project settings, input map or autoloads 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. Input parameters: - `action` (string): input_add/input_remove: the action name, e.g. jump - `deadzone` (number): input_add: deadzone of a new action (default 0.2) - `events` (array): input_add: events such as Key:Space, Mouse:Left, JoyButton:0, JoyAxis:1- - `file` (string): autoload_add: res:// path of the script or scene - `global` (boolean): autoload_add: make a global variable (default true) - `key` (string): set/unset: the setting path, e.g. display/window/size/viewport_width - `name` (string): autoload_add/autoload_remove: the autoload name, e.g. Game - `op` (string, required): what to change - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `value` (string): set: the value, e.g. 1920, true, 1.5, a text, res://main.tscn or Vector2i(1920, 1080) - `write` (boolean): write the change (default false: show the diff only) ### `godot_scene_edit` (~592 tokens) Change a scene 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. Input parameters: - `editable` (boolean): set_editable: false to make it not editable (default true) - `from` (string): connect/disconnect: path of the node that emits - `instance` (string): add_node: a res:// scene to instance instead of a type - `make_editable` (boolean): add_node/set/connect: also make the instance editable when the change is inside one - `method` (string): connect/disconnect: method name - `name` (string): add_node: name of the new node - `node` (string): remove_node/set/attach_script/set_editable: path of the node ("." is the root) - `op` (string, required): what to change - `parent` (string): add_node: path of the parent ("." is the root) - `property` (string): set: property name, e.g. position - `scene` (string, required): the scene: res://main.tscn, or a path - `script` (string): attach_script: res:// path of the script - `signal` (string): connect/disconnect: signal name - `to` (string): connect/disconnect: path of the node that receives - `type` (string): add_node: a Godot node class, e.g. Sprite2D - `value` (string): set: the value, e.g. Vector2(10, 20), 3, true, ALWAYS, res://icon.svg, null - `write` (boolean): write the change (default false: show the diff only) ### `godot_shader` (~480 tokens) Review and compile shaders 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. Input parameters: - `code` (string): unsaved shader code, checked in place of the file on disk - `compile` (boolean): compile with Godot (default: when Godot is found; true fails without it) - `detail` (string): brief (capped lists) or full (everything); default brief - `file` (string): res:// path the code belongs to (required with code) - `files` (array): only these res:// shaders, includes or scenes - `gpu` (boolean): also draw them on the Compatibility renderer, for GPU driver errors (needs a display or xvfb-run) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) ### `godot_resource_edit` (~369 tokens) Change a resource or import settings 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. Input parameters: - `file` (string, required): res://path or a path: .tres, .tscn, an asset or its .import - `ops` (array, required): changes or questions, applied in order - `reimport` (boolean): after a .import write, reimport with Godot and verify (default true) - `write` (boolean): write (default false: diff only) ### `godot_migrate` (~313 tokens) Port Godot 3 scripts to Godot 4 Rewrite Godot 3 GDScript and shaders to Godot 4 where that is mechanical: @export/@onready/@tool, 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 (setget, move_and_slide arguments, rpc keywords, 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. Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `files` (array): only these res:// scripts or shaders - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `write` (boolean): rewrite the scripts on disk (default false: report only) ### `godot_export` (~273 tokens) Check what the exported game will hold 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. Input parameters: - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `pck` (string): an exported .pck or game executable to read and compare - `preset` (string): only this preset (its name or number) ### `godot_export_run` (~416 tokens) Export headless, check the build and run it 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. Input parameters: - `against` (array): patch: base .pck files in load order - `frames` (integer): frames to run the exported game (default 120, 0 = no run) - `manifest` (array): patch: lists of the base game's files (JSON with md5, or paths) - `mode` (string): default pack - `out` (string): output file inside the project (.pck for pack and patch) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `pck` (string): smoke: the .pck or exported game to run - `preset` (string): the preset (name or number); not needed for smoke - `timeout_seconds` (integer): timeout per Godot run (default 600) ### `godot_deps` (~278 tokens) The project's files as a graph: unused, why used, what a scene loads 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. Input parameters: - `file` (string): why and of: the res:// file - `op` (string, required): unused, why, of or cycles - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) ### `godot_undo` (~218 tokens) Undo the last Godotwright writes 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. Input parameters: - `force` (boolean): undo even when a file changed after the write; those changes are lost - `list` (boolean): only list the writes that can be undone - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `steps` (integer): how many writes to undo (default 1) ### `godot_session` (~279 tokens) Start or stop a game session that stays up 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. Input parameters: - `idle_minutes` (integer): quit after this many minutes without a request (default 15) - `op` (string, required): start, status or stop - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `restart` (boolean): stop a running session and load the scene again - `scene` (string): the res:// scene to load (default: the main scene) - `timeout_seconds` (integer): how long the scene may take to load (default 300) ### `godot_game` (~678 tokens) Look at and drive the running game session 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. Input parameters: - `args` (array): call: arguments as Godot values - `depth` (integer): tree: levels to show (default 3) - `every` (integer): step: sample every n frames (default: about 10 samples) - `expr` (string): eval: the expression, e.g. get_node("Hero").velocity.length() - `files` (array): reload: res:// scripts to reload (default: every script changed since the session started or the last reload) - `frames` (integer): step: frames to run (default 60) - `from` (string): ray: start, Vector3(...) or Vector2(...) - `input` (string): step: "0 press jump; 10 release jump; 20 hold right 30" - `limit` (integer): tree: nodes to show (default 80) - `method` (string): call: method name - `node` (string): call: node path from the scene root - `op` (string, required): what to do - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `root` (string): tree and layout: start at this node (default the scene root) - `signals` (array): signals: Node.signal to record - `sizes` (array): ui: window sizes such as 1280x720 or 720x1280 (default the size the project sets) - `target` (string): set: Node.property - `to` (string): ray: end - `until` (string): step: stop at the first frame where this holds, "Hero.is_on_floor() == true" - `value` (string): set: the new value as Godot writes it, e.g. Vector3(0, 30, 0) - `watch` (array): get and step: values to read, e.g. "Hero.position", "Hero.is_on_floor()" ### `godot_perf` (~346 tokens) Measure a scene's frame times 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. Input parameters: - `baseline` (boolean): compare with and save the last run of this scene (default true) - `budget_ms` (number): frame budget in ms (default 16.6) - `frames` (integer): frames to measure (default 600) - `input` (string): input while measuring: "10 hold right 300" - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `scene` (string): the res:// scene to measure (default: the main scene) - `timeout_seconds` (integer): timeout of the run (default 300) - `warmup` (integer): frames to run first without measuring (default 60) ### `godot_leaks` (~367 tokens) Find what leaks per scene reload 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/). Input parameters: - `cycle_frames` (integer): frames per cycle (default 60) - `cycles` (integer): cycles (default 5) - `input` (string): timeline replayed each cycle: "10 press load; 40 press unload" - `keep` (boolean): keep the scene running instead of freeing it each cycle - `objects_per_cycle` (number): allowed object growth per cycle (default 0) - `orphans_per_cycle` (number): allowed orphan-node growth per cycle (default 0) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `scene` (string): the res:// scene to cycle (default: the main scene) - `timeout_seconds` (integer): timeout of the run (default 300) - `warmup` (integer): first cycles not counted (default 1) ### `godot_doctor` (~289 tokens) What is wrong, and in which order to fix it 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. Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `files` (array): only problems in these res:// files - `godot` (boolean): run Godot too when it is installed (default true) - `limit` (integer): problems shown in full (default 12) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `symptom` (string): what you see going wrong, in plain words Output parameters: - `errors` (number) - `findings` (array) - `godot` (string) - `next` (array) - `ok` (boolean) - `overall` (number) - `truncated` (number) - `warnings` (number) ### `godot_fix` (~509 tokens) Fix review findings mechanically 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. Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `files` (array): only these res:// files - `from` (string): release the project comes from, as in godot_review - `include_check` (boolean): also apply fixes labelled check (default false) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `rules` (array): only these rules (the fixable ones are listed above) - `stamp_uids` (boolean): also give scenes, resources, scripts and shaders without a uid a new one (header or .uid file) - `write` (boolean): write the fixes (default false: show them only) ### `godot_check` (~413 tokens) Check with real Godot 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. Input parameters: - `compare_godot` (string): second Godot binary to diff against, or "next" for $GODOT_NEXT - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `run_frames` (integer): also run the main scene for this many frames and return its output (default 0; 120 when scene is given) - `scene` (string): run this scene (a res:// path) instead of the main scene - `shaders` (boolean): also draw every shader on the Compatibility renderer, for what only the GPU driver rejects (needs a display or xvfb-run) - `timeout_seconds` (integer): timeout per Godot run (default 600) Output parameters: - `errors` (number) - `findings` (array) - `frames` (number) - `godotVersion` (string) - `ok` (boolean) - `scenes` (number) - `scripts` (number) - `shaderFiles` (number) - `shaders` (object) - `truncated` (number) - `warnings` (number) ### `godot_code` (~413 tokens) Ask Godot's GDScript language server 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. Input parameters: - `code` (string): unsaved GDScript to analyse as `file` instead of the file on disk; nothing is written - `column` (integer): 1-based column; a tab is one column (hover, definition, completion) - `file` (string): the .gd file: res:// path or a path (diagnostics without it: every script) - `limit` (integer): completion: most items shown (default 40) - `line` (integer): 1-based line (hover, definition, completion) - `op` (string, required): diagnostics, hover, definition or completion - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) ### `godot_screenshot` (~871 tokens) Screenshot a scene or model 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. W… Input parameters: - `baseline` (string): compare with a baseline: "auto" (in .godotwright/baselines/, saved on the first run), a .png path inside the project, or a name (.godotwright/baselines/.png with its settings in .json) - `baseline_dir` (string): folder of named baselines inside the project (default .godotwright/baselines; godotwright ci needs --baseline-dir for another one) - `frames` (integer): frames to run before the picture (default 10) - `height` (integer): height of one view (default 360) - `model` (string): a .glb or .gltf file to look at instead of a scene - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `scene` (string): the res:// scene to render (default: the main scene) - `threshold` (number): percent of pixels that may change before the picture counts as changed (default 0.5, or the named baseline's) - `tolerance` (number): how far (0-255) a pixel's colour may move before it counts as changed (default 3, or the named baseline's) - `update_baseline` (boolean): save the new picture as the baseline instead of comparing (baseline defaults to auto) - `views` (array): camera views for a model or a 3D scene without a camera (default [iso]) - `width` (integer): width of one view (default 640) ### `godot_play` (~581 tokens) Play a scene with input 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. Input parameters: - `every` (integer): sample every n frames (default 10); frames with input and the last frame are always sampled - `expect` (array): claims to check: "Heli.health > 0" (last frame) or "Heli.position.y < 1 @ 90"; their values are watched; on a recorded signal, "Heli.landed >= 1" counts how often it fired - `frames` (integer): physics frames to run (default 120) - `input` (string): timeline: "10 press jump; 30 release jump; 40 hold right 20; 50 tap Key:Space" - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `scene` (string): the res:// scene to run (default: the main scene) - `signals` (array): signals to record: "Heli.landed", "Deck.body_entered" - `summary` (boolean): one line per watched value instead of a table (samples every frame) - `timeout_seconds` (integer): timeout of the run (default 300) - `until` (string): stop at the first frame where this holds: "Heli.is_on_floor() == true" - `watch` (array): values to sample: Player.position, Player.velocity.y, Player.is_on_floor() ### `godot_scenario` (~450 tokens) Keep and run scenario tests 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. Input parameters: - `expect` (array): save: claims, "Hero.velocity.y == -400 @ 10", "Hero.landed >= 1" - `frames` (integer): save: physics frames to run - `input` (string): save: timeline, "10 tap jump; 40 hold right 20" - `name` (string): save: the new scenario's name (letters, digits, _ or -); run and list: which ones (default all) - `op` (string, required): list, run or save - `overwrite` (boolean): save: replace a scenario with that name - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `scene` (string): save: the res:// scene (default: the main scene) - `signals` (array): save: signals to record, "Hero.landed" - `timeout_seconds` (integer): timeout of each run (default 300) - `until` (string): save: stop when this holds; the scenario fails when it never does - `watch` (array): save: extra values to sample ### `godot_test` (~321 tokens) Run the unit tests 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. Input parameters: - `dirs` (array): test folders or scripts as res:// paths (default: the framework's config, else res://test and res://tests) - `filter` (string): GUT only: run only tests whose name contains this text - `framework` (string): which framework (default: whichever is installed) - `path` (string): project folder, or a file or folder inside it (relative to the server's folder; default: the current project) - `timeout_seconds` (integer): timeout of the run (default 600) Output parameters: - `errors` (number) - `failed` (number) - `findings` (array) - `framework` (string) - `ok` (boolean) - `passed` (number) - `skipped` (number) - `tests` (number) - `truncated` (number) - `warnings` (number) ### `godot_feedback` (~228 tokens) Feedback on a review finding 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. Input parameters: - `finding` (string): the finding line, e.g. res://player.gd:12: error [api/unknown-member] ... - `lesson` (string): a lesson id from godot_lessons, e.g. physics/moving-platform-velocity - `verdict` (string, required) ### `godot_lessons` (~382 tokens) Lessons from real Godot projects 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`). Input parameters: - `detail` (string): brief (capped lists) or full (everything); default brief - `error` (string): a Godot error or warning message, as printed - `gaps` (boolean): list what Godotwright cannot predict yet instead of lessons - `limit` (integer): max lessons (default 5; 20 when listing) - `query` (string): words, or a lesson id - `rule` (string): a rule id from godot_review or godot_model_lint, e.g. api/infer-variant - `topic` (string): only lessons of this topic ### `godot_lesson_add` (~335 tokens) Keep a lesson learned here 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. Input parameters: - `cause` (string): why, in Godot terms - `error` (string): the Godot message it explains, as printed - `fix` (string, required): what to do instead - `rules` (array): review or model rule ids it belongs to - `symptom` (string): what went wrong, as it showed - `tags` (array): words to find it by - `test` (string): how to test it - `title` (string, required): the lesson in one line, e.g. 'A body placed on a moving deck must start at the deck speed' - `topic` (string): default gdscript ### `godot_checklist` (~98 tokens) AAA checklist 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. ### `godot_model_identify` (~218 tokens) What is this thing? 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. Input parameters: - `text` (string, required): what you want to make or check, e.g. 'a tractor', 'helikopter', 'wind turbine' ### `godot_model_brief` (~173 tokens) Briefing before you build a model 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. Input parameters: - `text` (string, required): what you want to make, e.g. 'a rowing boat', 'dragon', 'castle wall' ### `godot_model_spec` (~112 tokens) Model spec format 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. ### `godot_model_build` (~583 tokens) Build a 3D model from code 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. Input parameters: - `collision` (string): collision for Godot: convex (a hull per mesh on import, for props and vehicles), trimesh (exact triangles on import, for buildings), or heightmap (terrain tiles: writes .heightmap.tres and