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:
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(); }, }, },});orderis'round-robin'or a function returning every seat that should play, in order.firstis'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.skipsays which seats to pass over each time the turn advances, such as folded players.timeoutMsandonTimeoutadd 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.
Rounds
Section titled “Rounds”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:
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
onceaction from the same seat rejects withALREADY_SUBMITTEDbeforerunstarts. Seats that were not participants getNOT_PARTICIPANT, and calls after the round closed getROUND_CLOSED. Actions withoutoncecan be called freely and never count. closeWhen: 'all-submitted'closes the round when nobody is pending or whendurationMsruns out, whichever is first.closeWhen: 'timeout'waits fordurationMseven if everyone has answered, for games that reveal on a fixed beat. It needsdurationMs.onCloseis 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 inonCloserolls back only the close.- Rounds do not reopen by themselves. In
onClose, callctx.round.next()to open the next one, orctx.phase.go(...)to move on (the quiz goes toreveal). onOpenruns 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.
Test both
Section titled “Test both”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.
