Skip to content

Turns vs rounds

Shoehive has two models for who may act and when. A phase uses turns, rounds or neither. The reasoning is in ADR 0008.

Use When Examples
Turns One seat acts, then the next. Order matters. tic-tac-toe, poker, blackjack play
Rounds Everyone acts at once, usually against a clock. quiz answers, sealed bids, blackjack betting
Neither The game reacts to events, or only timers move it on. a lobby, a reveal screen

A game with no phases sets turns or rounds at the top level. A game with phases sets them per phase (a top-level one is an error), and one phase cannot have both. Blackjack mixes them: betting is a round, play is turns.

Add turns and the engine tracks ctx.turn.seat, ctx.turn.number (1-based, per phase) and ctx.turn.order. The simplest form is turns: { order: 'round-robin' }, which cycles through the occupied seats in ascending order. Everything else is optional:

turns.ts
export const lastOneIn = defineGame({
id: 'last-one-in',
seats: { min: 2, max: 5 },
setup: ({ seats }) => ({ start: 0, folded: Array<boolean>(seats).fill(false) }),
turns: {
// Play runs from the highest seat down. The function returns every seat once.
order: ({ seats }) => [...seats].reverse(),
// Who starts. It must be a seat in the order.
first: ({ state, seats }) => (seats.includes(state.start) ? state.start : seats[0]!),
// Seats to pass over when the turn advances.
skip: ({ seat, state }) => state.folded[seat]!,
},
actions: {
fold: {
run({ state, seat, ctx }) {
// The engine does not check whose turn it is. Every turn action should.
if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN');
state.folded[seat] = true;
const left = ctx.occupied.filter((s) => !state.folded[s]);
if (left.length === 1) ctx.end({ winner: left[0]! });
else ctx.turn.next();
},
},
pass: {
run({ seat, ctx }) {
if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN');
ctx.turn.next();
},
},
},
});
  • order is 'round-robin' or a function returning every seat that should play, in order.
  • first is 'lowest' (the default) or a function returning the starting seat, for example "left of the big blind". A skipped seat passes to the next eligible one.
  • skip says which seats to pass over each time the turn advances, such as folded players.
  • timeoutMs and onTimeout add a turn clock: see Timers and turn clocks.

In an action, ctx.turn.next() moves to the next eligible seat and ctx.turn.set(seat) jumps to one (it throws if the seat is not in the order). When no seat is eligible, ctx.turn.seat is null. Blackjack uses that to leave the play phase.

The engine does not reject off-turn actions. Check ctx.turn.seat !== seat and reject('NOT_YOUR_TURN') yourself, as above. Forgetting is a cheating bug, so make it your first test: an out-of-turn t.act that must reject.

A seat that stands up leaves the order. A seat that sits down mid-phase joins the order but does not get the current turn.

A rounds phase opens a round when it starts. Every seat occupied at that moment is a participant. Mark the action that counts as an answer with once: true, and the engine does the bookkeeping:

rounds.ts
export const sealedBids = defineGame({
id: 'sealed-bids',
seats: { min: 2, max: 8 },
setup: ({ seats }) => {
const bids: Record<string, number> = {}; // seat to bid, hidden until the round closes
return { bids, wins: Array<number>(seats).fill(0) };
},
rounds: {
durationMs: 20_000, // the round also closes by itself after 20 seconds
closeWhen: 'all-submitted', // ...or as soon as every participant has submitted
onOpen: ({ state }) => {
state.bids = {};
},
onClose: ({ state, ctx }) => {
// Runs once per round, in its own entry, after the last submission has synced.
const entries = Object.entries(state.bids).sort((a, b) => b[1] - a[1]);
if (entries[0]) state.wins[Number(entries[0][0])]! += 1;
if (ctx.round.number >= 3) ctx.end({ wins: state.wins });
else ctx.round.next(); // rounds do not reopen by themselves
},
},
actions: {
bid: {
once: true, // the seat's one submission this round
input: z.object({ amount: z.number().int().min(1).max(100) }),
run({ state, seat, input }) {
if (input.amount % 5 !== 0) reject('BID_NOT_A_MULTIPLE_OF_FIVE');
state.bids[String(seat)] = input.amount;
},
},
},
});
  • A second once action from the same seat rejects with ALREADY_SUBMITTED before run starts. Seats that were not participants get NOT_PARTICIPANT, and calls after the round closed get ROUND_CLOSED. Actions without once can be called freely and never count.
  • closeWhen: 'all-submitted' closes the round when nobody is pending or when durationMs runs out, whichever is first. closeWhen: 'timeout' waits for durationMs even if everyone has answered, for games that reveal on a fixed beat. It needs durationMs.
  • onClose is required. It runs exactly once, in its own entry, so the last answer is committed and synced to clients before your scoring code runs. An error in onClose rolls back only the close.
  • Rounds do not reopen by themselves. In onClose, call ctx.round.next() to open the next one, or ctx.phase.go(...) to move on (the quiz goes to reveal).
  • onOpen runs when a round opens, which is a good place to reset per-round state.

In code, ctx.round has number, open, participants, submitted, pending and deadline, plus ctx.round.close() to end the round early. A seat that sits down during a round waits for the next one. A seat that stands up leaves pending. Clients see the progress in meta.round.

Submissions can arrive in any order, but never at the same time: everything runs in one queue per table, so there are no races to guard against.

it('closes when everyone has bid and rejects a second bid', async () => {
const t = await createTestTable(sealedBids, { players: 2 });
await t.act(0, 'bid', { amount: 30 });
await expect(t.act(0, 'bid', { amount: 40 })).rejects.toMatchObject({
code: 'ALREADY_SUBMITTED',
});
await t.act(1, 'bid', { amount: 50 }); // last submission: the round closes
expect(t.state.wins.slice(0, 2)).toEqual([0, 1]);
expect(t.meta.round?.number).toBe(2); // onClose opened the next round
});
it('closes on the timer when someone is too slow', async () => {
const t = await createTestTable(sealedBids, { players: 2 });
await t.act(0, 'bid', { amount: 30 });
await t.advance(20_000);
expect(t.state.wins.slice(0, 2)).toEqual([1, 0]);
});

Use t.advance(ms) to reach a round's deadline. There is no tick loop in v1: time only enters through timers.

Related: Phases, and the concept page Turns and rounds.