---
title: "Multiplayer AI games: how AI players sit at the same table as real people"
subtitle: "The AI takes a real seat in Avalon, with a secret role and the same rules as everyone else. How the room server, the card in the host's browser and the model make that work."
description: How an AI plays Avalon on Yumina as a real player. What it hears, how it acts under the same rules as the humans, how its role stays secret, and who runs the model.
author: Yumina
date: 2026-11-15
updated: 2026-11-16
category: engineering
tags: multiplayer AI game, AI NPC, AI players, game server, Avalon, Yumina engine
lang: en
url: https://yumina.io/blog/multiplayer-ai-games
canonical: https://yumina.io/blog/multiplayer-ai-games
---

# Multiplayer AI games: how AI players sit at the same table as real people

*The AI takes a real seat in Avalon, with a secret role and the same rules as everyone else. How the room server, the card in the host's browser and the model make that work.*

## How to play a multiplayer AI game with friends

Some Yumina worlds are live games built for several players. Each one shows a Live badge with how many people are in it right now. Open one, and inside the game use Invite friends to pick who joins. They get a notification and come straight into your game. The rest of this post explains how an AI player sits at the same table.

## Why AI players are hard in a real game

Most AI in games is a chatbot sitting next to the game. In a game like poker or Avalon, the AI has to be a player. It has to hear what people say at the table and follow the same rules they do. In Avalon it also has to keep a secret role, which means the server can never send that role to anyone else. And it has to answer quickly, because nobody at a table waits ten seconds for a bot to vote.

## The stack

Yumina's room server has no separate path for AI. A room has seats, a seat holds a human, an AI, or nothing, and every seat acts through the same two calls, inputs and commands. The game module cannot tell who is sitting where.

The module is a pure program. The host hands it a time step and a seeded random number generator, and it may touch nothing else:

```ts
/** A game module is PURE logic: no sockets, no DB, no timers, no Date.now,
 *  no Math.random. The host injects dt and a seeded RNG. */
```

The generator is mulberry32, a few lines of integer math. The same seed gives the same sequence, so a room can be replayed, a test can play thousands of games, and nobody can rig the deal.

On every tick the AI brains act first. Then the host applies the inputs queued from every chair, advances the game one step, and sends everyone the events plus a small delta; every tenth tick, a full snapshot. Avalon ticks four times a second. A chair may send at most 30 inputs per tick, and a stalled server advances at most three ticks at once, so a hiccup cannot teleport the game forward.

Two kinds of message reach the module. Inputs are continuous and merged, such as movement in the sea game, and the host keeps at most the latest per chair per tick. Commands are discrete and ordered, such as a vote, a proposed team or a line of speech, and each one is validated by the module before it changes anything. Private knowledge travels the other way as a directed event: in Avalon the `role` event goes to one chair at the start and on reconnect, and the `myView` command returns that chair's view of the table on demand. Everything else is public events, deltas and the every-tenth-tick snapshot, all under the 64 KB frame cap.

## How the AI player acts

The server does not run the model. The host's browser does. The first person to join an Avalon table is the host and picks which chairs are bots. The Avalon card in the host's browser asks the server for a bot's private view, feeds it to the model, and sends the model's choice back as an ordinary command with one extra field naming the bot's chair. Two checks are the whole trust model:

```ts
/** Who is acting: your own chair, or the host acting for a bot. */
function actor(s: AvalonState, seatId: string, body: Body): number | null {
  const as = body?.as;
  if (typeof as === "number") {
    if (seatId !== s.hostId || !isBot(s, as)) return null;
    return as;
  }
  const i = humanSlot(s, seatId);
  return i >= 0 ? i : null;
}
```

Only the host may act for a bot, and only for a bot's chair. A test covers all three cases, and only the host voting as a bot is accepted. While a bot is thinking, the card sends a draft with the words so far, so the table sees that chair composing.

The Avalon card is the world's custom interface, written in TSX and stored with the world. For each bot chair it calls `myView` to get that chair's private view and builds the model's prompt from it plus the last 40 speeches. The prompt goes to the same completions endpoint as any side call, `POST /api/sessions/:id/completions`, with an 8,192-token cap on the answer. The model's reply becomes a command with `as` set to the bot's chair. A different model can sit in each chair, so one table can have four models arguing with three people.

![An Avalon table on Yumina with one person and six AI players, each a different model, during a vote: the countdown on the table and the discussion feed on the right](/blog-assets/multiplayer-ai-games/avalon-table.png)

## What the AI player hears, and what stays secret

The server never puts a role in anything it broadcasts. The public snapshot holds the chairs, the quest, the leader, the proposed team, the vote counts, the last 40 speeches, the drafts and the timer. Roles appear in it only when the game is over. Each chair's role travels in a private event addressed to that chair at the start and again on reconnect. A bot's view goes only to the host, only for a bot chair, never in the lobby.

Two tests run on every build. One deals a seven-player game and checks that no role word appears in the public snapshot. The other plays 600 random games end to end with timers firing at random, and asserts that every game finishes, no role leaks, and no snapshot exceeds 60,000 characters, since the frame cap is 64 KB.

Voice works the same way. Audio goes between the humans, and each person's speech becomes text at the table, so a bot hears what was said, not only what was typed.

## When the model is slow

Every step has a countdown and a fallback.

| Step | Countdown | When it runs out |
|---|---|---|
| Discussion | 60, 100 or 160 seconds by pace; none in free pace | voting starts |
| Propose a team | 90 seconds; 60 if the leader is a bot | a fallback team is proposed |
| Vote | 45 seconds | missing votes are filled by a simple rule |
| Quest | 35 seconds | missing cards are played by a simple rule |
| Assassin | 120 seconds; 300 in free pace | a random candidate is chosen |

A person who disconnects keeps their chair, marked offline. If the host leaves, the next online human becomes host. A line of speech is at most 240 characters, the same chair waits one second between lines, and a speech in the last seconds of a discussion stretches the clock, at most three times. Whoever is sitting, a good player can only play a success card on a quest; if a confused model, or person, tries to fail one, the server records a success.

## Who pays for the AI players

The host's card calls the same completions endpoint any custom interface uses for a side call, under the host's login, model access, credit check and rate limit. A host with their own API key is billed by their provider; otherwise the tokens come out of the host's Yumina credits. The host pays for every AI player at the table.

## Joining a room, and the numbers

To join a room you need a ticket, and the room server checks it in constant time without touching a database. A second device on the same chair is told the chair is taken. A dropped socket frees the chair's turn at once, and on reconnect the player gets their role again.

A ticket is `base64url(JSON{u, n, r, exp, j}).signature`: user, nonce, room, expiry and a join id, signed with HMAC-SHA256 under a secret the main site and the room server share. The nonce is single-use and the server keeps the last 100,000, the expiry is at most five minutes, and the socket must send its `hello` within five seconds or it is closed. Guests get at most 600 tickets a minute per IP.

| | |
|---|---|
| Avalon tick | 250 ms |
| Chairs | 5 to 10, default 7 |
| Frame cap | 64 KB |
| Sockets per server process | 512 |
| Loopback test, 500 rooms and 1,000 sockets for 60 s | 1,201,700 messages, p95 14.34 ms, p99 16.16 ms, 132 MiB memory |
| Real match, Singapore to the US | median round trip 344 ms, worst gap 564 ms |


## Doing the same in your own game

The design carries over to any game with hidden information. Four rules reproduce it.

1. Give the game module no access to time, randomness, sockets or storage; inject a time step and a seeded generator, and the module becomes testable by replay.
2. Make AI a seat, not a feature: every participant acts through the same inputs and commands, and the module never checks who is sitting where.
3. Send secrets only as directed events to the chair that owns them, and write a test that plays hundreds of random games and greps every public frame for a role word.
4. Put a countdown and a fallback on every step a model or a person could stall.

Running the model in the host's browser, with the server checking only that the host acts for a bot chair, keeps the server free of model code and puts the cost on the person who invited the bots.

## What it does not do yet

If the host leaves mid-game, the bots fall back to the simple rules until a new host's card picks them up. Because the AI players run in the host's browser, a slow host slows every bot. Game traffic has run on its own tunnels since September, after the platform's public entry point cut long WebSocket connections. A match across an ocean once died when a phone switched networks; the 10-second heartbeat and the instant takeover of a dead chair come from that.

## On Yumina this is built in

[Open an Avalon table](https://yumina.io/@kljws/avalon-1ad0cd76), pick the number of chairs, leave some open for friends, and the bots think with whatever model your account uses, or your own key; [playing with friends](https://docs.yumina.io/help/how-do-i-play-with-friends) covers the invite. A creator who wants AI players in another game writes the module as pure logic and gets the seats, the secrets and the clocks for free; [characters in games](https://docs.yumina.io/creator/games) is the starting point, and the [engine is open source](https://github.com/lovetimo0421/yumina-oss).

## FAQ

### Can the AI player see my role?

No. Roles leave the server only in private events addressed to one chair. The public snapshot has no roles until the game is over, and a test checks every build for leaks.

### What happens if the AI is slow or the host disconnects?

Every step has a countdown. When it runs out, a fallback rule acts for whoever did not: a fallback team, a filled-in vote, a played card. If the host leaves, hosting passes to the next person online.

### Can I play with only AI players?

Yes. One person and the rest bots is a valid table. The same rules file also runs inside the card for a solo game, so the rules are identical whether the room is on the server or in your browser.
