# screenshot

> Screenshot capture and image analysis handoff. capture: capture a Godot scene screenshot in headless mode (experimental). analyze: return the image as MCP image content (base64) for the client vision capability to examine — returns image data, NOT a text description.

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | safe |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 是 |
| 长耗时 | 否 |

## Actions

- `capture`
- `analyze`
- `diff`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (3 项) | ✓ | Action type: capture (take a screenshot), analyze (AI visual analysis of an image), or diff (pixel-level comparison of two PNG images) |
| `project_path` | string |  | Path to Godot project directory |
| `scene` | string |  | capture: Scene file path relative to project (res://scenes/main.tscn). If omitted, captures the default scene or an empty viewport. |
| `output_path` | string |  | capture: Output PNG path (absolute). Defaults to <project_path>/screenshot.png |
| `frame_delay` | number |  | capture: Frames to wait before capture (default: 15) |
| `viewport_width` | number |  | capture: Viewport width in pixels (default: 1280) |
| `viewport_height` | number |  | capture: Viewport height in pixels (default: 720) |
| `wait_node` | string |  | capture: 等待该节点(名或 /root/... 路径)出现在场景树再截图。对分帧构建/异步初始化场景,优先于 frame_delay 生效;超时(固定 300 帧≈5s@60fps,独立于 max_frames)后放弃等待直接截图 |
| `wait_text` | string |  | capture: 等待任一 Label/RichTextLabel 的 text 包含该子串再截图;超时同 wait_node(固定 300 帧≈5s@60fps,独立于 max_frames) |
| `image_path` | string |  | analyze: Absolute path to the image file (PNG or JPG) |
| `question` | string |  | analyze: Question for the AI to answer about the image. Default: "Describe what you see in this game screenshot." |
| `vision_route` | boolean |  | Phase 2 Vision Routing:开启时调视觉模型(groq)把图片翻译成文字描述,返回纯文本(不含 image block),让纯文本模型(DeepSeek 等)也能"看懂"截图。失败时 fallback 到 detail 分层 + 追加 note。需 GODOT_MCP_VISION_KEY 环境变量。 |
| `vision_question` | string |  | vision_route=true 时传给视觉模型的上下文(可选,如"我在调试 Player 走路动画")。 |
| `detail` | enum: full | thumbnail | ascii |  | P1-5 视觉成本层级:full(完整 base64 图像,高 token) / thumbnail(缩放至 thumbnail_width 的 PNG,中 token) / ascii(ASCII art 文本,低 token)。默认 full。 |
| `thumbnail_width` | number |  | detail=thumbnail: 目标宽度像素(默认 256,保持纵横比) |
| `ascii_cols` | number |  | detail=ascii: 字符列数(默认 80) |
| `ascii_rows` | number |  | detail=ascii: 字符行数(默认 40) |
| `image_a` | string |  | diff: 基准图(a 图)路径。相对路径需 project_path;两图尺寸必须一致。 |
| `image_b` | string |  | diff: 对比图(b 图)路径。路径策略同 analyze 的 image_path(白名单校验)。 |
| `threshold` | number |  | diff: per-pixel 归一化欧氏距离阈值 sqrt(Δr²+Δg²+Δb²)/(√3×255),0-1,默认 0.12。恰好等于阈值不计差(严格大于才计)。忽略 alpha 只比 RGB。 |
| `diff_path` | string |  | diff: 可选,差异图输出路径。差异像素染纯红 (255,0,0),其余保留 a 图原色。不提供则不写文件。 |
| `godot_path` | string |  | 覆盖 Godot 二进制路径（可选，优先于项目配置和环境变量） |

## 风险分布

读 3

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->