# Play-test your game with an agent

> An AI agent play-tests your DiceyTable game in a private preview. It plays moves, waits for the pieces to stop, then checks what should be true.

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

An agent play-tests your game in a private preview. It plays the same moves you would, waits for the pieces to stop, and then checks rules like "every player holds 7 cards". Each check comes back as a pass or a fail.

You need a [paired](https://diceytable.com/docs/ai-agents/setup/pairing) editor tab. The agent's [API key](https://diceytable.com/docs/ai-agents/setup/api-keys) needs **Edit projects** and **Play at the table**. It's the quick way to find out if your rules hold up before friends sit down, the way [playtesting a prototype online](https://diceytable.com/features/board-game-prototyping) should feel.

## Step 1: Open a preview

In the editor tab, the agent calls [`playtest_start`](https://diceytable.com/docs/ai-agents/reference/tools/playtest#playteststart). It saves your draft and opens it in a new tab. That tab pairs with the agent by itself, with no dialog, and the call returns its tab id.

A preview is **peerless**, which means nobody else can join. You're alone at the table. Nothing is recorded, and it never counts as play for chips or stats.

Now the agent has two tabs. It passes `tab` on each call to pick one, or it calls `session_select_tab` once. [Use one agent across several tabs](https://diceytable.com/docs/ai-agents/setup/multiple-tabs) explains how calls find the right tab.

![The editor tab calls playtest_start, a preview tab joins the same agent session, and both report diagnostics](https://diceytable.com/assets/build/playtest--editor-and-preview-BIe_SOLk.svg "**Two tabs, one agent.** The editor is where fixes happen. The preview is where the game gets played.")

## Step 2: Read the table

The agent looks before it plays. Four tools read the table:

- `table_snapshot` lists every object as **your seat** sees it. It can give a short summary or the full state. It can filter by kind, zone, owner seat or `label`.
- `table_query` returns only the objects that match a filter.
- `table_events` reads the event log, which says who did what.
- `table_hud_view` shows the game's on-screen UI as you see it. That means status lines, prompts, buttons and panels.

Card text, labels and player names come back marked as untrusted. The agent treats them as data and never as orders. [Prompt injection protection](https://diceytable.com/docs/ai-agents/concepts/prompt-injection) explains why.

## Step 3: Play some moves

The `table_*` action tools take the same path as your clicks. In a preview, the table applies each one right away.

| Tool | What it does |
|---|---|
| `table_spawn`, `table_move`, `table_rotate`, `table_flip` | Place and move objects |
| `table_shuffle`, `table_draw`, `table_deal`, `table_hand` | Work with decks and hands |
| `table_roll` | Roll dice |
| `table_click` | Click an entity, the way a script hears a mouse click |
| `table_object_action`, `table_menu_invoke` | Pick an item from an object's menu |
| `table_hud_act`, `table_ui_interact` | Answer a prompt, press a button, use a widget |
| `table_seat` | Take or change a seat |
| `table_intent` | Send any table intent the tools above don't cover |
| `table_reset` | Reset the table. Destructive in a preview, so it needs `confirm: true` |

## Step 4: Wait, then check

Physics takes time. A die that's still tumbling has no answer yet. So before it checks anything that moved, the agent calls `table_wait_settled`. It returns once everything is at rest. If that takes too long, it gives up after its timeout, which is 10 seconds unless the agent asks for up to 60.

Then the agent calls [`table_assert`](https://diceytable.com/docs/ai-agents/reference/tools/playtest#tableassert) with up to 100 checks at once:

| Check `type` | What it checks |
|---|---|
| `count` | How many objects match a kind, zone, owner seat or `label` (`equals`, `min`, `max`) |
| `field` | One field of one object has a value |
| `in-zone` | An object is inside a zone |
| `face` | An object is face up or face down |
| `owned-by` | An object belongs to a seat |

The result says whether everything `passed`. It also gives a pass or fail, with details, for each check.

## What can a test rely on?

Good tests check things that are always true. Bad tests bet on luck.

- **Check rules, not order.** "52 cards, one of each" is a good check. "The top card is the ace of spades" is not. Shuffles and draws use the host's private random numbers. No tool can read them or set a seed, and that's on purpose.
- **Check the range of a roll.** Dice give real rolls. Check that the die shows 1 to 6, or that a roll happened. Don't check the number.
- **Freeze physics when timing matters.** Physics doesn't repeat exactly from one run to the next. In a preview, `table_step_physics` freezes the table and moves time forward by 1 to 600 fixed steps. It can then let the table run again. A live room refuses it.
- **Test from the right seat.** The agent sees only what your seat may see, even when you're the host. To check a hand, test from the seat that owns it. [Hidden cards and AI agents](https://diceytable.com/docs/ai-agents/concepts/hidden-information) has the details.

## Step 5: Fix, reload, repeat

When a check fails, the agent fixes the game in the editor tab, not in the preview. Then it runs the loop:

1. It calls `project_save` in the editor tab.
2. It calls `playtest_reload` with `confirm: true`. A reload throws away the preview's table, so it counts as destructive.
3. It tests again.

When the agent is done, `playtest_stop` closes the preview. If something broke and the reason isn't clear, the next stop is the diagnostics hub.

## Next steps

- [Find errors with the diagnostics hub](https://diceytable.com/docs/ai-agents/workflows/diagnostics): read every error both tabs collected.
- [Take screenshots with an agent](https://diceytable.com/docs/ai-agents/workflows/screenshots): see what a player would see.
- [Test multiplayer with two agents](https://diceytable.com/docs/ai-agents/workflows/multiplayer-testing): check two hands from two seats.