Dicey Table
Docs
Search the docs

Build with an agent

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.

3 min readVerified

View as Markdown
On this page7 sections

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 editor tab. The agent's API key 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 should feel.

Step 1: Open a preview#

In the editor tab, the agent calls playtest_start. 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 explains how calls find the right tab.

The editor tab and the preview tab share one agent session The agent calls playtest_start in the editor tab. A preview tab opens and joins the same agent session with no dialog. The agent reads diagnostics from both tabs. Your agentone session, through the bridge Editor tab/editorwhere fixes happen Preview tab/table?preview=…where the game is played playtest_start opens it diagnostics and results joins the session, no dialog; diagnostics too
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 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 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 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#

Did this page answer your question?