tts-workshop/docs/bgm/engine.md

bgm-engine

The message layer that drives bgm board games, built into @tts/engine. It unifies the two halves of scripted interaction — declaring what should happen and executing it — into a single reactive loop: messages flow through a queue, and handlers react to them.

This doc covers the message model (what flows), the queue and its tick (how it flows), and the handlers (who reacts). Command execution — the async lifecycle, run contexts, and tap interaction — is specified in commands.md; this doc is the layer above it.

package split

The engine is a pure package: the message bus, queue, tick, trigger registry, and the handler runner. It has no r3f, no React, and no store, so it is node-testable in isolation (mirroring @tts/extract's isomorphic, zero-dep style). It defines the contract — Message, the handler registry, Trigger, Orchestrator, and RunContext.

@tts/tabletop is one consumer of that contract: it registers the built-in commands (move, focus, caption, enableSurface, ...) that mutate the tabletop store and drive the render layer. The engine never imports tabletop; tabletop depends on the engine for the message types and the handler registry. A headless sim or bot harness can consume the engine without the render layer.

1. messages

A message is the unit of communication. It is both an event (something happened) and an intent (something should happen) — the two are the same thing. A message is dispatched to the handlers registered for its type; a handler may emit new messages in response.

Messages are a discriminated union on type. The engine defines the generic shapes; the host's concrete union extends them with its own command types.

interface TapMessage {
  type: 'tap';
  data: TapEvent; // part, position, trigger
}

interface CommandMessage<Name extends string, Args> {
  type: Name;
  data: Args;
}

A message is identified by type, matching the format's type#id convention. A move message both runs the move command and is observable as an event; the command's completion is itself a message, which is what triggers match and orchestrators await.

The loop is just: message → handler → message. Handlers consume messages and emit new ones; the queue serializes them.

2. the queue and ticking

Messages are not processed inline. They are enqueued and handled on the next tick. This kills reentrancy (a handler cannot cause unbounded recursion), gives a natural debounce, and makes the whole system a deterministic frame.

tick contract

The engine is pure — it has no render loop and must stay node-testable. It exposes tick(), and the host calls it:

• In @tts/tabletop, a useFrame drives tick().
• In tests, tick() is called manually.

The engine never assumes a render loop.

drain semantics

• Snapshot-and-drain. At tick(), snapshot the queue and process it. Messages emitted during the drain go to the next tick. This guarantees no reentrancy within a drain and makes ordering deterministic.
• FIFO within a tick. Simple and predictable.
• One tick drains the whole snapshot (not one message per tick), so a burst of messages all resolve in one frame.

awaiting

A handler suspends on await ctx.wait(pred) and resumes when a matching message is processed during a drain. Its own emissions go to the next tick, so it cannot re-enter itself.

3. message types

interaction messages

Interaction is the player's input, reported to the engine as messages. Only tap interaction is supported (see commands.md §4).

interface TapMessage {
  type: 'tap';
  data: TapEvent;
}

A tap on a part is reported with the nearest trigger point (or null on a miss). The handler decides how to react — resolve, reject with a "wrong spot" shake, or ignore. The runtime stays dumb; the handler owns the UX.

command messages

A command message names a command to run. Its handler is the command implementation; its completion is emitted as a result message. A command's result is a discriminated union on the type suffix, carrying the terminal state:

type CommandResult<Name extends string, R = void> =
  | { type: `${Name}:done`; data: R }
  | { type: `${Name}:cancel` }
  | { type: `${Name}:error`; error: Error };

// e.g. move:done { data: MoveResult } | move:cancel | move:error

The command-id-as-key convention means a message both is the intent and observes the result. move:done, focus:done, etc. are the messages that triggers match and orchestrators await. A cancelled command emits :cancel, an errored one :error — a trigger matching move:done does not fire on a cancel.

4. handlers

There are three kinds of handler. All three consume messages and emit messages; they differ in how they're declared and how they run.

Handler	Declared	Runs	Purpose
Trigger	data (yaml)	synchronously on match	declarative reactive glue
Orchestrator	code (main.ts)	async, awaits	imperative flow
Command	code (built-in)	async, on its message	atomic execution

triggers — declarative reactive glue

A trigger matches a message by type and named params, and emits messages in response. It is declared as data, keyed by role+type+id like other defs, and collision-checked the same way.

role: trigger
type: tap
id: draw
match:
  part: carcassonne:tile#a
  trigger: draw
emit:
  - move: { part: carcassonne:tile#a, to: /grid/5/5 }
  - focus: { path: /grid/5/5 }

• type selects the message kind; match binds named params from the payload (like a route's candidates).
• emit uses the command-id-as-key convention.
• Multiple triggers can match the same message — both fire, which is usually what you want.
• A trigger is a pre-registered handler: it's a message consumer that emits commands. An orchestrator can do the same thing imperatively with ctx.on(...).

orchestrators — imperative async flow

An orchestrator is the code counterpart to a trigger: an async function that emits messages and awaits matching ones. It is a proper TS module, declared per folder as main.ts — unique per folder like package.yaml.

// main.ts
export default async function main(ctx: RunContext): Promise<void> {
  await ctx.focus({ path: '/deck' });
  await ctx.caption({ text: 'Draw a tile' });
  const tap = await ctx.wait((m) => m.type === 'tap');
  await ctx.move({ part: tap.data.part, to: '/grid/5/5' });
}

• main.ts is executable code, loaded by the host, not the engine. The engine defines the contract (the orchestrator type and runner); the host dynamically imports main.ts and hands the exported orchestrator to the engine. The engine never imports user code.

• A default export async function. main.ts exports a single async function as its default export, taking the RunContext. It is the folder's orchestrator.

• Trigger control lives here. The orchestrator toggles triggers at runtime by their type#id:

  ctx.enableTrigger('tap', 'draw');
  ctx.disableTrigger('tap', 'draw');
  

  Declaration is data; activation is code. The orchestrator owns game-flow logic ("no more placements this turn" → disable the trigger), while the trigger stays a dumb declarative mapping.

commands — atomic execution

A command is an async function, the same shape as an orchestrator. It takes a RunContext (with its args), returns its result, and throws on error. The engine wraps it: it builds the context from the message, runs the function, and emits the result message — :done on resolve, :cancel on abort, :error on throw.

type Command<Args, Result> = (ctx: RunContext & { args: Args }) => Promise<Result>;

Commands are the single mutation path — the only way state changes. Triggers and orchestrators never mutate state directly; they emit command messages, and the command handlers execute them.

5. run context

Every handler runs against a RunContext, the handle to everything it can affect and the unit of cancellation.

interface RunContext {
  signal: AbortSignal; // cancellation: superseded, skipped, surface disabled
  emit(msg: Message): void;
  wait(pred: (m: Message) => boolean): Promise<Message>; // rejects on abort
  enableTrigger(type: string, id?: string): void;
  disableTrigger(type: string, id?: string): void;
}

• Cancellation is an AbortSignal. A superseded command or a disabled surface aborts the signal; a wait rejects on abort, and the command's :cancel result is emitted.
• Errors are thrown. A command that throws emits :error; an orchestrator that throws surfaces loudly.
• Commands and orchestrators are the same shape: an async function taking the context. An orchestrator is a command that returns void and is never awaited by a parent.

6. solo-only

This design is solo-only — no multiplayer. Other players either don't exist or are automated with an automata. An automata is just another message consumer that emits commands: a stateful trigger or orchestrator. The engine doesn't care whether a tap message came from a human or a bot decision — same queue, same handlers. Solo-only simplifies the design: no network, no sync, no authoritative-server concerns. "Other players" are just more message producers.

Open decisions

• main.ts loading. The host dynamically imports main.ts; the exact loading boundary (Vite dynamic import, error handling, HMR) is deferred to implementation. The engine defines the orchestrator type; the host loads the module and hands the exported orchestrator to the engine.