Play a scene with input
godot_playRun a Godot scene headless for physics frames with scripted input and watch node or action values per frame; get deterministic results, errors, prints, and optional assertions for play-testing.
Instructions
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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "godot_play"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | project folder, or a file or folder inside it (relative to the server's folder; default: the current project) | |
| every | No | sample every n frames (default 10); frames with input and the last frame are always sampled | |
| input | No | timeline: "10 press jump; 30 release jump; 40 hold right 20; 50 tap Key:Space" | |
| scene | No | the res:// scene to run (default: the main scene) | |
| until | No | stop at the first frame where this holds: "Heli.is_on_floor() == true" | |
| watch | No | values to sample: Player.position, Player.velocity.y, Player.is_on_floor() | |
| expect | No | 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 | No | physics frames to run (default 120) | |
| signals | No | signals to record: "Heli.landed", "Deck.body_entered" | |
| summary | No | one line per watched value instead of a table (samples every frame) | |
| timeout_seconds | No | timeout of the run (default 300) |