Play-Test Tools for AI Agents

These tools run and check a private preview of your game. They open, reload and close the preview, wait for pieces to settle, step physics one frame at a time, check results and reset the table. The table action tools make the moves.

Tools in this family#

7 tools. The tool reference lists every family. An MCP client shows each tool as mcp__diceytable__<name>.

→ D / → H: the call escalates with certain arguments (see the tool). +: the call takes the class of the tool or action it dispatches to. bridge: answered by the bridge, on any surface, with no tab.

playtest_start#

Start play-test — Save the editor project and open it in a peerless preview table tab that pairs with this agent automatically; returns the new tab id.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Saves the editor project and opens it in a peerless preview table in a new tab. This is the editor's own "Preview" path. The new tab joins this agent session by itself through a one-time hand-off, so you need no second pairing code. The call returns the new tab's id.

When to use it. Whenever you want to see the game run: after building a setup, after changing a script. Then drive the preview with the table_* tools, passing the returned tabId as their tab argument (or select it with session_select_tab).

Class. W with editor:write. Requires the project lease, because it saves.

Gotchas.

• The preview records nothing: no play time, no stats, no chips. It is a peerless table with role offline.
• If the browser blocks the pop-up, or the save fails, the call answers internal; see diagnostics_get.
• If the preview opened but did not pair within the wait, the call answers timeout with the URL; the tab may still appear in session_list_tabs a moment later.
• A room pack's decor does not render in the preview yet; screenshot room packs in the editor viewport.
• The preview is a separate tab. A browser only renders the visible tab, so screenshot_viewport on a preview in a background tab fails until the user brings it to the front.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "tabId": "tab_Zr7bN2cW5yHe",
    "url": "/table?preview=9b1d6f2a-3c4e-4a7b-8f10-5e2d7c9a1b36"
  }
}

playtest_reload#

Reload play-test — Reload the preview table from the latest editor save, discarding the preview's table state. Destructive: needs confirm: true.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reloads the preview from the latest editor save. It throws away the preview's table state. It does what the preview banner's "Reload preview" does.

When to use it. After editing and saving in the editor, to see the change. Call it on the preview tab (its tab); called on the editor tab it reloads the preview window that editor opened.

Class. D: the preview's table state is thrown away, so pass confirm: true. Called on the editor tab, the first D call of the session also makes a restore point of the project.

Gotchas.

• On the preview tab this reloads the whole page. The tab reconnects with the same tab id; wait a moment before the next call, and expect a fresh table (setup positions, new shuffles).
• It re-reads the last save: call project_save in the editor first. playtest_start saves for you, this does not.
• Called on an editor tab that did not open the preview, it answers not-found and suggests passing the preview tab.

Example#

Sent to the preview tab after saving in the editor:

{
  "request": {
    "confirm": true,
    "tab": "tab_Zr7bN2cW5yHe"
  },
  "response": {
    "reloaded": true
  }
}

playtest_stop#

Stop play-test — Close the preview table tab.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Closes the preview tab.

When to use it. When play-testing is done. The editor tab is unaffected.

Class. W with editor:write.

Gotchas.

• Called on the editor tab it closes the preview window that editor opened; otherwise call it on the preview tab.
• After it, the preview's tab id is gone from session_list_tabs.

Example#

A request and the structured result it returns.

{
  "request": {
    "tab": "tab_Zr7bN2cW5yHe"
  },
  "response": {
    "closed": true
  }
}

table_wait_settled#

Wait until settled — Wait until the preview or live table is at rest, or the timeout passes. On the host (or solo/preview) every body must sleep; on a player or spectator tab this user's sent intents must be answered and the host's snapshots must show no movement for a quiet window.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Waits until the table is at rest, or until the timeout passes. Then it reports how long it waited. It also says how many of this tab's intents still have no answer, and how much is still moving.

When to use it. After a roll, a drop or a spawn, before reading positions or taking a screenshot. On a peerless preview held by table_step_physics, it advances the held simulation itself.

Class. R.

Gotchas.

• What "at rest" means depends on the role. Only the host simulates. On the host (and a solo or preview table) every dynamic body must be asleep. On a player's or spectator's tab the wait watches what the tab receives instead: every intent it sent the host must have been answered by a host snapshot, and the host's snapshots must have shown no object moving, appearing or disappearing for about 1.2 seconds, counted from the later of the last movement and the last intent sent. So a player's wait always lasts at least that long after an action.
• pendingIntents counts this tab's intents that no host snapshot has answered yet; it is always 0 on the host, which applies its own. An intent the host refused silently stops counting after 5 seconds.
• awakeBodies on the host is the bodies not asleep; on a player's or spectator's tab it is the number of objects that moved in the latest host snapshot that moved anything.
• While a table or model is still loading on the host, the simulation is held and the wait is refused at once (settled: false, waitedMs: 0, with a physics warning in the diagnostics).
• settled: false after the timeout is not an error: something is still moving (a spinning die, a sliding stack).
• table_roll runs this wait itself before it reports faces.

Example#

A request and the structured result it returns.

{
  "request": {
    "timeoutMs": 5000
  },
  "response": {
    "settled": true,
    "waitedMs": 1240,
    "pendingIntents": 0,
    "awakeBodies": 0
  }
}

table_step_physics#

Step physics — Freeze the peerless preview table's simulation and advance it by N fixed steps. Refused in live rooms.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Freezes the peerless preview's physics and moves it forward by exactly steps fixed steps of dt seconds. Then it sends one snapshot. The world stays frozen after that unless you pass resume: true.

When to use it. For repeatable play-tests: step a roll or a drop by a known amount and assert on the result.

Class. W with table:play.

Gotchas.

• Peerless only. In a live room it is refused (role-denied): freezing a shared table would stall everyone.
• The world stays held after the call. Resume with resume: true on your last step; while held, table_wait_settled advances the simulation itself.
• There is no random seed: shuffles and host randomness are still private. Assert invariants, not outcomes.
• If the physics world fails mid-step, the call reports internal and a physics diagnostic.

Example#

Two seconds of simulation at 60 steps per second, then hand the clock back:

{
  "request": {
    "steps": 120,
    "dt": 0.016666666666666666,
    "resume": true
  },
  "response": {
    "stepped": 120,
    "simulatedMs": 2000
  }
}

table_assert#

Assert table state — Check declarative assertions against the preview or live table (counts by kind, field values, in zone, face up or down, owned by seat) and report pass or fail per assertion.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Checks what you expect against your seat's view of the table. You list the checks. It reports pass or fail for each one, with a sentence and the actual value. The checks are count, field, in-zone, face and owned-by. count counts by kind, zone, owner seat or label, with equals, min and/or max. field tests that a dotted path on one object equals a value. face is up or down, and owned-by takes a seat index.

When to use it. As the check at the end of a play-test step. One call can hold up to 100 assertions; passed is true only if all pass.

Class. R.

Gotchas.

• A count needs at least one of equals, min or max.
• field paths read the object as the snapshot stores it (position.x, metadata.score, tags.0, faceDown), not the projected names of table_snapshot; numbers compare within 1e-9.
• Objects hidden from your seat fail as "not in your view"; the wording never reveals whether they exist.
• Zone membership is by position on the table plane, from the zone outlines everyone can see.
• untrustedDetail and untrustedActual can quote object data (labels, tags, metadata), so they are untrusted fields.

Example#

Two checks after a deal; the second one fails:

{
  "request": {
    "assertions": [
      {
        "type": "count",
        "kind": "card",
        "ownerSeat": 0,
        "equals": 5
      },
      {
        "type": "face",
        "entityId": "obj_13",
        "faceUp": true
      }
    ]
  },
  "response": {
    "passed": false,
    "results": [
      {
        "index": 0,
        "passed": true,
        "untrustedDetail": "Counted 5.",
        "untrustedActual": 5
      },
      {
        "index": 1,
        "passed": false,
        "untrustedDetail": "obj_13 is face down, expected face up.",
        "untrustedActual": false
      }
    ]
  }
}

table_reset#

Reset table — Reset the table to its setup. On the peerless preview it is destructive and needs confirm: true; resetting a live room as host asks the user in the tab.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Resets the table to the state the game started in, like the table's Reset. On a play-test preview it reloads the preview from the last editor save.

When to use it. To start a play-test over, or, as host, when the user asks to restart a live game.

Class. D on a peerless table (pass confirm: true), escalating to H in a live room: resetting affects everyone, so the user confirms in the tab. Only the host can reset.

Gotchas.

• Reset needs the start-of-game state the table captured; a table where the game was not started answers disabled. A preview uses its own reload instead, which reloads the tab.
• Players and spectators get role-denied.

Example#

On a peerless preview this is D and needs confirm: true:

{
  "request": {
    "confirm": true
  },
  "response": {
    "reset": true
  }
}