MCP scripts
An MCP script is a JSON list of tool calls that the editor replays with run_script. The showcase maps are built
this way, so their scripts in examples/mcp double
as examples for every tool.
| Script | Builds |
|---|---|
mountain_house.json |
A cabin hanging off a cliff, with a cliff lift and forests |
church_school.json |
A church and a school where three buttons open the courtyard gate |
lighthouse_forest.json |
A lighthouse with a rotating beacon, a boat on a func_train and spawning wisps |
withered_city.json |
A ruined neon city at night with lightning, glow and ssr |
night_district.json |
An industrial street at night with a roller door and a viaduct train |
sea_island.json |
The sea island tutorial |
scripted_scene.json |
The cutscene tutorial |
Running them
godottrench --mcp-http --project godot # the editor with the demo project
python tools/mcp_script.py run examples/mcp/sea_island.json # replay a script
python tools/mcp_script.py shot view.png --pos 4300,900,3300 --look 2200,700,1200 --shade lit
The scripts save into godot/demo/maps/showcase, scripted_scene.json into godot/demo/maps. A run stops at the
first failed step unless you pass --continue-on-error.
Script format
{
"format": "godottrench-mcp-script",
"vars": { "save_dir": "${project}/maps" },
"steps": [
{ "note": "A hollow room." },
{ "tool": "map_file", "args": { "op": "new" } },
{ "tool": "create_brush", "args": { "min": [0, 0, 0], "max": [256, 128, 256] }, "save": "room" },
{ "tool": "select", "args": { "ids": "$room.ids" } },
{ "tool": "run_action", "args": { "action": "csg_hollow" } },
{ "tool": "map_file", "args": { "op": "save", "path": "${save_dir}/room.gtm" } }
]
}
A step without tool is a comment. A step with save stores its result under that name for later steps.
screenshot, simulate_input and run_script cannot run inside a script.
| Write | Means |
|---|---|
"$name.path" |
The saved JSON value. Numbers index arrays, as in $room.ids.0 |
"${name.path}" |
Its text inside a longer string |
"$a.ids + $b.ids" |
Both joined into one array. ["$a.ids", "$b.ids"] works too |
$last |
The previous step's result |
$project |
The open Godot project's folder, an error when none is open |
$script_dir |
The script file's folder |
$$ |
A literal $, so a node path is "$$Player" |
An unknown name is an error, so typos never pass silently. A $ that cannot start a name, like "$5", stays as it
is. Ids given as text, such as "42", work wherever a node id is expected.
Ids after CSG
CSG and clip steps replace brushes. The runner then rewrites the ids saved by earlier steps, so "$wall.ids" still
means the wall after a window is cut into it. In a list, a replaced id gives way to all of its replacements, or drops
out when the brush was removed. A single id becomes its replacement, a list of them, or null. Only values under id,
ids, selection, letters, copies, entity and keys ending in _id or _ids change.
Tip: Spell out every brush setting in
scatterandblendcalls. Anything left out comes from the editor's current Scatter panel or Blend tool settings.