Skip to main content
Glama

render_movie

Destructive

Render frames or a video of a Godot project or scene in a separate movie-writer run to check for blank output and motion, keep PNGs, or write an AVI/OGV file.

Instructions

Render frames frames of the project (or scene) in a separate movie-writer run: no bridge, session or input (to interact: run_project, simulate_input). mode check (default): stats, likelyBlank, motion, inline frames, files deleted. frames: keeps PNGs. video: .avi/.ogv, no stats. Returns: frameCount, likelyBlank, anyMotion, samples, paths, bytesWritten; warnings leads if unmeasured or unconfirmed. Needs a display; asks the user once per project. Errors on timeout, failed run or live session.

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": {
      "projectPath": "<projectPath>"
    },
    "name": "render_movie"
  }
}

Input Schema

NameRequiredDescriptionDefault
fpsNoFixed simulation and capture rate (default 30, max 120). Game time covered is frames / fps seconds, whatever the wall-clock speed.
modeNo"check" (default) measures a sample of frames, returns a few inline, and deletes every file. "frames" keeps the PNG sequence (and frame.wav) under .mcp/godot-runtime/movies/ and returns paths plus stats for a sample. "video" writes one movie file and returns its path; it has no pixel stats.
sceneNoScene to render (path relative to project, e.g. "scenes/main.tscn"). Omit to use the project's main scene. Must end in .tscn, .scn, .escn, .tres or .res.
formatNo[video] Movie container (default "avi"). "ogv" needs an engine that can write it; the error names the format and engine version when it cannot. Rejected in other modes.
framesNoFrames to render before Godot quits (default 30, max 600). The first frames can be blank while the scene loads; likelyBlank is judged on the last one. The run is budgeted at 30s plus 250ms per frame, and a run that overruns it takes up to 10s more to stop. A run of 77 to 80 frames is refused, with nothing run, because its answer would not fit a client's 60s request timeout; above that a client may cut the call off before this server can report a timeout.
projectPathYesPath to the Godot project directory
inlineFramesNo[check] Inline images to return, evenly spaced and ending at the last frame (default 3, max 6; 0 for none). Each is downscaled to fit 960x540; stats are measured at full size. Rejected in other modes.

Output Schema

NameRequiredDescriptionDefault
fpsYes
modeYes
pathNo
sceneNo
formatNo
motionNoLargest mean RGB difference between consecutive measured frames, over every pixel, 0 to 1. A small mover reads near 0 here; anyMotion is decided by the changed pixel count, not by this mean.
samplesNo
byteSizeNo
warningsNo
anyMotionNoTrue when some pair of consecutive measured frames had at least its motionThreshold of pixels whose R, G or B changed by more than 8 of 255; every pixel is compared. Null when no measured pair moved and a pair was not measured, or fewer than two frames were measured. motionPairs has the counts behind it.
audioPathNo
directoryNo
statsNoteNo
frameCountNoPNG frames found on disk after the run.
framePathsNoOmitted above 60 frames; use framePattern and frameCount.
framesKeptNo
likelyBlankNoJudged on every pixel of the last frame: true when it is one flat colour (no channel varies by more than 8 of 255 across it). Null when it was not measured.
motionPairsNo
projectPathYes
bytesWrittenNoTotal size in bytes of every file this run wrote under .mcp/godot-runtime/movies/. In check mode the files are deleted again (framesKept false); in frames and video mode they stay on disk until removed by hand. Null when the run directory could not be read.
framePatternNo
inlineFramesNo
measuredFramesNoSampled frames whose stats were measured.
statsAvailableYesFalse in video mode: stats need PNG frames.
framesRequestedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv4.0.1

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond the destructiveHint annotation: files are deleted in check mode but kept in frames mode, video mode emits no pixel stats, and warnings surface when data is unmeasured or unconfirmed. Timeout and error behavior ('errors on timeout, failed run or live session') and the display/prompt requirement are disclosed. It does not explain why destructiveHint is set beyond check-mode cleanup, nor what happens to pre-existing files in the movie directory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and alternatives, with no filler sentences. The telegraphic, semicolon-heavy phrasing ('no bridge, session or input', 'x, y, z' return lists) is compact but occasionally dense enough to slow parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with an output schema, the description covers the essentials an agent needs: mode tradeoffs, environment prerequisite (display), user-prompt side effect, and failure modes. Output-schema details are correctly left to the schema rather than duplicated at length.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter is already documented with enum values and bounds. The description largely restates that schema content (check/frames/video behavior, avi/ogv, PNG retention), adding little new meaning; the schema already carries the frame-budget and likelyBlank details. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (render frames of the project or scene) plus a key scope distinction: it runs a separate movie-writer pass with no bridge, session or input. It names run_project and simulate_input as the interactive counterparts, so an agent can separate this from siblings without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: if you need to interact with the running game, use run_project or simulate_input instead. It also summarizes what each mode does and mentions the display requirement and the one-time user prompt, giving concrete preconditions for calling it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.