Screenshot & Visual Diff Tools¶

Capture game view, save visual baselines, and compare screenshots for regression testing. Use these tools for visual verification and automated visual testing.

screenshot¶

Capture the current game view as a PNG image with optional object annotations and AI description.

Parameters: - width (int, default=640) — Image width in pixels - height (int, default=480) — Image height in pixels - camera (string, optional) — Camera preset: "scene_view" | "scene_view_frame" | "multi_view" | "single_view" | "overview" | "overview_game" | custom camera name - path (string, optional) — Scene path to target object (for framing) - output_path (string, optional) — Save path (default: auto-generated in Screenshots/) - describe (string, optional) — AI description mode: "haiku" - raw (bool, default=false) — Force path output instead of description - zoom (float, optional) — Zoom level (higher = closer) - angles (string, optional) — Per-view rotation (Euler angles): "ex,ey,ez|..." (use "_" to skip) - supersample (int, optional) — Antialiasing level (1-4) - offset (string, optional) — Framing offset (x,y) - fixed_size (float, optional) — Fixed framing size - highlight (string, optional) — Object paths to highlight with bounding box: "path1:path2:#RRGGBB" - show_colliders (bool, optional) — Overlay collider wireframes - angle (string, optional) — Camera angle for single_view: "front" | "left" | "top" | "iso" | "ex,ey,ez" - annotation_id (string, optional) — Draw object path labels (auto sets camera=annotation_frame)

Camera Presets:

Output: File saved under <project>/ScreenShots/ with an optional AI description appended.

Example:

# Basic screenshot
img = await screenshot()

# Custom size and camera
img = await screenshot(width=1280, height=720, camera="scene_view")

# Multi-view for debugging
img = await screenshot(camera="multi_view", zoom=1.5)

# With object highlighting (bounding box)
img = await screenshot(highlight="Player:Enemy:#FF0000",
                      camera="scene_view")

# Show colliders
img = await screenshot(camera="scene_view", show_colliders=True)

# Haiku AI description (token-efficient)
desc = await screenshot(describe="haiku", camera="scene_view")
# → "[AI analysis] Player standing at position (0,5,0), health UI visible..."
# → "[img:<project>/ScreenShots/2026-07-29_12-00-00_screenshot.png]"

# With annotation ID (labels on objects)
img = await screenshot(annotation_id="Player", camera="annotation_frame")

# Single-view with specific angle
img = await screenshot(camera="single_view", angle="front", width=800, height=600)

Use Cases: - Visual regression testing (compare with baseline) - Playtest documentation - Debugging spatial/rendering issues - CI/CD visual verification

screenshot_baseline¶

Save current screenshot as reference for visual regression testing.

Parameters: - name (string, default="default") — Baseline identifier - width (int, default=640) — Image width - height (int, default=480) — Image height - camera (string, optional) — Camera preset (same as screenshot)

Output: Baseline saved to .claude/baselines/{name}.png

Example:

# Save main menu baseline
baseline = await screenshot_baseline(name="main_menu", camera="scene_view")

# Save gameplay baseline at specific resolution
baseline = await screenshot_baseline(name="combat_start", 
                                    width=1920, height=1080,
                                    camera="overview")

Use Cases: - Establish visual reference before changes - Create regression testing suite - Document expected visual state

screenshot_compare¶

Compare current screenshot with saved baseline. Highlights differences and calculates similarity.

Parameters: - name (string, default="default") — Baseline identifier - width (int, default=640) — Image width - height (int, default=480) — Image height - camera (string, optional) — Camera preset (same as screenshot) - mode (string, default="auto") — Comparison algorithm: "auto" | "pixel" | "structural" | "targeted" | "ui_layout" | "animation" | "color" | "position" - question (string, optional) — Custom question for "targeted" mode (e.g., "Did the health bar change?")

Comparison Modes:

pixel comparison is local. Modes that use image analysis consume the configured LLM budget according to the actual image and token usage; auto consumes budget only when it escalates beyond the pixel comparison.

Output: Comparison report with diff image and similarity percentage.

Example:

# Setup: save baseline
await screenshot_baseline(name="level_1", camera="overview")

# Later: verify unchanged
result = await screenshot_compare(name="level_1", camera="overview")
# → "Similarity: 99.8% (5 pixels different)"

# Detect layout changes
result = await screenshot_compare(name="main_menu", mode="ui_layout")

# Targeted question
result = await screenshot_compare(name="hud", mode="targeted",
                                 question="Did the health bar color change?")

# Color detection
result = await screenshot_compare(name="environment", mode="color")

# Auto mode (starts with pixel, escalates if needed)
result = await screenshot_compare(name="gameplay", mode="auto")

Workflow:

1. Baseline Setup (first run)

   await screenshot_baseline(name="gameplay", camera="overview")
   

2. Make Changes

3. Modify game state, UI, objects, etc.

4. Verify Changes

   result = await screenshot_compare(name="gameplay", mode="auto")
   # → Report differences
   

5. Update Baseline (when intended)

   await screenshot_baseline(name="gameplay", camera="overview")
   

Use Cases: - Automated visual regression testing - Verify UI doesn't shift unexpectedly - Detect animation state changes - Validate color/material updates - CI/CD visual quality gates

Common Patterns¶

See also: Scene Tools for screenshot variants and editor control, UI Tools for object positioning verification via get_spatial_context.