Build with an agent
Add game bots to a lobby with an agent
An AI agent can seat a game's bots in a DiceyTable lobby, set how hard they play, and check whether your device can host an AI bot before you press Start.
On this page7 sections
An agent adds a bot by calling lobby_bot_add with one of the game's bots and a difficulty. The bot takes a player seat, and the agent can change its difficulty or remove it until the game starts.
A game bot is an opponent the game's author built into the game. Some bots follow a script. Others think with an AI model that runs on the host's device, and the host is the lobby owner. Players see what that's like on Play board games against the computer.
What you'll need#
- A paired tab in a
/playlobby, as Set up a multiplayer lobby with an agent shows. - You must be the lobby owner. Only the owner adds, changes or removes bots.
- A game that offers bots. Not every game does.
Step 1: See which bots the game offers#
The agent calls lobby_state. The game's bots are listed under game.bots. Each one has a kind, either scripted or ai. An AI bot also has a minTier, the least the host's device must manage to run it:
cpu-basic: any modern device.cpu-fast: a fast processor.gpu: a graphics card.
Some games have variants, and not every variant seats every bot. game.variants says which bots each variant seats, under seatsBots. If the lobby's variant can't seat a bot, adding it fails with bot-variant-no-handler. Pick a variant that seats it first with lobby_set_variant. Switching to a variant that can't seat a bot removes that bot.
Can my computer run an AI bot?#
hardware_tier_get says what tier this device measured as, and the facts behind it. It only reads the saved result. It never downloads or runs anything.
The lobby runs the test on its own when bots are involved. On the owner's device, that happens when the game offers bots. On everyone else's, it happens once a bot is seated. The first test downloads about 14 MB, or about 41 MB when the browser can use the graphics card.
To test again, the agent presses the lobby's Re-test button with actions_invoke and the id lobby.bots.retest-device. That counts as a write, because it runs a test on your machine.
A tier is advice from your own device. It decides whether the owner may press Start with an AI bot seated. It also helps choose who hosts next if the host leaves. It never stops anyone from joining.
Step 2: Seat the bot#
- The agent calls
lobby_bot_addwith abotIdfromgame.bots. It can add adifficultyId, or the bot's default is used. - Bots and players share the game's seats. A full table has no room for a bot.
lobby_statenow lists the bot underbots, with itspeerId. The next two tools take that id.
| Tool | What it does |
|---|---|
lobby_bot_set_difficulty |
Changes how hard a seated bot plays |
lobby_bot_set_deck |
Gives a seated bot one of the game's own decks, or hands the choice back to the game |
lobby_bot_remove |
Removes a seated bot. No person is removed, so it needs no confirmation |
Choose the bot's deck#
Some card games ship their own decks. In an unranked game, the owner can pick which one a bot plays. The agent lists them with lobby_requirement_options and pool: "game", then calls lobby_bot_set_deck with the bot's peerId and a deck's id. Passing deckId: null lets the game choose again.
A game played side against side can forbid two decks on the same side. lobby_state shows that rule as distinctBy on the deck requirement. A deck that would clash is refused with bot-deck-pairing. In ranked play the game always chooses its bots' decks, so the tool is refused with bot-deck-ranked.
Step 3: Start the game#
When the owner's agent calls lobby_start, the bots can hold it up. Start then returns botRefusal with one of two reasons:
bot-tier-unmet: your device is below what a seated AI bot needs.bot-seats-exceed-players: players plus bots are more than the seats.
lobby_state warns about both ahead of time, under startBlockedBy.
Once the game is running, the host's agent can still manage bots at the table. table_bots_list shows each bot's seat, difficulty, and whether it's playing or paused. table_bots_set adds or changes one, and table_bots_remove takes one out with confirm: true.
Bots and hidden cards#
⚠ A game's bots can see hidden cards. The host's device holds the whole table, and the bots run there. So whenever a game can hide anything, its bots can see it. The lobby says so beside the bots. lobby_state also reports the game's own declaration as game.botsCanSeeHiddenInformation.
Your agent doesn't get the same view. It still sees only what your seat may see. Hidden cards and AI agents explains the difference.
Next steps#
- Game bots for mod authors: how a game declares its bots and models.
- Test multiplayer with two agents: add a second human seat instead.
- Train an AI to play your board game: build a bot of your own.