# Take screenshots with an agent

> An AI agent sees your DiceyTable game through screenshots of the 3D view, cards, models and panels, each sized to fit its vision input. Here is how to pick one.

- Question: How does an agent take screenshots of my game?
- Source: https://diceytable.com/docs/ai-agents/workflows/screenshots
- Last verified: 2026-10-09

An agent sees your game by taking screenshots. It can capture the 3D view, a single card, a model or a panel. Every image is sized to fit the agent's vision input, and it comes with a short report: the size, the bytes, the camera and what was hidden.

Screenshots are how an agent checks its own work, the same way you step back from the table to look. They work in the editor, a [play-test preview](https://diceytable.com/docs/ai-agents/workflows/playtest) and a live table.

## Which screenshot tool should the agent use?

Pick the cheapest tool that answers the question.

| You want to know | Use |
|---|---|
| What a panel's fields are set to | `describe_panel` (text, no image) |
| What the 3D scene looks like | `screenshot_viewport` |
| What a model, material or texture looks like on its own | `screenshot_surface` |
| What one card looks like, face or back | `screenshot_card` |
| What a panel or dialog looks like | `screenshot_panel` |
| What this tab can capture right now | `capture_surfaces` |

**Prefer `describe_panel` to `screenshot_panel`.** It returns each field of a panel with its value, plus each button, as text. That's usually what the agent wants to know. It's always exact, and it costs a fraction of an image.

![Choosing a capture tool: describe_panel first, then screenshot_panel, screenshot_surface or screenshot_viewport](https://diceytable.com/assets/build/screenshots--pick-a-tool-QEAfEk2j.svg "**Start with text.** Reach for an image only when the answer is how something looks.")

## Size and budget

With no size given, the long edge is **1280 px**. The agent can ask for up to 2576 px per edge. The format is `webp` unless it asks for `jpeg` or `png`. Use `png` for checks that must match pixel for pixel.

Every image has a byte budget, `maxBytes`. It's 600,000 bytes by default and 5,000,000 at most. Over the [relay](https://diceytable.com/docs/ai-agents/concepts/how-it-works), the most is 400,000. If an image comes out too big, the tab lowers the quality, then shrinks the image, up to five tries. The report then says `clamped: true`. If it still can't fit, the call fails with `over-budget`.

`saveTo` also writes the image to a file on your computer. It only writes inside the bridge's allowed folders, and the key needs **Local files**. [Which local files an agent can read](https://diceytable.com/docs/ai-agents/concepts/local-file-access) explains the fence.

## Step 1: Choose a camera

`screenshot_viewport` captures the 3D view. Its `camera` decides where it looks from.

| `camera` | What you get |
|---|---|
| `"current"` (default) | Exactly your view. Almost free, since the tab was drawing that frame anyway |
| `"top"`, `"front"`, `"side"`, `"iso"` | A separate **agent camera** framing the whole table |
| `"fit-selection"` | The agent camera framing what's selected |
| `{ "fitEntities": [...] }` | The agent camera framing those entities |
| `{ "position", "target", "fov" }` | The agent camera at an exact spot, in feet |

The agent camera never moves your view. It draws its own image, but without effects such as bloom or depth of field. The report lists that gap as `no-post-fx`. For a faithful image, the agent passes `tier: "ultra"`. That uses the photo mode pipeline. It takes a few seconds, and in a live room you confirm it first.

`crop` trims the image to some entities or to a rectangle. `settle: true` waits for assets to load and for pieces to stop moving first.

## Step 2: Hide the clutter

`hide` removes editor overlays from the image.

| `hide` | Removes |
|---|---|
| `"none"` (default) | Nothing |
| `"chrome"` | Gizmos, grids, helpers, selection outlines, and zone and snap point markers. The game itself stays, decals, text labels and a mod's own UI included |
| A list of photo mode categories | Exactly those |

With your own camera, hiding takes the overlays out of your view for **one frame**. You might see a single frame flicker without gizmos. Nothing else about your view changes.

## Other things the agent can capture

`capture_surfaces` lists what the tab can capture right now. Besides the 3D view, that includes the model and material previews, deck cards and sheets, card layouts, textures, the two image editors, board tracing and the Screenshots gallery. `screenshot_surface` takes one of those by id. `screenshot_card` draws card N of a deck, face or back, even if it isn't on the table.

`screenshot_panel` captures a panel or dialog by its id. By default it's **approximate**: it redraws the panel's HTML as an image. That's quick, but outside images, embedded frames and some effects can come out blank. The report's `fidelity.gaps` lists what it missed. For the real pixels, see [exact panel capture](https://diceytable.com/docs/ai-agents/workflows/exact-panel-capture).

## Why was a screenshot refused?

- **Hidden cards.** A screenshot never shows more than your seat may see. At a live table where you're the host, the agent may only use your own view. In a preview, it can't look up from under the table. Both refusals say `role-denied`. [Hidden cards and AI agents](https://diceytable.com/docs/ai-agents/concepts/hidden-information#screenshots-and-the-agent-camera) explains why.
- **VR.** Every screenshot is refused with `immersive-session-active` until you leave the headset view.
- **A background tab.** It draws no frames, so 3D captures fail with `surface-unavailable`. Keep the tab visible, even in another window.
- **Room packs.** Take those in the editor. A preview tab doesn't draw a room's decor yet. See [Build a room or table pack with an agent](https://diceytable.com/docs/ai-agents/workflows/build-a-room-or-table).

## Next steps

- [Exact panel capture](https://diceytable.com/docs/ai-agents/workflows/exact-panel-capture): real pixels of a panel, with your permission.
- [Hidden cards and AI agents](https://diceytable.com/docs/ai-agents/concepts/hidden-information): what the camera may not show.
- [Set up a multiplayer lobby with an agent](https://diceytable.com/docs/ai-agents/workflows/lobby): take the game to a live table.