Engine overview - tableverse-kit

@tableverse-kit/engine is the rules package. It turns your game definition into one GameExecutor that Tableverse can run. Your frontend does not import or run these rules. It communicates with the executor through @tableverse-kit/client.

The four parts of a game

State

The saved facts of the game, such as scores, pieces, decks, and player order.

Commands

The actions players can attempt, with input validation and execution rules.

Stages

The current phase, allowed commands, active players, and next phase.

Game definition

The state, events, setup, and initial stage assembled into one game.

Typical file layout

Small games can keep everything in a few files:

engine/src/
├── state.ts
├── events.ts
├── commands.ts
├── stages.ts
├── game.ts
└── index.ts

As the game grows, split commands, stages, and nested state classes into folders. Keep game.ts as the place that assembles them.

Main exports

import {
  createCommandFactory,
  createGameExecutor,
  createStageFactory,
  defineEvents,
  defineGameState,
  GameDefinitionBuilder,
  t,
} from "@tableverse-kit/engine";

t defines serializable field and input schemas.
defineGameState pairs saved fields with a state class.
createCommandFactory creates commands for that class.
createStageFactory creates the flow between player actions.
defineEvents declares player-facing event payloads.
GameDefinitionBuilder assembles the game.
createGameExecutor produces the finished runtime surface.

Rules to keep in mind

Use the provided rng for every random choice. Math.random() cannot be replayed.
Store only values described by t schemas.
Put rule changes inside command execution, automatic stages, or setup.
Treat game as read-only in validation, availability, and transition callbacks.
Use hidden-information rules for secrets. Never send canonical state to a player.

Model game state

Define saved fields and rule methods.

​The four parts of a game