Build with an agent
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.
On this page7 sections
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 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.
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, 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 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.
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 explains why. - VR. Every screenshot is refused with
immersive-session-activeuntil 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.
Next steps#
- Exact panel capture: real pixels of a panel, with your permission.
- Hidden cards and AI agents: what the camera may not show.
- Set up a multiplayer lobby with an agent: take the game to a live table.