Skip to main content
Glama

Editor Screenshot

editor_screenshot

Capture a screenshot of the Godot editor viewport or running game.

Instructions

Capture a screenshot of the Godot editor viewport or running game.

Picking a source: the default "viewport" captures the editor's 3D viewport, which is empty if the edited scene has no Node3D anywhere in the tree (or no scene is open). Those cases return EDITOR_NOT_READY with error.data = {editor_state: "viewport_not_3d", scene_root_type} and an actionable error.message — switch to "cinematic" if the scene has a Camera3D, or open a scene with 3D content.

Sources:

  • "viewport" (default): editor 3D viewport. Requires Node3D content in the edited scene (root or any descendant); see above for the no-3D-content / no-scene error shape.

  • "viewport_2d": editor 2D viewport. Use for 2D scenes. Not compatible with view_target/coverage/elevation/azimuth/fov.

  • "cinematic": render edited scene through its active Camera3D (no editor gizmos). Prefers a Camera3D marked current; falls back to the first Camera3D found in a depth-first walk. NODE_NOT_FOUND only when the scene contains no Camera3D at all.

  • "game": running game's framebuffer (only when project is running). A backgrounded/minimized game window freezes its main loop; the capture then returns the last rendered frame with stale_frame: true and a note in the metadata — focus the game window and retry for a current frame. GAME_HELPER_TIMEOUT means the game process never replied at all (nothing rendered yet, main thread blocked, or helper dead) — focus the window and retry, or use game_command to confirm liveness.

include_image=True (default) returns an MCP ImageContent block. view_target (comma-separated Node3D paths) reframes editor camera; AABB metadata always returned. coverage=True with view_target captures perspective + orthographic top-down references.

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": "editor_screenshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
fovNoCamera FOV in degrees. Tight 20-30 = zoom; 60-75 = context.
widthNoCinematic render width, 1..4096 pixels. Supply with height. Omit both to use the editor viewport size.
heightNoCinematic render height, 1..4096 pixels. Supply with width.
sourceNo"viewport" | "viewport_2d" | "cinematic" | "game". Default "viewport".viewport
azimuthNoCamera azimuth in degrees (0=front, 90=right).
save_toNoCinematic only: save the full render to a res:// PNG path. Parent directories are created. max_resolution and transport limits affect only the inline preview, not the saved PNG. With include_image=False, only metadata crosses the transport; saved_path, saved_width, saved_height and saved_bytes describe the file. File writes require a writable editor and cannot be undone.
coverageNoWith view_target, capture two reference shots + AABB.
elevationNoCamera elevation in degrees (0=level, 90=overhead).
overwriteNoReplace an existing save_to PNG. Default False.
session_idNoOptional Godot session to target. Empty = active session.
user_promptNoOptional context from the agent that requested the capture. With Vision Routing enabled it is sent alongside the image so the vision model can describe what the agent is looking for.
view_targetNoNode3D scene path(s) to frame, comma-separated.
include_imageNoReturn image data. Default True.
max_resolutionNoMaximum longest edge. Default 640. 0 removes the requested cap. Large PNGs are downscaled further to fit the MCP transport; metadata reports the actual and original dimensions.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv4.4.1
    • addedInput schema / properties / height
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Cinematic render height, 1..4096 pixels. Supply with width."
      +}
    • changedInput schema / properties / max_resolution / description
      Previous value: -"Longest-edge resolution. Default 640. 0 = full res."New value: +"Maximum longest edge. Default 640. 0 removes the requested\ncap. Large PNGs are downscaled further to fit the MCP transport;\nmetadata reports the actual and original dimensions."
    • addedInput schema / properties / overwrite
      Added value: +{
      +  "default": false,
      +  "description": "Replace an existing save_to PNG. Default False.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / save_to
      Added value: +{
      +  "default": "",
      +  "description": "Cinematic only: save the full render to a res:// PNG path.\nParent directories are created. max_resolution and transport\nlimits affect only the inline preview, not the saved PNG.\nWith include_image=False, only metadata crosses the transport;\nsaved_path, saved_width, saved_height and saved_bytes describe\nthe file. File writes require a writable editor and cannot be undone.",
      +  "type": "string"
      +}
    • addedInput schema / properties / width
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Cinematic render width, 1..4096 pixels. Supply with height.\nOmit both to use the editor viewport size."
      +}
  2. Addedv3.1.4
  3. Removedv3.0.7
  4. First observedv2.9.1

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full load and does so well: it discloses prerequisite scene content, the exact error shape (EDITOR_NOT_READY with error.data fields), stale-frame behavior for minimized games, and GAME_HELPER_TIMEOUT semantics with recovery steps. The main omission is the file-write/irreversibility behavior of save_to, which appears only in the parameter schema rather than the description body.

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?

Long but deliberately structured: the core action first, then a 'Picking a source' decision section, then a bulleted source list with per-source caveats. Some parenthetical detail (error-shape keys, retry advice) is dense but earns its place by preventing failed calls; only minor redundancy between the intro and the bullet list.

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 14-parameter tool with no output schema and no annotations, the description covers what an agent needs: source prerequisites, error conditions and recovery, what include_image returns, and what metadata accompanies the image (AABB, stale_frame, note). Return-value explanation is partial but the image/metadata contract is stated.

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 beyond the schema: view_target is explained as reframing the editor camera with AABB always returned, coverage is described as producing perspective plus orthographic top-down references, and include_image is tied to an MCP ImageContent block. The interplay between source and the view_target/coverage/elevation/azimuth/fov group is clarified beyond what the schema says.

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?

Opens with a specific verb+resource: 'Capture a screenshot of the Godot editor viewport or running game.' It then enumerates the four distinct capture sources, so an agent can distinguish exactly what will be captured rather than guessing from the name alone.

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?

Explicit routing guidance: 'Picking a source' explains when to choose viewport vs. cinematic vs. viewport_2d vs. game, including the failure conditions that should trigger a switch ('switch to "cinematic" if the scene has a Camera3D, or open a scene with 3D content'). Compatibility exclusions are stated (viewport_2d 'Not compatible with view_target/coverage/elevation/azimuth/fov').

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