/screenshot

name: screenshot
description: |
  Capture gameplay screenshots using godot-e2e for visual verification.
  Use when you need to: take a screenshot of the running game, capture
  multiple screenshots during an E2E scenario, generate reference.png,
  visually verify game state, or provide screenshots for VQA analysis.
  Triggers: "screenshot", "capture screenshot", "take screenshot",
  "reference.png", "visual capture", "screenshot the game".

Screenshot — Gameplay Capture via godot-e2e

$ARGUMENTS

<!-- agent-operations: invoke_supporting_skill, run_shell_command -->

Capture screenshots from a running Godot game using godot-e2e's internal viewport capture. Works headless, multi-monitor safe, no external tools needed.

Quick Capture (single screenshot)

Write and run a Python script:

# capture_screenshot.py
import os, sys
from godot_e2e import GodotE2E

project_path = sys.argv[1] if len(sys.argv) > 1 else "."
save_path = sys.argv[2] if len(sys.argv) > 2 else "screenshot.png"

with GodotE2E.launch(project_path, timeout=15.0) as game:
    game.wait_for_node("/root/Main", timeout=10.0)
    game.wait_seconds(1.0)  # let the game render a few frames
    result = game.screenshot(save_path=save_path)
    print(f"Screenshot saved: {result}")

Run: `python capture_screenshot.py <project_dir> <output_path>`

Multi-Point Capture (E2E with screenshots)

For capturing multiple screenshots during a gameplay scenario:

# capture_gameplay.py
import os, sys
from godot_e2e import GodotE2E

project_path = sys.argv[1] if len(sys.argv) > 1 else "."
output_dir = sys.argv[2] if len(sys.argv) > 2 else "screenshots"
os.makedirs(output_dir, exist_ok=True)

with GodotE2E.launch(project_path, timeout=15.0) as game:
    game.wait_for_node("/root/Main", timeout=10.0)

    # 1. Initial state
    game.wait_seconds(0.5)
    game.screenshot(save_path=os.path.join(output_dir, "01_initial.png"))

    # 2. After some interaction (customize per game)
    game.wait_seconds(2.0)
    game.screenshot(save_path=os.path.join(output_dir, "02_gameplay.png"))

    # 3. Later state
    game.wait_seconds(3.0)
    game.screenshot(save_path=os.path.join(output_dir, "03_later.png"))

    print(f"Captured {len(os.listdir(output_dir))} screenshots to {output_dir}/")

Frame Sequence for VQA Question Mode

For scenes with motion, animation, or physics, capture **N frames at 0.5s intervals (2 FPS cadence)** and pass them to the `visual-qa` skill's Question mode. Output goes into a per-scene subdirectory (`e2e/screenshots/scene_{name}/`) so multiple scenes don't collide:

# capture_dynamic.py
import os, sys
from godot_e2e import GodotE2E

project_path = sys.argv[1]
out_dir      = sys.argv[2]   # e.g. "e2e/screenshots/scene_main"
n_frames     = int(sys.argv[3]) if len(sys.argv) > 3 else 6
os.makedirs(out_dir, exist_ok=True)

with GodotE2E.launch(project_path, timeout=15.0) as game:
    game.wait_for_node("/root/Main", timeout=10.0)
    game.wait_seconds(1.0)  # let initial render settle

    for i in range(n_frames):
        path = os.path.join(out_dir, f"frame_{i:03d}.png")
        game.screenshot(save_path=path)
        if i < n_frames - 1:
            game.wait_seconds(0.5)  # 0.5s = 2 FPS motion-review cadence

Then invoke the published `visual-qa` supporting skill through the active runtime's `invoke_supporting_skill` mapping. Ask a question grounded in the applicable `DESIGN.md` rules, with these arguments:

--question "Do these frames satisfy the listed DESIGN.md rules? Goal: ... Requirements: ... Verify: ..." e2e/screenshots/scene_main/frame_*.png

For static scenes (decoration, terrain, UI without motion), one screenshot is enough — use the Quick Capture pattern above and call `visual-qa` Question mode with `--question` plus the screenshot path. Static and Dynamic modes remain available only when the caller explicitly supplies a comparison image; never generate one for this check.

For fixgap worker visual self-checks, save evidence under `reports/fixgap-visual/<task_id>/`. For verifier-only fresh captures, use `reports/verifier-temp/`.

Generate reference.png

Use the quick capture method, save to `reference.png` in the project root:

python capture_screenshot.py <project_dir> <project_dir>/reference.png

If the game has a title screen, wait for it to load and capture. If the game starts directly in gameplay, capture after 1-2 seconds of gameplay.

Spot-Check Screenshots

During spot-check, use multi-point capture with game interactions:

# spot_check_capture.py
import os, sys
from godot_e2e import GodotE2E

project_path = sys.argv[1]
output_dir = os.path.join(project_path, "spot_check_screenshots")
os.makedirs(output_dir, exist_ok=True)

with GodotE2E.launch(project_path, timeout=15.0) as game:
    game.wait_for_node("/root/Main", timeout=10.0)

    # Capture at intervals
    for i in range(4):
        game.wait_seconds(1.5)
        path = os.path.join(output_dir, f"spot_{i+1}.png")
        game.screenshot(save_path=path)
        print(f"Spot-check screenshot {i+1}: {path}")

API Reference

| Method | Description | |--------|-------------| | `game.screenshot(save_path="")` | Capture viewport as PNG. Returns absolute path. If `save_path` is empty, saves to a temp file. |

Debug Collision Visualization

When capturing screenshots for physics/collision verification, launch Godot with `--debug-collisions` to render collision shapes as visible overlays:

with GodotE2E.launch(project_path, timeout=15.0,
                     extra_args=["--debug-collisions"]) as game:
    game.wait_seconds(1.0)
    game.screenshot(save_path="collision_check.png")

This makes CollisionShape2D/3D outlines visible in the capture, allowing VQA to verify that collision bounds match sprite extents.

Rules

1. **Always use `game.screenshot()`** — internal viewport capture. Do NOT use external screenshot tools. 2. **Wait before capturing** — `ga