@table-games-engine/core 0.1.0 → 0.1.1

package/README.md

@@ -1,69 +1,59 @@
 # @table-games-engine/core
 
-Pure, in-process implementation of the action-stack game engine described in
-[`docs/normative/`](../../docs/normative/).
+The deterministic, in-process engine for turn-based table games: state, actions, priority, triggers, seeded randomness and per-player views. Game logic is written against its types.
 
-## Run
+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), which scaffolds a game that already depends on it. Games import types and helpers from it:
 
-```bash
-npm install
-npm test --workspace=@table-games-engine/core
-npx tsc -p packages/core --noEmit
+```ts
+import { ok, reject, resolved, type ActionHandler, type GamePlugin } from '@table-games-engine/core';
+
+const fireBolt: ActionHandler = (ctx, frame) => {
+  const actor = 'actor' in frame ? frame.actor : frame.controller;
+  const target = ctx.getActivePlayers().find((p) => p !== actor);
+  if (!target) return reject('rule-violation');          // illegal move: nothing changes
+  return resolved([
+    { domain: 'player', operation: { type: 'add-resource', playerId: target, resource: 'life', delta: -2 } },
+    { domain: 'turn', operation: { type: 'advance' } },  // end the turn
+  ]);
+};
 ```
 
-## API entry point
+## Install
 
-```ts
-import {
-  createEngine,
-  computePlayerView,
-} from '@table-games-engine/core';
+```sh
+npm install @table-games-engine/core
+```
+
+ESM only.
+
+## What a game provides
+
+A `GamePlugin` has `id`, `version`, `manifest`, `requiredMechanics`, `setup`, `actionHandlers`, `winConditionChecker` and `legalMoves(state, playerId)`. `legalMoves` returns every concrete move the player may submit now, and `[]` when they do not hold priority or the game is over. Handlers must be pure: return mutations, never modify `ctx.state`.
+
+Helpers for handlers:
 
-const engine = createEngine(manifest, initialState, handlers);
+- `resolved(mutations, events?)` - a successful result.
+- `reject(reason)` - an illegal move (`'rule-violation'`, `'condition-failed'`, `'targets-illegal'`); state does not change.
+- `ok(value)` - generic `Result` success constructor (`err(error)` is its failure counterpart). `setup` returns `ok({ state })`.
 
-const result = engine.applyAction(playerInput);
-if (result.ok) {
-  engine.resolveTopFrame();
-}
+## Running the engine
 
-const state = engine.getState();
-const viewForP1 = computePlayerView(state, manifest, p1Id);
+Use these to run matches yourself (in tests, simulators, servers):
+
+```ts
+import { setupMatch, driveAction, rulesFromPlugin, computePlayerView } from '@table-games-engine/core';
 ```
 
-See [`__tests__/mini-duel.test.ts`](./__tests__/mini-duel.test.ts) for a full
-end-to-end example.
-
-## Determinism guarantees
-
-Same `(initialState, manifest, handlers, inputs[])` always produces the same
-final state. The engine never calls `Math.random` or `Date.now`; all
-randomness flows through `MatchState.rng` (xorshift32 PRNG). All IDs
-(transition, frame, trigger) derive from `state.version` plus caller-supplied
-input (clientId, event id) — no hidden module-level state.
-
-## Module map
-
-| File | Purpose |
-|---|---|
-| `src/types/` | Type definitions (the public API contract) |
-| `src/engine/rng.ts` | Seeded xorshift32 PRNG |
-| `src/engine/reducer.ts` | Pure `applyMutation` over 8 mutation domains |
-| `src/engine/transition.ts` | Compose mutations + bump version + log events |
-| `src/engine/stack.ts` | Stack helpers (peek, find, depth) |
-| `src/engine/priority.ts` | Priority pass-order operations |
-| `src/engine/window.ts` | Compute legal `ActionWindow` from phase + stack |
-| `src/engine/context.ts` | `GameEngineContext` — the API game logic sees |
-| `src/engine/validate.ts` | Validation pipeline (priority → window → speed) |
-| `src/engine/frames.ts` | `StackFrame` builder (deterministic ids) |
-| `src/engine/resolve.ts` | Top-of-stack resolver, dispatch to handlers |
-| `src/engine/triggers.ts` | Scan triggers, APNAP-order |
-| `src/engine/lifecycle.ts` | Advance turn / phase, win check |
-| `src/engine/operations.ts` | `createEngine` facade |
-| `src/engine/views.ts` | Per-player view filtering |
-
-## Status
-
-M1 — all engine modules implemented and unit-tested. 95 tests across 15 files.
-
-Out of scope: networking, persistence, client SDK, reference games. See
-[`docs/ROADMAP.md`](../../docs/ROADMAP.md).
+- `setupMatch` and `driveAction` start a match from a `GamePlugin` and apply one player input.
+- `createEngine(manifest, initialState, handlers)` is the lower-level facade (`applyAction`, `resolveTopFrame`, `getState`).
+- `computePlayerView(state, manifest, playerId)` returns what one player may see.
+- Randomness: `seedRng`, `nextRandom`, `randomInt`, `randomPick`, `randomShuffle`. Inside handlers use `ctx.random*`.
+- Lower-level building blocks are also exported (`applyMutation`, `applyTransition`, `validateAction`, `resolveTopFrame`, `scanTriggers`, `advanceTurn`, `advancePhase`, `checkWin`, priority helpers).
+
+## Determinism
+
+The same initial state, manifest, handlers and inputs always produce the same final state. The engine never calls `Math.random` or `Date.now`; all randomness flows through `MatchState.rng` (xorshift32).
+
+## Licence
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@table-games-engine/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -25,5 +25,15 @@
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "description": "Deterministic turn-based game engine: state, actions, priority, seeded RNG, player views.",
+  "keywords": [
+    "table-games",
+    "turn-based",
+    "multiplayer",
+    "game-engine",
+    "nakama",
+    "boardgame"
+  ],
+  "homepage": "https://www.npmjs.com/package/@table-games-engine/core"
 }