Game definition - tableverse-kit

The game definition is the complete set of rules that the CLI validates and Tableverse runs.

import {
  createGameExecutor,
  GameDefinitionBuilder,
  t,
} from "@tableverse-kit/engine";
import { events } from "./events.ts";
import { gameState } from "./state.ts";
import { playerTurn } from "./stages.ts";

export const game = new GameDefinitionBuilder("token-race")
  .state(gameState)
  .events(events)
  .setupInput(
    t.object({
      targetScore: t.optional(t.number()),
    }),
  )
  .setup(({ game, players, input }) => {
    if (players.length < 2) {
      throw new Error("at_least_two_players_required");
    }

    game.playerOrder = [...players];
    game.scores = Object.fromEntries(players.map((id) => [id, 0]));
    game.targetScore = input.targetScore ?? 10;
  })
  .initialStage(playerTurn)
  .build();

export const executor = createGameExecutor(game);

Builder methods

Method	Purpose
`.state(gameState)`	Sets the root state definition.
`.events(events)`	Registers domain events available to commands and automatic stages.
`.setupInput(schema)`	Declares game configuration a client chooses at start, such as a variant or option.
`.setup(callback)`	Initializes state before the first stage begins.
`.initialStage(stage)`	Sets the first stage.
`.build()`	Validates and creates the definition.

State and an initial stage are required. Events, setup input, and setup are optional. The player roster arrives as players on createInitialState and reaches .setup() through the context, alongside rng. Use .setupInput() for game configuration a client chooses, such as a variant or option.

Setup without input

If every game starts the same way, omit .setupInput():

export const game = new GameDefinitionBuilder("solo-puzzle")
  .state(gameState)
  .setup(({ game, rng }) => {
    game.deck = rng.shuffle(createDeck());
  })
  .initialStage(playStage)
  .build();

The executor signatures reflect this choice. Both start from an init object carrying the deterministic seed and the players roster; a definition with setup input also requires setup:

executorWithInput.createInitialState({
  seed: "seed-1",
  players: ["p1", "p2"],
  setup: { targetScore: 15 },
});
executorWithoutInput.createInitialState({
  seed: "seed-1",
  players: ["p1", "p2"],
});

Declare events

Events tell clients what happened without asking them to infer it from state changes.

import { defineEvents, t } from "@tableverse-kit/engine";

export const events = defineEvents({
  advanced: t.object({
    actorId: t.string(),
    spaces: t.number(),
  }),
  game_won: t.object({ winnerId: t.string() }),
});

Pass typeof events to your command and stage factories. emitEvent then accepts only declared event types and valid payloads.

Export both game and executor. The CLI config uses game; the frontend imports typeof executor for end-to-end types.

export { game, executor } from "./game.ts";

Use the executor

Start state, execute commands, and create safe views.

​Builder methods

​Setup without input

​Declare events

Use the executor

Builder methods

Setup without input

Declare events