Executor - tableverse-kit

createGameExecutor(game) produces the final rules surface. Tableverse hosts it, the local server runs it, and your tests can call it directly.

import { createGameExecutor } from "@tableverse-kit/engine";
import { game } from "./game.ts";

export const executor = createGameExecutor(game);

Start a game

createInitialState takes one init object:

const state = executor.createInitialState({
  seed: "match-42",
  players: ["p1", "p2"],
  setup: { targetScore: 15 },
});

seed — a deterministic RNG seed. The same seed reproduces the same shuffles and rolls.
players — the authoritative roster, in seating order. These identity strings are what the engine matches against a command’s actorId and a view’s playerId.
setup — matches your .setupInput() schema. Omit it when your definition declares no setup input:

executor.createInitialState({ seed: "match-42", players: ["p1", "p2"] });

Public methods

Method	Returns
`createInitialState(...)`	Canonical game and runtime state at the first waiting stage.
`getView(state, viewer)`	A visibility-safe game view and current progression.
`listAvailableCommands(state, { actorId })`	Command IDs the actor may currently use.
`discoverCommand(state, request)`	Legal UI choices, completed command input, or `null`.
`executeCommand(state, command)`	An accepted or rejected result with state and events.

Execute a command

const result = executor.executeCommand(state, {
  type: "advance",
  actorId: "p1",
  input: { spaces: 2 },
});

if (!result.ok) {
  console.log(result.reason, result.metadata);
} else {
  console.log(result.state.game);
  console.log(result.events);
}

On success, continue from result.state. The executor does not mutate the input state. On rejection, result.state is the original state and result.events is empty. Common engine-level reasons include unknown_command, not_active_player, invalid_command_input, and command_not_allowed_in_stage. Your .validate() callback can return game-specific reasons.

Discover legal choices

For a discoverable command, begin with its initial step:

const discovery = executor.discoverCommand(state, {
  type: "choose_route",
  actorId: "p1",
  step: "select_route",
  input: {},
});

An incomplete result contains options. Send an option’s nextStep and nextInput in the next discovery request. A complete result contains input ready for executeCommand. The executor returns null when the command, actor, step, input, or generated options are invalid.

Read available commands and views

const commands = executor.listAvailableCommands(state, { actorId: "p1" });
const view = executor.getView(state, { kind: "player", playerId: "p1" });

Use canonical state only inside trusted rule and test code. Send getView() output to players.

Frontends normally use TableverseClient instead of calling the executor. The client supplies the viewer identity and actor ID through the host.

Test the executor

Verify complete command and stage flows with Vitest.

​Start a game

​Public methods

​Execute a command

​Discover legal choices

​Read available commands and views

Test the executor

Start a game

Public methods

Execute a command

Discover legal choices

Read available commands and views