Lobby Tools for AI Agents

These tools run a /play lobby. They create or join one and choose the game, variant and settings. They pick decks, add bots and start the game. Removing a player always waits for your click. Ranked never starts while an agent is attached.

Tools in this family#

21 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.

lobby_create#

Create lobby — Create a public multiplayer lobby on the /play hub through the normal create flow, optionally with a game picked. Changing visibility or setting a password is a separate step the user confirms.

Input

Output (structured content)

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

Creates a multiplayer lobby on the /play hub through the normal create flow, then moves the tab into it. You can also pick a game, a name, a player cap and whether spectators may join. New lobbies are public.

When to use it. To set up a multiplayer play-test or a game night the user asked for. Then share lobby_invite_link, wait for players with lobby_state, and lobby_start.

Class. W with table:play, in a lobby-surface tab (/play/tables or a lobby page).

Gotchas.

• Making the lobby friends-only or private, or giving it a password, is a separate step the user confirms: lobby_settings_set.
• The user must be signed in (role-denied otherwise).
• If the lobby was created but maxPlayers or spectatorsAllowed were refused, the error carries the new roomId and lobbyUrl: the lobby exists.
• The lobby itself records no play; the table session after Start follows the usual rules, and any agent time in a session means it earns no chips, progression or stats.

Example#

A request and the structured result it returns.

{
  "request": {
    "modId": "sam-plays.harbour-merchants",
    "name": "Harbour night",
    "maxPlayers": 4
  },
  "response": {
    "roomId": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
    "lobbyUrl": "https://diceytable.com/play/lobby/3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75"
  }
}

lobby_list_open#

List open lobbies — List open lobbies: this user's own (from their tables list) and public ones (from the /play hub's tables page).

Input

Output (structured content)

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

Lists open lobbies the way the tables page shows them. The user's own open lobbies come first, then public ones. Pass query to search them.

When to use it. To find a lobby to join with lobby_join.

Class. R.

Gotchas.

• hasPassword is known only for the user's own lobbies (yours: true). The public listing does not publish it, so on other people's lobbies it is null, meaning unknown, never a guess. A lobby with a password cannot be joined with lobby_join.
• The maximum player count is not listed: neither listing publishes it. Read it from lobby_state once in the lobby.
• players is the number of people in the lobby now, from the public listing when the lobby appears there. A private lobby of the user's own that the public listing does not show may report 0.
• Lobby and game names are other people's text (untrustedName, untrustedGame).

Example#

One of the user's own lobbies and someone else's public one:

{
  "request": {
    "query": "harbour"
  },
  "response": {
    "lobbies": [
      {
        "roomId": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
        "untrustedName": "Harbour night",
        "untrustedGame": "Harbour Merchants",
        "players": 1,
        "hasPassword": false,
        "yours": true,
        "visibility": "public"
      },
      {
        "roomId": "b72f09e4-51c3-4e8d-9a0b-6d2c4f7e1a93",
        "untrustedName": "Harbour league",
        "untrustedGame": "Harbour Merchants",
        "players": 3,
        "hasPassword": null,
        "yours": false,
        "visibility": "public"
      }
    ],
    "total": 2
  }
}

lobby_join#

Join lobby — Join a /play lobby by room id, invite code (public lobbies only) or invite link, as player or spectator. A lobby with a join password cannot be joined from the lobby page, by the user or an agent.

Input

Output (structured content)

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

Joins a lobby by room id, invite code or invite link, as a player or a spectator. Player is the default. The tool opens the lobby page and waits up to 15 seconds for the roster to show the user.

When to use it. When the user wants to play in someone's lobby, or to bring a second paired browser into your own for a multiplayer test.

Class. W with table:play.

Gotchas.

• Password-protected lobbies cannot be joined here. The lobby page never sends a join password, for the user or an agent, so such a lobby refuses the join. There is no password argument; the input is strict, so passing one fails argument validation instead of being ignored.
• code is the room's short invite code (the first characters of its id), and only public open lobbies are searched for it; use the link or room id otherwise.
• Asking for spectator in a lobby closed to spectators leaves the user as a player and answers disabled.
• Give exactly one of roomId, code or link.

Example#

A request and the structured result it returns.

{
  "request": {
    "link": "https://diceytable.com/play/lobby/3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75"
  },
  "response": {
    "roomId": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
    "role": "player"
  }
}

lobby_state#

Lobby state — Read the /play lobby: roster (names, roles, ready, deck selections, AI agent badge, Player Trust tier, each member's device tier), the seated game bots (with any game deck chosen for them), settings (including the variant that will be played), picked game with its variants, setup options and declared bots, requirement status, and Ranked (offered, on, and what blocks a ranked Start).

Input

Output (structured content)

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

Reads the lobby the tab shows. For each member you get their name, role, ready flag and deck picks. You also see whether an AI agent is active for them, who owns the room, their Player Trust tier and what their device measured as. The result also covers the seated game bots and the settings. It includes the picked game with its variants, setup options and the bots it offers. For the user, it gives each requirement's status and the members still missing required choices. Last, it shows the Ranked switch with what blocks a ranked Start, and whether the owner can start.

When to use it. After every lobby action, and while waiting for players. It is the lobby's table_snapshot.

Class. R.

Gotchas.

• agentActive is attested by DiceyTable's server from the member's own agent session; nobody can set it by message.
• startable is only ever true for the owner, before Start, with no shortfalls, no deck pairing clash, no bot problem and, while Ranked is on, no ranked blocker.
• A deck requirement with a pairing rule carries distinctBy: no two decks at the table (players' and bots') may share a deck-icon value (a side, in a two-sided game) except the values in untrustedExcept; untrustedLabels names the values. While two decks clash, untrustedPairingProblem gives the Start control's sentence and Start is refused. pools includes game when the game ships its own decks.
• Each seated bot's deck is the game deck the owner chose for it with lobby_bot_set_deck (deckId, untrustedLabel, and untrustedIconValue, its side), or null when the game's script chooses.
• Member names, deck captions, requirement labels, game, variant and bot names and notices are untrusted text.
• setupOptionValues is included only for the owner.
• A requirement whose game declares a deck icon (deckIcon in the manifest) adds, for the user's own chosen deck, untrustedSelectionIconValue (the mapped value, e.g. a side) and selectionIconImage (the repo-relative image the lobby draws beside it). Both are absent when there is no icon.
• settings.variantId is the variant the lobby will start, as the server resolved it: the owner's choice, else the game's first variant, else null for a game that declares none. Every member reads the same id.
• game.variants lists what the game declares, in order (the first is the default): id, the untrusted name, the variant's own players range when it has one, rulesEnforced (its script enforces the rules and decides the result), rankingOffered (it may be played ranked) and, for a game with bots, seatsBots (the bots its scripts play). The owner changes it with lobby_set_variant.
• ranked is the server's view of the Ranked switch: offered (the variant offers ranked play), on, and while it is on, blockers (each member who would stop a ranked Start, by memberId = their userId, with reasons) and tableBlockers. Member reasons: anonymous, trust-locked, agent-active, client-outdated, pair-cap (with pairWith), self-hosted-cap, spectator-seat. Table reasons: too-few-sides, bots-not-ranked, variant-not-ranked, host-trust-locked. Agent play is never ranked: while this agent is attached the user is listed with agent-active, so a ranked Start is refused. The owner turns Ranked on or off with lobby_set_ranked.
• Each member's trustTier is their public Player Trust badge (new, good, trusted, caution or locked), filled by the server. locked pauses that member's ranked play only. It is absent when the server reports none.
• bots lists the game bots the owner has seated. A bot is not a member: it has no account, and it is addressed by its peerId (bot:…), which lobby_bot_remove and lobby_bot_set_difficulty take. seat: null means the first open seat after the players. Bots and players share the game's seats. displayName is the first name the lobby shows for the bot, chosen to avoid the members' names; it is cosmetic and can change, so identify a bot by peerId and what it is by botId, difficultyId and modelId (AI bots only). modelId, minTier and modelBytes are those of the model the bot plays with at its difficulty: a difficulty may name its own model.
• game.bots lists the bots the game offers, for lobby_bot_add: kind is scripted or ai, minTier is the device tier the host needs (none for a scripted bot), and modelBytes is the size of the model every host downloads, both at the bot's default difficulty. Each of its difficulties carries the modelId it plays with (its own, else the bot's default) and that model's minTier. game.botsCanSeeHiddenInformation is true when the game declares read-hidden-information: its bots run on the host, which holds the whole table.
• Each member's hardwareTier is what their own device reported (none, cpu-basic, cpu-fast or gpu), and probeVersion is 0 until it has reported. It is the member's own claim and is advisory. Only the owner's matters for Start, because the bots run on the owner's device. A lobby for a game without bots shows none and 0 for everyone: nothing is tested until a bot is on offer.
• startBlockedBy appears, for the owner only, when the seated bots would make lobby_start refuse as far as the tab can tell: bot-tier-unmet (the owner's device is below a seated AI bot's minTier, or has not reported a test yet) or bot-seats-exceed-players (players plus bots outnumber the seats). The server makes the final decision.
• rematch appears in a rematch lobby: the one the players of a finished Fully scripted game reach with Return to lobby. It is owned by whoever was that table's host, and for its first 30 seconds only that table's players can join. awaiting lists the ones not back yet (the lobby greys them out), left the ones who chose Exit, and secondsLeft the time left when the tab last heard from the server. It is absent for an ordinary lobby and once the 30 seconds are up.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "roomId": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
    "isOwner": true,
    "phase": "lobby",
    "connection": "open",
    "members": [
      {
        "userId": "u_sam",
        "untrustedName": "Sam",
        "role": "player",
        "ready": true,
        "isOwner": true,
        "isSelf": true,
        "agentActive": true,
        "untrustedSelections": [
          "Merchant fleet · 40 cards"
        ],
        "hardwareTier": "cpu-fast",
        "probeVersion": 1,
        "trustTier": "good"
      },
      {
        "userId": "u_ana",
        "untrustedName": "Ana",
        "role": "player",
        "ready": false,
        "isOwner": false,
        "isSelf": false,
        "agentActive": false,
        "untrustedSelections": [],
        "hardwareTier": "cpu-basic",
        "probeVersion": 1,
        "trustTier": "trusted"
      }
    ],
    "bots": [
      {
        "peerId": "bot:k3v9x2m7q1ta",
        "botId": "harbour-master",
        "displayName": "Dmitri",
        "untrustedLabel": "Harbour Master",
        "modelId": "harbour-net",
        "kind": "ai",
        "difficultyId": "club",
        "seat": null,
        "minTier": "cpu-fast",
        "modelBytes": 1800000
      }
    ],
    "settings": {
      "untrustedDisplayName": "Harbour night",
      "visibility": "public",
      "maxPlayers": 4,
      "spectatorsAllowed": true,
      "seatSelection": "choice",
      "variantId": "short-voyage"
    },
    "game": {
      "modId": "sam-plays.harbour-merchants",
      "untrustedName": "Harbour Merchants",
      "variants": [
        {
          "id": "short-voyage",
          "untrustedName": "Short voyage",
          "rulesEnforced": false,
          "rankingOffered": false,
          "seatsBots": [
            "dockhand",
            "harbour-master"
          ]
        },
        {
          "id": "long-voyage",
          "untrustedName": "Long voyage",
          "players": {
            "min": 3,
            "max": 6
          },
          "rulesEnforced": true,
          "rankingOffered": true,
          "seatsBots": [
            "dockhand",
            "harbour-master"
          ]
        }
      ],
      "bots": [
        {
          "id": "dockhand",
          "untrustedLabel": "Dockhand",
          "kind": "scripted",
          "minTier": "none",
          "modelBytes": null,
          "difficulties": [],
          "defaultDifficultyId": null
        },
        {
          "id": "harbour-master",
          "untrustedLabel": "Harbour Master",
          "kind": "ai",
          "minTier": "cpu-fast",
          "modelBytes": 1800000,
          "difficulties": [
            {
              "id": "easy",
              "untrustedLabel": "Easy",
              "modelId": "harbour-net",
              "minTier": "cpu-fast"
            },
            {
              "id": "club",
              "untrustedLabel": "Club",
              "modelId": "harbour-net",
              "minTier": "cpu-fast"
            }
          ],
          "defaultDifficultyId": "club"
        }
      ],
      "botsCanSeeHiddenInformation": false,
      "setupOptions": []
    },
    "requirements": [
      {
        "id": "fleet",
        "untrustedLabel": "Your fleet deck",
        "required": true,
        "appliesToYou": true,
        "satisfied": true,
        "untrustedSelection": "Merchant fleet · 40 cards",
        "pools": [
          "mine",
          "community"
        ]
      }
    ],
    "ranked": {
      "offered": false,
      "on": false,
      "blockers": [],
      "tableBlockers": []
    },
    "shortfalls": [
      {
        "userId": "u_ana",
        "untrustedName": "Ana",
        "untrustedMissing": [
          "Your fleet deck"
        ]
      }
    ],
    "startable": false
  }
}

lobby_set_game#

Pick lobby game — Pick the game for the /play lobby (room owner only). Reports what the change cleared: the seat cap, setup options, the variant choice, and any seated bots the new game does not declare (botsCleared).

Input

Output (structured content)

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

Picks the lobby's game (owner only). It sends the same request as the owner's game chooser.

When to use it. After lobby_create without a game, or to switch games before Start.

Class. W with table:play.

Gotchas.

• Changing the game can clear settings that no longer fit: the result reports maxPlayersCleared, packagePinsCleared, the cleared setupOptionKeysCleared, and variantCleared when the variant chosen for the old game is not one the new game declares (the lobby then starts the new game's first variant; choose another with lobby_set_variant).
• Seated game bots belong to the game that declares them. botsCleared lists the peerIds of the bots the change removed, because the new game does not declare them or has no seat for them. It is empty when none were removed. Add the new game's bots with lobby_bot_add.
• Non-owners get role-denied, and after Start the lobby takes no changes (invalid).

Example#

A request and the structured result it returns.

{
  "request": {
    "modId": "sam-plays.harbour-merchants"
  },
  "response": {
    "modId": "sam-plays.harbour-merchants",
    "maxPlayersCleared": false,
    "packagePinsCleared": false,
    "setupOptionKeysCleared": [],
    "variantCleared": false,
    "botsCleared": []
  }
}

lobby_set_variant#

Set game variant — Choose which of the picked game's declared variants the /play lobby will start (room owner only, before Start). lobby_state lists them under game.variants (each with rulesEnforced, rankingOffered and, when known, seatsBots). Choosing a variant removes every seated bot it cannot seat — one whose scripts do not register that bot's handler (botsCleared).

Input

Output (structured content)

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

Chooses which of the picked game's variants the lobby will start (owner only). It sends the same request as the owner's Variant dropdown. A variant is the same game set up another way: another board size, a larger table, or a fully scripted version that can be played ranked. The platform applies the variant before any script runs.

When to use it. When lobby_state's game.variants lists more than one and the lobby should not start the first. Read the ids there; settings.variantId is the one in play.

Class. W with table:play.

Gotchas.

• The id must be one the game declares. Anything else is invalid, with the declared ids in variantIds.
• A variant can seat a different number of people than the game's headline range. If the lobby's seat cap no longer fits, the server clears it and the result says maxPlayersCleared: true.
• For the same reason a variant can have no seat left for a seated game bot, and a bot is played only by a variant whose scripts register it (game.variants[].seatsBots). botsCleared lists the peerIds of the bots the server removed; it is empty when none were.
• A variant without ranked play (rankingOffered: false) turns the lobby's Ranked switch off.
• Asking for the variant already in play makes no request and returns maxPlayersCleared: false with no bots cleared.
• The game must have loaded (busy otherwise). Non-owners get role-denied, and after Start the variant is locked (invalid).
• A variant is not a setup option: lobby_setup_options_set answers the game's own questions, which the variant's scripts read.

Example#

A request and the structured result it returns.

{
  "request": {
    "variantId": "long-voyage"
  },
  "response": {
    "variantId": "long-voyage",
    "maxPlayersCleared": false,
    "botsCleared": []
  }
}

lobby_set_ranked#

Set Ranked — Turn the /play lobby's Ranked switch on or off (room owner only, before Start; locked once the game starts). Only while lobby_state ranked.offered is true. Turning it ON needs a Player or Game Master membership (refused ranked-requires-membership otherwise; turning it off never is). Turning it on starts nothing: lobby_start then refuses while ranked.blockers or ranked.tableBlockers is not empty. Agent-driven play is never ranked: a ranked Start is refused while any seated player has an AI agent attached (agent-active), and an agent attaching mid-match voids that match.

Input

Output (structured content)

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

Turns the lobby's Ranked switch on or off (owner only). It sends the same request as the owner's Ranked checkbox. With Ranked on, the match the lobby starts counts toward the game's Rankings. It changes every player's Score.

When to use it. Only when the user asks for a ranked match, and only while lobby_state shows ranked.offered: true. The game's author decides which variants offer Ranked.

Class. W with table:play.

Gotchas.

• Agent play is never ranked. While this agent is attached, the user is a ranked blocker (agent-active), so a ranked lobby_start is refused until the user disconnects the agent. An agent that attaches during a ranked match voids it. So the agent can prepare a ranked lobby, but a human starts and plays it.
• Ranked play needs a Player or Game Master membership. Turning Ranked on is refused for an owner without one, and at Start every seated human and the host must have one (membership-required, host-membership-required). A free account can still play the same game unranked.
• Turning Ranked on starts nothing. Read lobby_state's ranked.blockers and ranked.tableBlockers for what still stops a ranked Start: a player who is not signed in, has no Player or Game Master membership, has an agent attached, needs to refresh, has played the daily ranked limit with the same person, or is trust-locked; too few sides; bots in a variant that does not rank them.
• Asking for the value the switch already shows makes no request and returns changed: false.
• Refusals carry the server's code in detail.code: not-room-owner (role-denied), ranked-locked after Start (invalid), ranked-not-offered (disabled; also refused before any request when ranked.offered is false), ranked-requires-membership when the user has no Player or Game Master membership (disabled), trust-locked when ranked play is paused for the user's account (disabled; unranked play is unaffected), and rankings-unavailable (busy). Turning Ranked off is never refused before Start.
• Changing the variant to one without Ranked turns the switch off.
• Ranked is its own switch: lobby_settings_set does not change it.

Example#

Example: turning Ranked on, then reading lobby_state for anything that still blocks a ranked Start.

{
  "request": {
    "ranked": true
  },
  "response": {
    "ranked": true,
    "changed": true
  }
}

lobby_setup_options_set#

Set game setup options — Set the picked game's setup options in the /play lobby (room owner only).

Input

Output (structured content)

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

Sets the picked game's setup options (owner only). The tool checks them with the same rules the owner's form and the server use. Your values are merged over the stored answers and the game's defaults before that check.

When to use it. When the game declares options (variant rules, board size) that should be chosen before Start. Read the option keys from lobby_state's game.setupOptions.

Class. W with table:play.

Gotchas.

• The game must have loaded (busy otherwise).
• Invalid values are refused with each key's problem; nothing is saved.

Example#

A request and the structured result it returns.

{
  "request": {
    "values": {
      "tideLength": 8,
      "variant": "short"
    }
  },
  "response": {
    "applied": [
      "tideLength",
      "variant"
    ]
  }
}

lobby_settings_set#

Set lobby settings — Set /play lobby settings (room owner only): name, max players, spectators and seat selection. Changing visibility or the join password asks the user in the tab. Ranked is not a setting here: use lobby_set_ranked.

Input

Output (structured content)

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

Changes the lobby's settings (owner only). The room name, the player cap, whether spectators may join and seat selection are ordinary writes. Visibility (public, friends or private) and the join password change who can get in.

seatSelection decides how players get their seats at the table: choice (the default) lets each player pick a free seat; random deals each arriving player a random free seat that only the host can change.

When to use it. Before inviting people, or when the user asks to open or close the lobby.

Class. W, escalating to H when visibility or password is present: the user confirms the access change in the tab. password: null removes the password.

Gotchas.

• Changes are applied in order (name, cap and spectators; then visibility; then password). If one is refused, the error lists what was already applied.
• A password must be 4 to 128 characters.
• Friends-only and private lobbies need a membership the server checks; it names the reason if it refuses.
• The name cannot be blank.
• seatSelection is fixed once the game has started: changing it then is refused (seat-selection-locked). Sending the value it already has is not a change and is accepted.
• Ranked is not one of these settings. Turn it on or off with lobby_set_ranked.

Example#

Name and seat cap are W. Adding visibility or password here would raise the in-tab dialog:

{
  "request": {
    "name": "Harbour night (4 seats)",
    "maxPlayers": 4
  },
  "response": {
    "applied": [
      "name",
      "maxPlayers"
    ]
  }
}

lobby_requirement_options#

Lobby deck options — List the decks this user can pick for a /play lobby requirement, from their own, community, database or game pools. The game pool is the decklists the game ships itself (manifest.gameDecks), each credited to who built it; picking one imports nothing. eligible is false (with untrustedProblem) for a deck the picker greys out, including one that would share a side with a deck someone else at the table holds when the requirement declares distinctBy.

Input

Output (structured content)

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

Lists the decks the user can pick for one of the game's lobby requirements. The decks come from one pool: mine (their saved decks), community (public decks for this game), database (the game's deck database) or game (the decks the game ships itself).

When to use it. Before lobby_pick_deck. Requirements and the pools each offers are in lobby_state.

Class. R.

Gotchas.

• mine and community rows carry eligible and, when not, untrustedProblem (the deck fails the requirement's format or size). Database rows carry importsPrivateCopy: true.
• game rows are the game's own decks (its "Game decks" tab), in the tab's order: starter decks first. Each carries level (novice, veteran or competitive) and cards, and, as the game wrote them, untrustedFormat, untrustedFormatPool, untrustedDescription and untrustedCredit (who built the deck and where it comes from). The pool exists only when the game names a decks file, and only for a requirement that offers it.
• When the requirement has a pairing rule (distinctBy, listed in lobby_state), a deck on the same side as one somebody else at the table holds is eligible: false with untrustedProblem, in every pool. A database row is checked by its side before anything is imported; a saved deck's side is worked out from its cards, and one whose side stays unknown (mixed sides, unreadable catalogue) is not refused here.
• A requirement that does not apply to the user's seat (spectators bring nothing) is refused.
• Captions include deck names and other users' names: untrusted.
• When the game declares a deck icon (deckIcon in the manifest), an option carries iconImage — the repo-relative image the lobby draws beside it (the mapped image, else the game's default unless that default is itself one of the mapped images) — and, when the deck has a mapped value, untrustedIconValue (e.g. a side). Database rows read the value from the provider row's declared field; saved decks through their format id or, for any other field, from their cards (the same derivation the picker runs). A deck whose value is unknown has no untrustedIconValue and may have no iconImage. Neither is ever a URL.

Example#

A request and the structured result it returns.

{
  "request": {
    "requirementId": "fleet",
    "pool": "mine"
  },
  "response": {
    "options": [
      {
        "id": "deck_8812",
        "untrustedCaption": "Merchant fleet · 40 cards",
        "pool": "mine",
        "eligible": true
      },
      {
        "id": "deck_8813",
        "untrustedCaption": "Pirate raiders · 25 cards",
        "pool": "mine",
        "eligible": false,
        "untrustedProblem": "This requirement needs at least 40 cards."
      }
    ],
    "total": 2
  }
}

lobby_pick_deck#

Pick lobby deck — Pick a deck for a /play lobby requirement. As in the UI, a database pick imports a private copy of the deck into the user's account; a game pick (one of the game's own decks) imports nothing. Refused (invalid) for a deck the picker greys out, including one whose side another deck at the table already holds when the requirement declares distinctBy.

Input

Output (structured content)

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

Picks a deck for a lobby requirement, as the picker does. Then it waits for the roster to show the choice.

When to use it. When the game requires each player to bring a deck.

Class. W with table:play.

Gotchas.

• A database pick imports a private copy of that list into the user's saved decks, exactly as in the UI; importedDeckId names it.
• A game pick (one of the game's own decks; optionId is the deck's id) imports nothing: the roster records a reference to the game's deck, and the table loads the list from the game's file.
• A deck from mine, community or game that fails the requirement is refused with the reason.
• When the requirement has a pairing rule (distinctBy), a deck on the same side as one somebody else at the table holds (a player's or a bot's) is refused invalid with detail.code lobby-pairing-conflict, before any import. The message names other people, so it is untrusted.
• Picks are only possible before Start.

Example#

A request and the structured result it returns.

{
  "request": {
    "requirementId": "fleet",
    "pool": "mine",
    "optionId": "deck_8812"
  },
  "response": {
    "picked": true
  }
}

lobby_set_ready#

Set ready — Set this user's ready state in the /play lobby.

Input

Output (structured content)

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

Sets the user's ready flag in the lobby and waits for the roster to confirm it.

When to use it. When the user is ready to play, after required deck picks.

Class. W with table:play.

Gotchas.

• Setting the value it already has does nothing and succeeds.
• If the lobby refuses (the screen shows a notice), the error quotes the notice.

Example#

A request and the structured result it returns.

{
  "request": {
    "ready": true
  },
  "response": {
    "ready": true
  }
}

lobby_set_role#

Set lobby role — Switch this user between player and spectator in the /play lobby.

Input

Output (structured content)

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

Switches the user between player and spectator in the lobby. Then it waits for the roster to confirm it.

When to use it. To watch rather than play, or to take a seat.

Class. W with table:play.

Gotchas.

• A lobby closed to spectators refuses spectator with disabled.
• Only before Start.

Example#

A request and the structured result it returns.

{
  "request": {
    "role": "spectator"
  },
  "response": {
    "role": "spectator"
  }
}

lobby_invite_link#

Lobby invite link — Get the /play lobby's share link and its room's invite code. Sending invites to friends is not available to agents.

Input

Output (structured content)

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

Returns the lobby's share link and its room's invite code.

When to use it. To give the user a link to send to friends. Sending invites to friends is not available to agents.

Class. R.

Gotchas.

• code is the room's invite code: the first 8 characters of its id. lobby_join finds a lobby by code only while it is public; for a private lobby, share the url.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "url": "https://diceytable.com/play/lobby/3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
    "code": "3e8a1c5d"
  }
}

lobby_kick#

Remove lobby member — Requires the user's confirmation in the DiceyTable tab. Remove a member from the /play lobby (room owner only).

Input

Output (structured content)

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

Removes a member from the lobby (owner only) and blocks them from the table the lobby becomes. The owner can let them back in from the lobby's Removed list.

When to use it. Only when the user asks to remove someone.

Class. H: the user confirms in the tab, and the dialog names the member. No scope skips it.

Gotchas.

• The owner cannot remove themselves (use lobby_leave).
• userId comes from lobby_state's members; an id not in the lobby is not-found.

Example#

Only after the owner confirmed in the tab:

{
  "request": {
    "userId": "u_ana"
  },
  "response": {
    "kicked": true
  }
}

lobby_start#

Start game — Start the game from the /play lobby (room owner only). If lobby requirements are unmet, returns the unmet list instead; if Ranked is on and something blocks a ranked match, returns rankedRefusal (the blockers, as lobby_state ranked lists them); if the seated bots hold it up, returns botRefusal. A ranked Start is always refused while an AI agent is attached to a seated player, the user included (agent-active): turn Ranked off to start.

Input

Output (structured content)

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

Starts the game from the lobby (owner only). If required lobby choices are missing, it returns started: false and the unmet list instead of starting. If Ranked is on and something blocks a ranked match, it returns started: false and rankedRefusal. If the seated game bots hold it up, it returns started: false and botRefusal.

When to use it. When lobby_state shows startable: true.

Class. W with table:play.

Gotchas.

• unmet lists, per member and requirement, what is missing. Member names are left out (they are untrusted); read them from lobby_state.
• rankedRefusal is set when Ranked is on and the server refused a ranked Start. With reason: "ranked-requirements-unmet", blockers and tableBlockers list every problem, exactly as lobby_state's ranked does (member names untrusted). With reason: "rankings-unavailable" the ranked checks could not be read: try again, or turn Ranked off.
• Agent play is never ranked. While this agent is attached, the user is a blocker (agent-active), so a ranked Start is always refused here. Turn Ranked off with lobby_set_ranked to start unranked, or leave the ranked Start to the user after they disconnect the agent. An agent that attaches during a ranked match voids it.
• botRefusal is set when the server refused over the lobby's bots. Its reason is one of two:
  • bot-tier-unmet: the owner is the host, so the bots run on the owner's device, and it is below what a seated AI bot needs. required and actual are the two tiers. Remove the bot with lobby_bot_remove, add one that needs less or a scripted one, or re-test the device (the lobby.bots.retest-device action) and try again.
  • bot-seats-exceed-players: players plus bots outnumber the seats (playerCap, humanPlayers, bots). Remove a bot, or have a player spectate.
• When botRefusal.probeVersion is present, the device was never the problem: the tab has not reported a hardware test, or reported an outdated one, and a lobby with any bot (a scripted one too) needs it. Re-test the device or reload the page. Do not remove the bot for this.
• Bot and model names are left out of botRefusal (they are untrusted); read the seated bots from lobby_state. Its startBlockedBy reports the same two problems before Start is pressed.
• When the game starts, tableUrl is the live table's link (/table?room=<roomId>). The lobby tab moves there by itself; follow it with page_info and session_list_tabs.
• From then on the table tools apply, and every player sees the AI agent badge on the user.

Example#

Refused because a required choice is missing:

{
  "request": {},
  "response": {
    "started": false,
    "unmet": [
      {
        "requirementId": "fleet",
        "userId": "u_ana",
        "message": "This member has not made a required lobby choice yet."
      }
    ]
  }
}

lobby_bot_add#

Add lobby bot — Add one of the picked game's declared bots to the /play lobby (room owner only, before Start). lobby_state lists them under game.bots; a bot takes one of the player seats. Refused (bot-variant-no-handler) when the lobby's variant does not seat that bot — a bot is played by a scene script that registers its handler, and which scripts a variant attaches is per-variant scene data; pick a variant that seats it (game.variants[].seatsBots) with lobby_set_variant first.

Input

Output (structured content)

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

Adds one of the picked game's bots to the lobby (owner only). It sends the same request as the owner's Add bot dialog. A bot is an opponent the game declares. It is either scripted, or it thinks with an AI model that the host's device runs. It takes one of the game's player seats.

When to use it. When the user wants to play against a bot, or a lobby needs a seat filled. Read the choices first: lobby_state's game.bots lists every bot the game offers, with its kind, its difficulties, and the minTier an AI bot needs from the host's device.

Class. W with table:play.

Gotchas.

• botId must be one the game declares, and difficultyId one of that bot's own. Anything else is invalid, with the valid ids in botIds or difficultyIds, and no request is made.
• Leave difficultyId out to get the bot's own default; the result reports the difficulty it will play at (null for a bot with no difficulties).
• There is no seat argument. The lobby does not know which seats the game's table has, so every bot is added on "auto": the first open seat after the players. seat in the result is null.
• The server decides whether the bot may sit. It refuses one bot too many, and a lobby with no seat left for it (players and bots share the game's seats). Its sentence may name the bot, so the error text is untrusted.
• A bot is played by a scene script that registers it, and which scripts a variant runs is that variant's own scene data. When the lobby's variant does not seat the bot (it is missing from that variant's game.variants[].seatsBots), the tool refuses with disabled and botRefusal: "bot-variant-no-handler" before any request; choose a variant that seats it with lobby_set_variant first.
• Adding an AI bot does not check the device. If the owner's device is below the bot's minTier, lobby_start is refused; lobby_state's startBlockedBy says so beforehand, and hardware_tier_get shows what the device measured.
• The game must have loaded (busy otherwise). Non-owners get role-denied, and after Start the lobby takes no changes (invalid): bots are then changed at the table.

Example#

A request and the structured result it returns.

{
  "request": {
    "botId": "club-ai",
    "difficultyId": "easy"
  },
  "response": {
    "peerId": "bot:k3v9x2m7q1ta",
    "botId": "club-ai",
    "difficultyId": "easy",
    "seat": null
  }
}

lobby_bot_remove#

Remove lobby bot — Remove one seated bot from the /play lobby (room owner only, before Start). It can be added again; no person is removed or blocked.

Input

Output (structured content)

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

Removes one seated bot from the lobby (owner only). It sends the same request as the Remove button on the bot's roster row.

When to use it. To free a seat, or to swap a bot the owner's device cannot run for one it can. It is how to clear a bot-tier-unmet or bot-seats-exceed-players refusal from lobby_start.

Class. W with table:play. Unlike lobby_kick, which removes and blocks a person and so needs the user's confirmation, this removes no one: the bot can be added again with lobby_bot_add.

Gotchas.

• peerId is the bot's own id, bot:…, from lobby_state's bots. It is not the bot's botId: a game's bot can be seated more than once, and each seat has its own peerId.
• Only a bot's id is accepted. A player's id is refused as invalid arguments, so this tool cannot remove a person.
• A peerId that is not seated is not-found.
• Non-owners get role-denied, and after Start the lobby takes no changes (invalid).

Example#

A request and the structured result it returns.

{
  "request": {
    "peerId": "bot:k3v9x2m7q1ta"
  },
  "response": {
    "removed": true
  }
}

lobby_bot_set_difficulty#

Set bot difficulty — Change how strong one seated bot plays in the /play lobby (room owner only, before Start).

Input

Output (structured content)

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

Changes how strong one seated bot plays (owner only). It sends the same request as the Difficulty dropdown on the bot's roster row.

When to use it. When the user asks for an easier or harder opponent before the game starts.

Class. W with table:play.

Gotchas.

• peerId is the seated bot's id from lobby_state's bots; difficultyId must be one of that bot's own, listed under game.bots[].difficulties. Anything else is invalid, with the valid ids in difficultyIds. A bot that declares no difficulties has none to set.
• Asking for the difficulty already in play makes no request.
• A difficulty changes how the bot plays, not what it needs. The device tier an AI bot asks of the host comes from its model, and stays the same at every difficulty.
• A peerId that is not seated is not-found. The game must have loaded (busy otherwise). Non-owners get role-denied, and after Start the lobby takes no changes (invalid).

Example#

A request and the structured result it returns.

{
  "request": {
    "peerId": "bot:k3v9x2m7q1ta",
    "difficultyId": "club"
  },
  "response": {
    "peerId": "bot:k3v9x2m7q1ta",
    "difficultyId": "club"
  }
}

lobby_bot_set_deck#

Set bot deck — Hand one seated bot one of the game's own decks in the /play lobby, or give the choice back to the game with deckId null (room owner only, before Start, unranked only). Only when a deck requirement offers the game pool; list the decks with lobby_requirement_options pool game. Refused bot-deck-ranked while Ranked is on (ranked play lets the game choose its bots' decks), bot-deck-unoffered when the game ships no decks a bot can be given, and bot-deck-pairing when the deck would share a side with a deck someone else at the table holds (distinctBy).

Input

Output (structured content)

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

Hands one seated bot one of the game's own decks, or gives the choice back to the game (owner only). It sends the same request as the Choose deck picker and the Game's choice button on the bot's roster row.

When to use it. When the user wants to play against a particular deck in an unranked game, for example a starter deck while they learn. Without a chosen deck, the game's script picks one for the bot.

Class. W with table:play.

Gotchas.

• Only a game that ships its own decks (gameDecks in the manifest) and has a deck requirement offering the game pool can give a bot a deck: a bot has no saved decks, so the game's decks are the only pool. List them with lobby_requirement_options and pool: "game"; deckId is an option's id. Otherwise the tool is refused disabled with detail.code bot-deck-unoffered.
• Unranked only. While Ranked is on the game chooses its bots' decks, so a choice is refused disabled with detail.code bot-deck-ranked. Turning Ranked on clears every bot's chosen deck.
• When the requirement has a pairing rule (distinctBy in lobby_state's requirements), the bot cannot be given a deck on the same side as a deck someone else at the table holds. That is refused invalid with detail.code bot-deck-pairing; the message names players and bots, so it is untrusted.
• deckId: null goes back to the game's choice. Asking for the deck the bot already holds, or clearing a bot that has none, makes no request and returns changed: false.
• lobby_state shows each bot's choice under bots[].deck (null for the game's choice).
• A peerId that is not seated, or a deckId the game does not ship, is not-found. Non-owners get role-denied, and after Start the lobby takes no changes (invalid).

Example#

A request and the structured result it returns.

{
  "request": {
    "peerId": "bot:k3v9x2m7q1ta",
    "deckId": "empire-gauntlet"
  },
  "response": {
    "peerId": "bot:k3v9x2m7q1ta",
    "deckId": "empire-gauntlet",
    "changed": true
  }
}

lobby_leave#

Leave lobby — Leave the /play lobby before the game starts. Leaving a live table room is not this tool.

Input

Output (structured content)

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

Leaves the lobby before the game starts, as the Leave button does. Then it waits up to 15 seconds for the lobby page to close.

When to use it. When the user no longer wants to take part.

Class. W with table:play.

Gotchas.

• After Start this tool refuses: leaving a live table is the user's decision at the table.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "left": true
  }
}