Skip to main content
Glama

Screenshot a scene or model

godot_screenshot
Idempotent

Render a Godot scene or .glb/.gltf model to PNG and compare it with a baseline to catch visual changes or blank frames.

Instructions

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. Without Godot, godot_model_view shows a model as text; to check behaviour rather than looks, use godot_play.

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_screenshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoproject folder, or a file or folder inside it (relative to the server's folder; default: the current project)
modelNoa .glb or .gltf file to look at instead of a scene
sceneNothe res:// scene to render (default: the main scene)
viewsNocamera views for a model or a 3D scene without a camera (default [iso])
widthNowidth of one view (default 640)
framesNoframes to run before the picture (default 10)
heightNoheight of one view (default 360)
baselineNocompare with a baseline: "auto" (in .godotwright/baselines/, saved on the first run), a .png path inside the project, or a name (.godotwright/baselines/<name>.png with its settings in <name>.json)
thresholdNopercent of pixels that may change before the picture counts as changed (default 0.5, or the named baseline's)
toleranceNohow far (0-255) a pixel's colour may move before it counts as changed (default 3, or the named baseline's)
baseline_dirNofolder of named baselines inside the project (default .godotwright/baselines; godotwright ci needs --baseline-dir for another one)
update_baselineNosave the new picture as the baseline instead of comparing (baseline defaults to auto)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.6.0
    • addedInput schema / properties / baseline
      Added value: +{
      +  "description": "compare with a baseline: \"auto\" (in .godotwright/baselines/, saved on the first run), a .png path inside the project, or a name (.godotwright/baselines/<name>.png with its settings in <name>.json)",
      +  "type": "string"
      +}
    • addedInput schema / properties / baseline_dir
      Added value: +{
      +  "description": "folder of named baselines inside the project (default .godotwright/baselines; godotwright ci needs --baseline-dir for another one)",
      +  "type": "string"
      +}
    • changedInput schema / properties / path / description
      Previous value: -"The project folder, or any file or folder inside it (Godotwright walks up to project.godot). Relative paths start at the server's folder. Default: the current project."New value: +"project folder, or a file or folder inside it (relative to the server's folder; default: the current project)"
    • addedInput schema / properties / threshold
      Added value: +{
      +  "description": "percent of pixels that may change before the picture counts as changed (default 0.5, or the named baseline's)",
      +  "maximum": 100,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / tolerance
      Added value: +{
      +  "description": "how far (0-255) a pixel's colour may move before it counts as changed (default 3, or the named baseline's)",
      +  "maximum": 255,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / update_baseline
      Added value: +{
      +  "description": "save the new picture as the baseline instead of comparing (baseline defaults to auto)",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changedv0.1.1
    • changedInput schema / properties / path / description
      Previous value: -"Project directory or a path inside it (default: the current project)."New value: +"The project folder, or any file or folder inside it (Godotwright walks up to project.godot). Relative paths start at the server's folder. Default: the current project."
  3. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses that it writes PNGs next to the model or to .godot/godotwright/, uses xvfb-run on headless Linux, returns a text summary of coverage and blank warnings, and that renders are deterministic. It also explains baseline file creation and that 'auto' baselines should be committed.

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

Conciseness3/5

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

The core purpose is front-loaded, but the baseline/diff paragraph is a dense run-on that packs many concepts (percent, box, mean shift, five areas, diff picture, threshold, tolerance) into one block. It is informative but could be broken into clearer sentences.

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 12-parameter tool with no output schema, the description covers return values (picture plus text summary), error results (missing Godot, scene cannot run), file output locations, and the full baseline workflow. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: width/height are per view, frames lets the scene settle, baseline 'auto' saves on first run, and threshold/tolerance fall back to the named baseline's values. This exceeds what the schema alone conveys.

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 a scene, or a .glb/.gltf model ... to a PNG with Godot 4.7') and names the renderer and platform behavior. It also distinguishes itself from siblings by pointing to godot_model_view and godot_play for other needs.

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 says 'Use it to look at what you built' and routes the agent away when appropriate: 'Without Godot, godot_model_view shows a model as text; to check behaviour rather than looks, use godot_play.' Clear when-to-use and when-to-use-alternatives.

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