Skip to content

The six concepts

Shoehive has exactly six nouns. The rest of the docs use them in this order, and everything else (lobby, session, transport, store, wallet, clock) is plumbing around them.

The examples on this page come from one small game: two players take turns guessing a secret number from 1 to 100, and each guess gets a hint.

A Game is a definition made by defineGame. It is plain data plus functions, with no I/O: the starting state, the turn order, the actions and the view. The same Game can run on a server, in a test and in the devtools.

game.ts
export const guessTheNumber = defineGame({
id: 'guess-the-number',
name: 'Guess the number',
seats: { min: 2, max: 2 },
setup: ({ random }) => ({
secret: random.int(100) + 1,
guesses: [] as { seat: number; value: number }[],
}),
turns: { order: 'round-robin' },
actions: {
guess: {
input: z.object({ value: z.number().int().min(1).max(100) }),
run({ state, seat, input, ctx }) {
if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN');
state.guesses.push({ seat, value: input.value });
if (input.value === state.secret) ctx.end({ winner: seat });
else ctx.turn.next();
},
},
},
view: ({ state, ctx }) => ({
guesses: state.guesses.map(({ seat, value }) => ({
seat,
value,
hint: value < state.secret ? 'higher' : value > state.secret ? 'lower' : 'correct',
})),
// Nobody sees the secret until the game is over.
secret: ctx.status === 'ended' ? state.secret : null,
}),
});

A Table is one running instance of a Game. It owns its state, its seats, its action log, its random number generator and its timers. A server runs many tables of many games at once. In a test, createTestTable gives you a table without a server:

export async function playOneTurn() {
// A Table is one running instance of the Game, here with two players seated.
const table = await createTestTable(guessTheNumber, { players: 2 });
// Seat 0 acts. Only an Action can change the state.
await table.act(0, 'guess', { value: 50 });
// Each seat receives its View, never the raw state.
const view = table.viewOf(1);
return view.guesses[0]?.hint; // 'higher', 'lower' or 'correct'
}

A Seat is a numbered slot at a Table, from 0. The game above has exactly two (seats: { min: 2, max: 2 }). A seat is empty, occupied, or reserved while its player reconnects. Game code only ever talks about seats, never about players: ctx.turn.seat is whose turn it is, and an action receives the seat that sent it.

A Player is an identity: an id, a display name and optional metadata. By default every visitor is a guest with a resume token; you can plug in your own authentication. A Player is not a socket: one player can have several tabs open, sit at one table and watch others as a spectator.

An Action is a named input from a seat, checked against its schema before your code runs. It is the only way the state changes from outside. Your run function changes a draft of the state; if it calls reject() or throws, the draft is thrown away and nothing changes.

game.ts
actions: {
guess: {
input: z.object({ value: z.number().int().min(1).max(100) }),
run({ state, seat, input, ctx }) {
if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN');
state.guesses.push({ seat, value: input.value });
if (input.value === state.secret) ctx.end({ winner: seat });
else ctx.turn.next();
},
},
},

A View is what one viewer, a seat or a spectator, is allowed to see. Your view() function computes it from the state. Clients only ever receive views, never the raw state, so the secret number above cannot reach a browser before the game ends.

game.ts
view: ({ state, ctx }) => ({
guesses: state.guesses.map(({ seat, value }) => ({
seat,
value,
hint: value < state.secret ? 'higher' : value > state.secret ? 'lower' : 'correct',
})),
// Nobody sees the secret until the game is over.
secret: ctx.status === 'ended' ? state.secret : null,
}),

When the state changes, Shoehive computes each viewer's new view, compares it with the one they already have, and sends only the difference.

  • State only changes inside an action, a lifecycle hook or a timer, one at a time per table.
  • A failed action rolls back completely.
  • Clients receive only view() output.
  • Every view a client holds has a revision number, and applying the patches in order gives exactly the server's view.
  • The same seed and the same action log always replay to the same state.

Next: build a full game in the tic-tac-toe tutorial, or read how each concept works in depth under Concepts.