docs: reorganize docs into bgm and status folders
Group the bgm spec cluster under docs/bgm and move dev logs and plans under docs/status, add an overview index, and update cross-references in the docs, README, and source comments.
This commit is contained in:
@@ -0,0 +1,260 @@
|
||||
# bgm-engine
|
||||
|
||||
The message layer that drives [bgm](./format.md) board games, built into
|
||||
[`@tts/engine`](../architecture.md). 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`](./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`](./tabletop.md) 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.
|
||||
|
||||
```ts
|
||||
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).
|
||||
|
||||
```ts
|
||||
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:
|
||||
|
||||
```ts
|
||||
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.
|
||||
|
||||
```yaml
|
||||
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`.
|
||||
|
||||
```ts
|
||||
// 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`:
|
||||
|
||||
```ts
|
||||
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.
|
||||
|
||||
```ts
|
||||
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.
|
||||
|
||||
```ts
|
||||
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.
|
||||
Reference in New Issue
Block a user