@table-games-engine/nakama-adapter 0.1.0 → 0.1.1

package/README.md

@@ -1,323 +1,78 @@
-# `@table-games-engine/nakama-adapter`
+# @table-games-engine/nakama-adapter
 
-Nakama runtime bindings for the `@table-games-engine/core` engine.
+Nakama runtime bindings for `@table-games-engine/core`: wraps the engine (and `@table-games-engine/persistence`) in a Nakama TypeScript-runtime match handler so players can connect over WebSocket and play your game.
 
-This package wires the deterministic, in-process `Engine` from
-`@table-games-engine/core` (and the persistence layer from
-`@table-games-engine/persistence`) into a Nakama TypeScript-runtime
-`MatchHandler<T>` so that multiple players can connect via WebSocket and
-play a turn-based card / tabletop game implemented as a `GameManifest`.
+Most game authors don't install this directly: it comes with [`@table-games-engine/game-kit`](https://www.npmjs.com/package/@table-games-engine/game-kit), whose `preview` command and the [Logigra](https://logigra.ru) store host your game for you. Install it to run your own Nakama server.
 
-For the **normative behaviour contract** (lifecycle, sequential processing,
-persistence, recovery, timeouts) see
-[`docs/normative/platforms/nakama.md`](../../docs/normative/platforms/nakama.md).
-This README is the **operator-facing usage guide** — how to wire the
-module into Nakama, what to configure, and how to extend it with
-platform plugins.
+## Install
 
----
-
-## What this package gives you
-
-- A factory `createMatchHandler(opts)` that returns a Nakama
-  `MatchHandler<NkMatchInternalState>` implementing every callback
-  Nakama needs (`matchInit`, `matchJoinAttempt`, `matchJoin`,
-  `matchLeave`, `matchLoop`, `matchSignal`, `matchTerminate`).
-- A `GameRegistry` for resolving `gameId -> { manifest, handlers, setup }`
-  at `matchInit` time, so a single Nakama runtime can host multiple
-  game definitions.
-- An `IdempotencyCache` for absorbing client retries.
-- A `parseInbound`/`serializeOutbound` JSON wire format, opcode
-  constants (`OPCODES`), per-presence broadcast filtering
-  (`broadcastViews`), action timeouts (`checkTimeouts`),
-  reconnection-aware joins, and a `NakamaPlatformPlugin` extension hook.
-- Persistence wiring to `@table-games-engine/persistence`: every engine
-  transition's events are appended; snapshots are written per the
-  configured `SnapshotPolicy`.
+```sh
+npm install @table-games-engine/nakama-adapter
+```
 
----
+## What you get
 
-## Wiring into a Nakama TypeScript runtime
+- `createMatchHandler(opts)` returns a Nakama `MatchHandler` implementing `matchInit`, `matchJoinAttempt`, `matchJoin`, `matchLeave`, `matchLoop`, `matchSignal` and `matchTerminate`.
+- `GameRegistry` resolves `gameId` to `{ manifest, handlers, setup }` at `matchInit`, so one runtime can host many games (`registerPlugin` registers a `GamePlugin`).
+- `IdempotencyCache` absorbs client retries.
+- JSON wire format (`parseInbound`, `serializeOutbound`, `OPCODES`), per-player filtered broadcasts (`broadcastViews`), action timeouts (`checkTimeouts`), reconnection-aware joins.
+- Persistence wiring: events are appended per transition and snapshots follow a `SnapshotPolicy`.
+- `NakamaPlatformPlugin` hooks for analytics, audit and similar.
 
-Nakama runs your TS code via the `nakama-runtime` Node host, with an
-`InitModule(ctx, logger, nk, initializer)` entry point. A minimal
-`init.ts` looks like this:
+## Wiring into Nakama
 
 ```ts
-// init.ts
-import {
-  createMatchHandler,
-  GameRegistry,
-  IdempotencyCache,
-} from '@table-games-engine/nakama-adapter';
-import { SqliteAdapter } from '@table-games-engine/persistence';
-import { everyNTransitions } from '@table-games-engine/persistence';
-
-import { registerMyGame } from './games/my-game.js';
-
-const MATCH_HANDLER_NAME = 'tabletop_match';
+import { createMatchHandler, registerPlugin, GameRegistry, IdempotencyCache } from '@table-games-engine/nakama-adapter';
+import { SqliteAdapter, everyNTransitions } from '@table-games-engine/persistence';
 
 const registry = new GameRegistry();
-registerMyGame(registry); // calls registry.register({ gameId, manifest, handlers, setup, winChecker })
-
-const idempotencyCache = new IdempotencyCache();
-
-const adapter = new SqliteAdapter({
-  path: process.env['ENGINE_DB_PATH'] ?? '/data/engine.db',
-});
+registerPlugin(registry, myGamePlugin);   // a GamePlugin; or registry.register({ gameId, manifest, handlers, setup }) by hand
 
 const handler = createMatchHandler({
   registry,
-  idempotencyCache,
-  adapter,
+  idempotencyCache: new IdempotencyCache(),
+  adapter: new SqliteAdapter('/data/engine.db'),
   policy: everyNTransitions(50),
-  ownerNode: process.env['NAKAMA_NODE_ID'] ?? 'node-A',
+  ownerNode: 'node-A',
   leaseSeconds: 60,
   timeout: { timeoutMs: 30_000 },
-  plugins: [
-    /* analytics, audit, etc. — see "Plugins" below */
-  ],
+  plugins: [],
 });
 
-function InitModule(
-  _ctx: nkruntime.Context,
-  logger: nkruntime.Logger,
-  _nk: nkruntime.Nakama,
-  initializer: nkruntime.Initializer,
-): void {
-  initializer.registerMatch(MATCH_HANDLER_NAME, handler);
-  logger.info('registered match handler %s', MATCH_HANDLER_NAME);
+function InitModule(_ctx: nkruntime.Context, logger: nkruntime.Logger, _nk: nkruntime.Nakama, initializer: nkruntime.Initializer): void {
+  initializer.registerMatch('tabletop_match', handler);
 }
-
-!InitModule && InitModule;
 ```
 
-Then create a match from your matchmaker / API hook:
+Create a match from your own server code:
 
 ```ts
-const matchId = nk.matchCreate(MATCH_HANDLER_NAME, {
+nk.matchCreate('tabletop_match', {
   gameId: 'my-game',
-  // optional — handler will mint one via `matchIdFactory` or `match-<now>` if absent
-  matchId: 'duel-12345',
-  // comma-separated; setup() receives them
-  playerIds: 'alice,bob',
-  config: JSON.stringify({ /* game-instance options */ }),
+  playerIds: 'alice,bob',                 // comma-separated; passed to setup()
+  config: JSON.stringify({ /* game options */ }),
 });
 ```
 
----
-
-## Environment variables
-
-The adapter itself reads no env vars directly — they're conventions for
-the `init.ts` shim above. Recommended:
-
-| Variable             | Purpose                                                                 |
-| -------------------- | ----------------------------------------------------------------------- |
-| `ENGINE_DB_PATH`     | Path to the SQLite DB used by `SqliteAdapter` for events + snapshots.   |
-| `ENGINE_DB_DSN`      | If using a network-backed adapter (e.g. Postgres), connection DSN.       |
-| `NAKAMA_NODE_ID`     | Node identifier passed to `acquireOwnership(matchId, node, leaseSec)`.  |
-| `ENGINE_SNAPSHOT_N`  | Override `everyNTransitions(N)` cadence at boot.                         |
-| `ENGINE_TIMEOUT_MS`  | Default per-action timeout for `checkTimeouts`.                          |
-| `ENGINE_LEASE_SEC`   | Ownership lease duration in seconds (default 60).                        |
-
-These are NOT consumed by the package — your `init.ts` is responsible
-for plumbing them into `createMatchHandler`'s options. The package
-stays config-agnostic.
-
----
-
-## Game registration pattern
-
-A "game" is the triple `(manifest, handlers, setup)` registered against
-a `gameId`. Call `registry.register` once at module init:
-
-```ts
-import { GameRegistry } from '@table-games-engine/nakama-adapter';
-import { manifest, handlers, setup, winChecker } from './my-game.js';
-
-export function registerMyGame(registry: GameRegistry): void {
-  registry.register({
-    gameId: 'my-game',
-    manifest,
-    handlers,
-    setup,         // (matchId, playerIds, config, { now }) => MatchState
-    winChecker,    // optional WinConditionChecker
-  });
-}
-```
-
-Multiple games can coexist behind a single Nakama match-handler name —
-`matchInit` resolves the entry by the `gameId` parameter.
-
----
-
-## Persistence
-
-When `adapter` is supplied to `createMatchHandler`:
-
-- `matchInit` persists the initial state as **snapshot v0**
-  (`adapter.persistSnapshot(matchId, state, checksum)`).
-- If `ownerNode` is also set, `matchInit` calls
-  `adapter.acquireOwnership(matchId, ownerNode, leaseSeconds)`. Failures
-  are logged via `logger.error` but do not abort match creation; for
-  hard-fail semantics, pre-acquire the lease in your matchmaker.
-- Each engine transition (player action, stack drain, timeouts, ejects)
-  appends events via `adapter.appendEvents(matchId, transition.toVersion,
-  transition.events)` and may snapshot per the configured `SnapshotPolicy`
-  (default `everyNTransitions(50)`).
-- `matchTerminate` releases the ownership lease but does **NOT** close
-  the adapter — the same adapter typically hosts other matches in the
-  same Node process.
-
-To recover after a crash, use
-[`replayMatch(adapter, matchId, toVersion?)`](../persistence/src/replay.ts)
-to rebuild the latest snapshot at or before `toVersion`.
-
----
-
-## Reconnection
-
-When the same `userId` rejoins a match (a new `sessionId` for an existing
-user), the handler:
-
-1. Replaces the old presence in `state.presences` with the new one.
-2. Sends a fresh, filtered `state` view to the rejoiner only — other
-   players are **not** re-broadcast to.
-3. Preserves the per-match idempotency cache, so any in-flight client
-   retries from before the disconnect resolve to their cached responses.
+The adapter reads no environment variables; plumb configuration into the options yourself.
 
-Rejoiners are detected when either (a) the userId is already in
-`state.presences` or (b) the engine has a `PlayerState` for that
-`userId` (covers the case where the player completed a turn before
-disconnecting).
+## Persistence and reconnection
 
----
+With `adapter` set, `matchInit` stores snapshot v0 (and takes an ownership lease if `ownerNode` is set), each transition appends its events and may snapshot, and `matchTerminate` releases the lease without closing the adapter. When the same user rejoins with a new session, the handler swaps the presence, sends a fresh filtered state to that player only, and keeps the idempotency cache.
 
 ## Plugins
 
-Platform plugins are an extension hook for things that don't belong
-inside the deterministic engine: analytics, leaderboards, audit
-logging, push notifications, anti-cheat sampling, achievement
-emission, etc.
-
 ```ts
 import type { NakamaPlatformPlugin } from '@table-games-engine/nakama-adapter';
 
-const analytics: NakamaPlatformPlugin = {
-  name: 'analytics',
-  async onMatchCreated(ctx) {
-    await analytics.track('match_created', { matchId: ctx.matchId });
-  },
-  async onMatchEnded(ctx, result) {
-    await analytics.track('match_ended', { matchId: ctx.matchId, winners: result.winners });
-  },
-  async onPlayerAction(ctx, input, transition) {
-    await analytics.track('action', {
-      matchId: ctx.matchId,
-      playerId: input.playerId,
-      actionTypeId: input.type === 'action' ? input.data.actionTypeId : input.type,
-      version: transition.toVersion,
-    });
-  },
+const audit: NakamaPlatformPlugin = {
+  name: 'audit',
+  async onMatchEnded(ctx, result) { /* ... */ },
 };
-
-createMatchHandler({ /* ... */, plugins: [analytics] });
-```
-
-### Plugin contract
-
-- All callbacks are **optional** — implement only what you need.
-- All callbacks are **async** and invoked **fire-and-forget** by the
-  match handler. The match loop does NOT await plugin promises.
-- Plugin failures (sync throws or rejected promises) are caught and
-  logged via `logger.error('plugin %s hook %s rejected: %s', name, hook, err)`.
-  A failing plugin **never** crashes the match.
-- Plugins are invoked in registration order, but their promises run in
-  parallel (no serialization).
-- Plugins receive a `PluginContext` (`{ matchId, gameId, state, now }`) —
-  treat `state` as readonly.
-
-### Hook coverage
-
-| Hook                 | Fires when                                                              |
-| -------------------- | ----------------------------------------------------------------------- |
-| `onMatchCreated`     | `matchInit` completes.                                                  |
-| `onMatchStarted`     | Match transitions `lobby -> active` (enough seats filled).             |
-| `onPlayerJoined`     | Each presence in a `matchJoin` (fresh joins and reconnects).            |
-| `onPlayerLeft`       | Each presence in a `matchLeave`.                                        |
-| `onPlayerAction`     | A player-driven `applyAction` transition succeeded (one per action).    |
-| `onStateTransition`  | Every successful transition (player actions, stack drain, timeouts).    |
-| `onMatchEnded`       | `checkWinConditions` reports `ended: true`.                             |
-
----
-
-## Determinism and tests
-
-The adapter accepts an injectable `now: () => number` so tests can use a
-monotonic harness clock instead of wall-clock time. Pair it with the
-in-package harness (`__tests__/harness.ts`) and `InMemoryAdapter` from
-`@table-games-engine/persistence` to drive whole matches without Nakama:
-
-```ts
-import { createHarness } from '@table-games-engine/nakama-adapter/__tests__/harness';
-import { InMemoryAdapter, always } from '@table-games-engine/persistence';
-
-const adapter = new InMemoryAdapter(() => 0);
-const harness = createHarness();
-const handler = createMatchHandler({
-  registry, idempotencyCache, adapter,
-  now: () => harness.tick.now(),
-  policy: always(),
-});
-
-const init = handler.matchInit({}, harness.logger, {}, { gameId, matchId, playerIds: 'alice,bob' });
-// ...drive matchJoin, matchLoop, matchLeave, matchTerminate...
 ```
 
-See `__tests__/e2e.test.ts` for the full pipeline exercised end-to-end.
-
----
-
-## Public API
-
-```ts
-// Wire format
-parseInbound, serializeOutbound,
-InboundEnvelope, OutboundEnvelope,
-
-// Match handler
-createMatchHandler, NkMatchInternalState, CreateMatchHandlerOptions,
-
-// Registry
-GameRegistry, RegistryError,
-
-// Idempotency
-IdempotencyCache,
-
-// Broadcast
-broadcastViews, OPCODES,
-
-// Timeouts
-checkTimeouts, TimeoutOptions,
-
-// Persistence bridge (lower-level; createMatchHandler uses it under the hood)
-createPersistenceBridge, PersistenceBridge,
-
-// Plugins
-NakamaPlatformPlugin, PluginContext,
-invokePluginHook, dispatchPluginHook,
-```
-
----
-
-## Status
+Hooks: `onMatchCreated`, `onMatchStarted`, `onPlayerJoined`, `onPlayerLeft`, `onPlayerAction`, `onStateTransition`, `onMatchEnded`. All are optional and async. They are fire-and-forget: the match loop never waits for them, and a failing plugin is logged but never crashes the match.
 
-- **Phase A** — wire format, registry, idempotency, harness. Done.
-- **Phase B** — full match handler, broadcast, timeouts, signals. Done.
-- **Phase C** — persistence wiring, plugins, reconnection, e2e test,
-  this README. Done.
+## Licence
 
-For the normative compliance contract (what any Nakama-based adapter
-MUST guarantee, regardless of implementation), see
-[`docs/normative/platforms/nakama.md`](../../docs/normative/platforms/nakama.md).
+FSL-1.1-ALv2 (Functional Source License, converts to Apache-2.0 after two years). See `LICENSE.md` in the package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@table-games-engine/nakama-adapter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -23,12 +23,22 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@table-games-engine/core": "^0.1.0",
-    "@table-games-engine/persistence": "^0.1.0"
+    "@table-games-engine/core": "^0.1.1",
+    "@table-games-engine/persistence": "^0.1.1"
   },
   "devDependencies": {
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
-  "license": "FSL-1.1-ALv2"
+  "license": "FSL-1.1-ALv2",
+  "description": "Nakama runtime match handler for table-games-engine games.",
+  "keywords": [
+    "table-games",
+    "turn-based",
+    "multiplayer",
+    "game-engine",
+    "nakama",
+    "boardgame"
+  ],
+  "homepage": "https://www.npmjs.com/package/@table-games-engine/nakama-adapter"
 }