Phases
A phase is a stage of the game with its own rules: what actions exist, whether play is by turns or rounds, and what runs on the way in and out. Betting, then playing, then the dealer, then settling is four phases. A game that is one continuous stage (tic-tac-toe) needs none. The model is in ADR 0001.
The examples are one small game, website/snippets/phases/.
Declare phases
Section titled “Declare phases”phases is an object keyed by phase name. The first one declared is the initial phase,
entered when the table starts. Each phase can have actions, turns or rounds (not
both), onEnter and onExit.
enter: { rounds: { closeWhen: 'all-submitted', onClose: ({ ctx }) => { ctx.phase.go('duel'); }, }, actions: { // Only available in this phase. In any other phase it is ACTION_NOT_ALLOWED. join: { once: true, input: z.object({ stake: z.boolean() }), run({ state, seat, input }) { state.in[seat] = input.stake; }, }, },},A game with phases sets turns and rounds inside each phase, never at the top level.
Top-level actions are available in every phase, and a phase's own actions only there.
Calling a phase action in the wrong phase rejects with ACTION_NOT_ALLOWED, with the
current phase in details.phase. Internal actions work the same way, so a timer set in one
phase whose action does not exist in the next does nothing when it fires.
Move between phases
Section titled “Move between phases”ctx.phase.go('duel') switches phase. Call it from an action, a hook, or onClose. Three
things to know:
- It takes effect when your function returns, not at the call.
ctx.phase.nameis still the old phase for the rest of the function, so finish your state changes first. - It is part of the transaction. If the action later rejects or throws, the move never happens.
- On the way, the engine runs the old phase's
onExit, cancels the turn clock and round timer, then enters the new phase. Your own timers are not cancelled: cancel them inonExit.
Entering a phase sets up its model: a turns phase computes the order and picks the first
seat, a rounds phase opens round 1. Then onEnter runs.
duel: { turns: { // Seats that stayed out, or whose die is 1, never get a turn. skip: ({ seat, state }) => !state.in[seat] || state.dice[seat] === 1, }, onEnter: ({ state, ctx }) => { // The first turn is chosen before this runs. If a die of 1 makes that seat // skippable, the engine moves on to the next seat afterwards (still turn 1). for (const seat of ctx.occupied) state.dice[seat] = 1 + ctx.random.int(6); }, onExit: ({ ctx }) => { ctx.emit('duel-over'); }, actions: { roll: { run({ state, seat, ctx }) { if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN'); state.rolled[seat] = state.dice[seat]!; const { turn } = ctx; // read afresh: next() moves the seat turn.next(); if (turn.seat === null) ctx.phase.go('done'); // nobody left to roll }, }, },},The first turn and onEnter
Section titled “The first turn and onEnter”The first seat is chosen before onEnter runs. So first should read state that was
set up before ctx.phase.go(), such as the button in poker. If onEnter then makes that
seat skippable (a dealt blackjack, a die of 1 above), the engine moves the turn on to the
next eligible seat once onEnter has finished, and it is still turn 1. skip is checked
again at every ctx.turn.next().
onEnter can itself call ctx.phase.go(), for example when no seat has anything left to
do. Blackjack's deal does this when every hand is a natural.
Phase names are typed
Section titled “Phase names are typed”TypeScript reads the phase names from the keys of phases, so a typo in go is an error
at compile time:
import { defineGame } from 'shoehive';
defineGame({ id: 'typed', seats: { min: 1, max: 1 }, setup: () => ({}), phases: { play: { onEnter: ({ ctx }) => { // @ts-expect-error 'finnish' is not a phase of this game ctx.phase.go('finnish'); ctx.phase.go('finish'); }, }, finish: {}, },});Without phases, any string type-checks and ctx.phase.go fails at runtime with an
unknown phase error. GamePhases<typeof game> gives you the union of names for your own
code. On clients meta.phase is a plain string | null.
Test phase changes
Section titled “Test phase changes”Assert on t.meta.phase after acting, and on the rejection for actions from the wrong
phase.
it('moves from enter to duel, and phase actions stay in their phase', async () => { const t = await createTestTable(dice, { players: 2 }); expect(t.meta.phase).toBe('enter'); await expect(t.act(0, 'roll')).rejects.toMatchObject({ code: 'ACTION_NOT_ALLOWED' });
await t.act(0, 'join', { stake: true }); await t.act(1, 'join', { stake: true }); // the round closes, onClose calls go('duel') expect(t.meta.phase).toBe('duel'); await expect(t.act(0, 'join', { stake: true })).rejects.toMatchObject({ code: 'ACTION_NOT_ALLOWED', });});
it('never gives the first turn to a seat that onEnter made skippable', async () => { const t = await createTestTable(dice, { players: 3, seed: 'other' }); for (const seat of [0, 1, 2]) await t.act(seat, 'join', { stake: true }); const seat = t.meta.turn?.seat; if (seat !== null && seat !== undefined) expect(t.state.dice[seat]).toBeGreaterThan(1);});Related: Turns vs rounds and Timers and turn clocks.
