run_script
Execute GDScript inside a running Godot 4 game to inspect or manipulate the live scene tree, with optional timeout and JSON-serialized results.
Instructions
Run GDScript in the running game. It must extend RefCounted and define func execute(scene_tree: SceneTree) -> Variant; execute may await, cut off at the timeout (not cancelled). Return is JSON-serialized: vectors as {x,y[,z,w]}, Color as {r,g,b,a}, a Node as {class,name,path}. Compiled with project warnings. Returns: projectPath, result, warnings, tip. Spawned: a runtime error is an error if result is null, else a warning. Attached: errors are unobservable. Asks the user once per project.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"script": "<script>"
},
"name": "run_script"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | GDScript source code. Must contain "extends RefCounted" and "func execute(scene_tree: SceneTree) -> Variant". | |
| timeout | No | Timeout in ms, a whole number from 1 to 600000 (default: 30000); a value from 59001 to 60000 is refused, since the answer would not fit a client's 60s request timeout. Increase for long-running scripts. Time spent on the confirmation prompt and waiting for the session queue comes off it; a call left with under 2000 ms is refused with nothing sent. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tip | Yes | ||
| result | Yes | The value execute returned. Vector2, Vector3 and Vector4 (and their int forms) are {x, y[, z, w]}, Color is {r, g, b, a}, and a packed array is a plain array of its elements, the shapes get_node_properties returns. A non-finite number (INF, NAN) is null and counted in warnings. Rect2, Quaternion, transforms and other types without a shape of their own are their text form (null and counted when a component is non-finite). A Node is {class, name, path}, a Resource {class, path}, another Object its text, a freed Object "<Freed Object>". | |
| warnings | No | ||
| projectPath | Yes |