@rogue-x/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RogueX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @rogue-x/engine
+
+A platform-free, data-driven game engine SDK. You describe a game as **data** — a
+`GameDefinition` of tiles, scenes, entities, actions, and events — and the engine
+runs it. The browser host (`@rogue-x/engine/web`) renders, drives the clock, binds
+input, and plays audio, so a complete game can be a single definition file plus one
+`<GameHost />`.
+
+> **Status:** web-first. The browser host is the supported runtime today. A React
+> Native / Expo host is a work in progress.
+
+## Install
+
+```bash
+npm install @rogue-x/engine react react-dom
+```
+
+`react` is an optional peer dependency — only needed if you use the `/web` host.
+
+## Quick start
+
+```tsx
+import { GameHost } from '@rogue-x/engine/web';
+import type { GameDefinition } from '@rogue-x/engine';
+
+const definition: GameDefinition = {
+  title: 'Hello',
+  profile: 'grid-turn-based',
+  tileTypes: { floor: { id: 'floor', visuals: ['plain'] } },
+  scenes: {
+    room: {
+      topology: { kind: 'square4', width: 5, height: 5 },
+      layers: [{ id: 'ground', role: 'logical', fill: 'floor' }],
+      entities: [
+        { id: 'hero', type: 'hero', position: { kind: 'discrete', loc: { x: 2, y: 2 } }, data: {} },
+      ],
+    },
+  },
+  initialSceneId: 'room',
+  onStep: () => ({ patch: {} }),
+};
+
+export default () => <GameHost definition={definition} tileSize={40} />;
+```
+
+See **[GETTING_STARTED.md](./GETTING_STARTED.md)** for the full walkthrough — defining
+a game, the action/patch model, events, modes, audio, and mounting the host.
+
+## Entry points
+
+| Import                    | What it is                                              |
+| ------------------------- | ------------------------------------------------------ |
+| `@rogue-x/engine`          | Core: `createGame`, types, coordinate + patch helpers. |
+| `@rogue-x/engine/web`      | Browser host: `GameHost`, `VisualConfig`, controls.    |
+| `@rogue-x/engine/tools`    | Authoring helpers (content validation).                |
+| `@rogue-x/engine/testing`  | Headless test session helpers.                         |
+
+Optional, swappable modules (e.g. pathfinding) live in
+[`@rogue-x/engine-modules`](https://www.npmjs.com/package/@rogue-x/engine-modules).
+
+## License
+
+MIT

package/dist/actions.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Actions / commands (ENG-47 … ENG-51).
+ *
+ * An action is mode-agnostic: it declares a target type, optional eligibility,
+ * optional cost, and an optional duration, and is invocable from any mode
+ * (ENG-47). These helpers are pure — they read a {@link StepContext} and return
+ * either a rejection (the engine writes nothing, ENG-48) or a {@link Transaction}
+ * the engine commits atomically (ENG-58):
+ *
+ *  - {@link evaluateAction} validates and produces the commit for one invocation;
+ *    an **instant** action (duration 0) folds its `resolve` into the commit, a
+ *    **durative** action enqueues an {@link InProgressAction} (ENG-49);
+ *  - {@link tickActions} advances the durative queue one step, resolving any that
+ *    reach zero remaining;
+ *  - {@link cancelAction} removes an in-progress action and refunds its cost iff
+ *    the definition is refundable (ENG-50);
+ *  - {@link queryActions} answers availability with the ENG-51 three-way result:
+ *    `available` / `locked` (identifying the locking action) / `none`.
+ */
+import type { ActionDefinition, ActionId, ActionTarget, DefaultGameTypes, GameTypes, InProgressAction, StepContext, Transaction } from './types.js';
+/** Action definitions indexed by id for O(1) lookup. */
+export type ActionRegistry<G extends GameTypes = DefaultGameTypes> = Record<ActionId, ActionDefinition<G>>;
+/** Build a registry from a flat list (last definition per id wins). */
+export declare function indexActions<G extends GameTypes = DefaultGameTypes>(defs: ActionDefinition<G>[]): ActionRegistry<G>;
+/** Why an invocation was rejected as a no-op (ENG-48). */
+export type ActionRejectReason = 'unknown' | 'ineligible' | 'locked' | 'concurrency' | 'cost';
+/** Imperative invocation outcome surfaced by the engine (ENG-48). */
+export type ActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ActionRejectReason;
+    lockedBy?: ActionId;
+};
+/** Pure evaluation: a rejection, or the transaction to commit. */
+export type ActionEvaluation<G extends GameTypes = DefaultGameTypes> = {
+    ok: true;
+    transaction: Transaction<G>;
+} | {
+    ok: false;
+    reason: ActionRejectReason;
+    lockedBy?: ActionId;
+};
+/** Availability answer for a target (ENG-51). */
+export type ActionQuery = {
+    kind: 'available';
+    actions: ActionId[];
+} | {
+    kind: 'locked';
+    by: ActionId;
+} | {
+    kind: 'none';
+};
+/** Structural target equality (locking / availability, ENG-51). */
+export declare function isActionTargetEqual(a: ActionTarget, b: ActionTarget): boolean;
+/**
+ * Validate one invocation and, if valid, produce the transaction to commit.
+ * Rejection order mirrors ENG-48: unknown → ineligible → locked → concurrency →
+ * cost. Nothing here mutates state (ENG-58, rejection before commit).
+ */
+export declare function evaluateAction<G extends GameTypes = DefaultGameTypes>(ctx: StepContext<G>, registry: ActionRegistry<G>, actionId: ActionId, target: ActionTarget): ActionEvaluation<G>;
+export interface ActionTick<G extends GameTypes = DefaultGameTypes> {
+    /** The durative queue after one step's decrement. */
+    actions: InProgressAction[];
+    /** Resolutions from actions that completed this step. */
+    transactions: Transaction<G>[];
+}
+/**
+ * Advance the durative queue by one step: decrement each remaining, resolve any
+ * that hit zero (and drop them), keep the rest (ENG-49). Pure — the engine folds
+ * the returned `actions` and `transactions` into the step's atomic commit.
+ */
+export declare function tickActions<G extends GameTypes = DefaultGameTypes>(ctx: StepContext<G>, registry: ActionRegistry<G>): ActionTick<G>;
+/**
+ * Cancel the first in-progress action matching `predicate`, refunding its cost
+ * iff the definition is refundable (ENG-50). Returns `null` when none match.
+ */
+export declare function cancelAction<G extends GameTypes = DefaultGameTypes>(ctx: StepContext<G>, registry: ActionRegistry<G>, predicate: (a: InProgressAction) => boolean): Transaction<G> | null;
+/**
+ * Availability for a target (ENG-51): `locked` (with the locking action) takes
+ * precedence; otherwise the eligible/affordable/uncapped actions, or `none`.
+ */
+export declare function queryActions<G extends GameTypes = DefaultGameTypes>(ctx: StepContext<G>, registry: ActionRegistry<G>, target: ActionTarget): ActionQuery;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EAEhB,WAAW,EACX,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,wDAAwD;AACxD,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,IAAI,MAAM,CACzE,QAAQ,EACR,gBAAgB,CAAC,CAAC,CAAC,CACpB,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACjE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,GAC1B,cAAc,CAAC,CAAC,CAAC,CAInB;AAED,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,aAAa,GACb,MAAM,CAAC;AAEX,qEAAqE;AACrE,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnE,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,IAC/D;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnE,iDAAiD;AACjD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAkB7E;AAgDD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACnE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,gBAAgB,CAAC,CAAC,CAAC,CAyCrB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB;IAChE,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,yDAAyD;IACzD,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EAChE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,UAAU,CAAC,CAAC,CAAC,CAaf;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACjE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,SAAS,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,OAAO,GAC1C,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAWvB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACjE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,MAAM,EAAE,YAAY,GACnB,WAAW,CAYb"}

package/dist/actions.js

@@ -0,0 +1,170 @@
+import { composePatches } from './patches.js';
+import { toLocKey } from './coords.js';
+/** Build a registry from a flat list (last definition per id wins). */
+export function indexActions(defs) {
+    const out = {};
+    for (const def of defs)
+        out[def.id] = def;
+    return out;
+}
+/** Structural target equality (locking / availability, ENG-51). */
+export function isActionTargetEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    switch (a.kind) {
+        case 'tile': {
+            const t = b;
+            return (a.scene === t.scene &&
+                a.layer === t.layer &&
+                toLocKey(a.loc) === toLocKey(t.loc));
+        }
+        case 'entity':
+            return a.id === b.id;
+        case 'abstract':
+            return a.key === b.key;
+        case 'global':
+            return true;
+    }
+}
+/** Discrete targets (tile/entity/abstract) lock; `global` is never lockable. */
+function targetLockedBy(queue, target) {
+    if (target.kind === 'global')
+        return null;
+    for (const a of queue) {
+        if (isActionTargetEqual(a.target, target))
+            return a.actionId;
+    }
+    return null;
+}
+function costOf(def, ctx, target) {
+    return def.cost ? def.cost(ctx, target) : {};
+}
+function affordable(cost, ctx) {
+    for (const k of Object.keys(cost)) {
+        if ((ctx.run.resources[k] ?? 0) < cost[k])
+            return false;
+    }
+    return true;
+}
+function concurrencyExceeded(def, ctx) {
+    if (def.maxConcurrent === undefined)
+        return false;
+    let n = 0;
+    for (const a of ctx.run.actions)
+        if (a.actionId === def.id)
+            n++;
+    return n >= def.maxConcurrent;
+}
+function negate(cost) {
+    const out = {};
+    for (const k of Object.keys(cost))
+        out[k] = -cost[k];
+    return out;
+}
+/**
+ * Validate one invocation and, if valid, produce the transaction to commit.
+ * Rejection order mirrors ENG-48: unknown → ineligible → locked → concurrency →
+ * cost. Nothing here mutates state (ENG-58, rejection before commit).
+ */
+export function evaluateAction(ctx, registry, actionId, target) {
+    const def = registry[actionId];
+    if (!def)
+        return { ok: false, reason: 'unknown' };
+    if (def.targetType !== target.kind)
+        return { ok: false, reason: 'ineligible' };
+    if (def.eligibility && !def.eligibility(ctx, target)) {
+        return { ok: false, reason: 'ineligible' };
+    }
+    const lockedBy = targetLockedBy(ctx.run.actions, target);
+    if (lockedBy)
+        return { ok: false, reason: 'locked', lockedBy };
+    if (concurrencyExceeded(def, ctx))
+        return { ok: false, reason: 'concurrency' };
+    const cost = costOf(def, ctx, target);
+    if (!affordable(cost, ctx))
+        return { ok: false, reason: 'cost' };
+    const costPatch = Object.keys(cost).length > 0 ? { resources: negate(cost) } : {};
+    const duration = def.duration ?? 0;
+    if (duration > 0) {
+        const inProgress = {
+            actionId,
+            target,
+            startedStep: ctx.run.step,
+            duration,
+            remaining: duration,
+        };
+        const patch = composePatches([
+            costPatch,
+            { actions: [...ctx.run.actions, inProgress] },
+        ]);
+        return { ok: true, transaction: { patch } };
+    }
+    const resolved = def.resolve(ctx, target);
+    const patch = composePatches([resolved.patch, costPatch]);
+    return {
+        ok: true,
+        transaction: resolved.effects && resolved.effects.length > 0
+            ? { patch, effects: resolved.effects }
+            : { patch },
+    };
+}
+/**
+ * Advance the durative queue by one step: decrement each remaining, resolve any
+ * that hit zero (and drop them), keep the rest (ENG-49). Pure — the engine folds
+ * the returned `actions` and `transactions` into the step's atomic commit.
+ */
+export function tickActions(ctx, registry) {
+    const actions = [];
+    const transactions = [];
+    for (const a of ctx.run.actions) {
+        const remaining = a.remaining - 1;
+        if (remaining <= 0) {
+            const def = registry[a.actionId];
+            if (def)
+                transactions.push(def.resolve(ctx, a.target));
+        }
+        else {
+            actions.push({ ...a, remaining });
+        }
+    }
+    return { actions, transactions };
+}
+/**
+ * Cancel the first in-progress action matching `predicate`, refunding its cost
+ * iff the definition is refundable (ENG-50). Returns `null` when none match.
+ */
+export function cancelAction(ctx, registry, predicate) {
+    const idx = ctx.run.actions.findIndex(predicate);
+    if (idx < 0)
+        return null;
+    const a = ctx.run.actions[idx];
+    const actions = ctx.run.actions.filter((_, i) => i !== idx);
+    const def = registry[a.actionId];
+    let patch = { actions };
+    if (def?.refundOnCancel && def.cost) {
+        patch = composePatches([patch, { resources: def.cost(ctx, a.target) }]);
+    }
+    return { patch };
+}
+/**
+ * Availability for a target (ENG-51): `locked` (with the locking action) takes
+ * precedence; otherwise the eligible/affordable/uncapped actions, or `none`.
+ */
+export function queryActions(ctx, registry, target) {
+    const lockedBy = targetLockedBy(ctx.run.actions, target);
+    if (lockedBy)
+        return { kind: 'locked', by: lockedBy };
+    const actions = [];
+    for (const def of Object.values(registry)) {
+        if (def.targetType !== target.kind)
+            continue;
+        if (def.eligibility && !def.eligibility(ctx, target))
+            continue;
+        if (concurrencyExceeded(def, ctx))
+            continue;
+        if (!affordable(costOf(def, ctx, target), ctx))
+            continue;
+        actions.push(def.id);
+    }
+    return actions.length > 0 ? { kind: 'available', actions } : { kind: 'none' };
+}

package/dist/assemble.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Game-definition assembler (ENG-69, ENG-73).
+ *
+ * The kernel ({@link createEngine}) runs on a low-level {@link EngineConfig}
+ * (a concrete `initialRun`, producers, events, actions). A {@link GameDefinition}
+ * is the *authoring* surface: a profile plus content (scenes, tile palette,
+ * optional onStep/actions/events/modes). This module is the missing glue that
+ * compiles the authoring surface into a runnable config, so a host can mount a
+ * game from its declaration alone.
+ *
+ * It is **platform-agnostic** (no React, React Native, or DOM imports), so the
+ * same assembler powers the web host (storybook) and the native host (ENG-75).
+ */
+import type { DefaultGameTypes, GameDefinition, GameTypes, ProfileState, RunState, StorageAdapter } from './types.js';
+import { type Engine, type EngineConfig } from './engine.js';
+import type { PersistenceKeys } from './persistence.js';
+/** Tuning a host supplies when assembling a definition (all optional). */
+export interface AssembleOptions<G extends GameTypes = DefaultGameTypes> {
+    /** Seed for scene generation + the run RNG (default 1; ENG-61). */
+    seed?: number;
+    /** Profile-scope state fed to {@link GameDefinition.initialRun} (ENG-5). */
+    profile?: ProfileState<G>;
+    /** Injectable persistence backend; no-op without one (ENG-64). */
+    storage?: StorageAdapter;
+    /** Per-scope storage keys (ENG-65). */
+    persistenceKeys?: PersistenceKeys;
+}
+/**
+ * Build the canonical {@link RunState} for a definition: every scene constructed
+ * from its spec (a generator scene draws from the shared seeded RNG, ENG-24), the
+ * initial mode stack, and the seeded resources/flags/vars. A game-supplied
+ * {@link GameDefinition.initialRun} hook shallow-overrides the result (ENG-5).
+ */
+export declare function buildInitialRun<G extends GameTypes = DefaultGameTypes>(def: GameDefinition<G>, options?: AssembleOptions<G>): RunState<G>;
+/**
+ * Compile a {@link GameDefinition} into a kernel {@link EngineConfig}. The single
+ * `onStep` hook becomes a producer (ENG-41); actions/events/autosave pass through;
+ * topology resolution uses the engine default (square4/square8/continuous).
+ */
+export declare function buildEngineConfig<G extends GameTypes = DefaultGameTypes>(def: GameDefinition<G>, options?: AssembleOptions<G>): EngineConfig<G>;
+/**
+ * Convenience: assemble a definition and create the running kernel in one call —
+ * the entry point a host uses to mount a game from its declaration (ENG-73).
+ */
+export declare function createGame<G extends GameTypes = DefaultGameTypes>(def: GameDefinition<G>, options?: AssembleOptions<G>): Engine<G>;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,YAAY,EACZ,QAAQ,EAER,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,YAAY,EAAqB,MAAM,aAAa,CAAC;AAG9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,0EAA0E;AAC1E,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB;IACrE,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1B,kEAAkE;IAClE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,uCAAuC;IACvC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACpE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAC/B,QAAQ,CAAC,CAAC,CAAC,CAyBb;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EACtE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAC/B,YAAY,CAAC,CAAC,CAAC,CAYjB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,GAAG,gBAAgB,EAC/D,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAC/B,MAAM,CAAC,CAAC,CAAC,CAEX"}

package/dist/assemble.js

@@ -0,0 +1,68 @@
+import { createEngine } from './engine.js';
+import { buildScene } from './scene.js';
+import { createRng } from './rng.js';
+const emptyProfile = () => ({
+    unlocks: {},
+    stats: {},
+    meta: {},
+});
+/**
+ * Build the canonical {@link RunState} for a definition: every scene constructed
+ * from its spec (a generator scene draws from the shared seeded RNG, ENG-24), the
+ * initial mode stack, and the seeded resources/flags/vars. A game-supplied
+ * {@link GameDefinition.initialRun} hook shallow-overrides the result (ENG-5).
+ */
+export function buildInitialRun(def, options = {}) {
+    const seed = options.seed ?? 1;
+    const rng = createRng(seed);
+    const scenes = {};
+    for (const [id, spec] of Object.entries(def.scenes)) {
+        scenes[id] = buildScene(id, spec, rng);
+    }
+    const base = {
+        activeSceneId: def.initialSceneId,
+        scenes,
+        resources: { ...(def.initialResources ?? {}) },
+        flags: { ...(def.initialFlags ?? {}) },
+        vars: (def.initialVars ?? {}),
+        actions: [],
+        eventCooldowns: {},
+        modeStack: def.initialModes ? [...def.initialModes] : [],
+        step: 0,
+        rngSeed: seed,
+    };
+    if (!def.initialRun)
+        return base;
+    const profile = options.profile ?? emptyProfile();
+    return { ...base, ...def.initialRun(profile) };
+}
+/**
+ * Compile a {@link GameDefinition} into a kernel {@link EngineConfig}. The single
+ * `onStep` hook becomes a producer (ENG-41); actions/events/autosave pass through;
+ * topology resolution uses the engine default (square4/square8/continuous).
+ */
+export function buildEngineConfig(def, options = {}) {
+    const producers = def.onStep ? [def.onStep] : [];
+    const config = {
+        initialRun: buildInitialRun(def, options),
+        producers,
+    };
+    if (def.events)
+        config.events = def.events;
+    if (def.actions)
+        config.actions = def.actions;
+    if (def.autosaveEvery !== undefined)
+        config.autosaveEvery = def.autosaveEvery;
+    if (options.storage)
+        config.storage = options.storage;
+    if (options.persistenceKeys)
+        config.persistenceKeys = options.persistenceKeys;
+    return config;
+}
+/**
+ * Convenience: assemble a definition and create the running kernel in one call —
+ * the entry point a host uses to mount a game from its declaration (ENG-73).
+ */
+export function createGame(def, options = {}) {
+    return createEngine(buildEngineConfig(def, options));
+}

package/dist/assets.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Asset-loading conventions shared by games built on the engine.
+ *
+ * Static assets (audio, images) need two different loading strategies because
+ * the engine runs on two very different runtimes:
+ *
+ *   - Native (Expo / React Native): assets are bundled by Metro and referenced
+ *     with a literal `require('../assets/foo.mp3')`, which resolves to an opaque
+ *     module id (a number) at build time.
+ *   - Web (Expo web served behind Replit's path-based proxy): assets live in the
+ *     app's `public/` directory and are loaded by URL. The URL must include the
+ *     app's path prefix (e.g. `/sim-game/audio/foo.mp3`) so the proxy routes it
+ *     to the right artifact.
+ *
+ * These helpers centralise the runtime detection, base-path derivation, and the
+ * require()-guard so individual games don't each reinvent them. The actual
+ * `require(...)` calls MUST stay in the game package with string literals —
+ * Metro statically analyses requires and cannot follow a require() that lives in
+ * a shared library or takes a variable. See `tryRequireAsset` below.
+ */
+import type { AssetRef, AudioConfig } from './types.js';
+/**
+ * True when running in a web browser DOM. False under React Native (no
+ * `document`) and false in Node/Vitest, so server-side tooling and unit tests
+ * take the native code path.
+ */
+export declare function isWebRuntime(): boolean;
+/**
+ * On web, derive the app's path prefix from the current URL (the first
+ * non-empty path segment, e.g. `/sim-game`). Replit serves each artifact behind
+ * such a prefix, and `public/` assets must be requested through it. Returns an
+ * empty string off-web or when the app is served from the root.
+ */
+export declare function webBasePath(): string;
+/**
+ * Build a web URL for a file served from the app's `public/` directory,
+ * prefixed with the artifact base path so Replit's proxy routes it correctly.
+ * `relativePath` is relative to `public/` (e.g. `audio/theme.mp3`).
+ */
+export declare function webPublicAsset(relativePath: string): AssetRef;
+/**
+ * Guard a literal `require()` of a bundled asset so it can't crash environments
+ * where the bundler isn't present (Node, Vitest, web). Pass a thunk that does
+ * the require with a STRING LITERAL argument:
+ *
+ *   tryRequireAsset(() => require('../assets/audio/theme.mp3'))
+ *
+ * Returns the resolved asset reference, or an empty string when the require
+ * fails (asset missing, or running outside Metro).
+ */
+export declare function tryRequireAsset(load: () => unknown): AssetRef;
+/**
+ * Pick the runtime-appropriate AudioConfig: the web map (public/ URLs) in a
+ * browser, the native map (bundled requires) everywhere else. Keeps the
+ * isWebRuntime() branch out of each game's audio setup.
+ */
+export declare function buildAudioConfig(maps: {
+    web: AudioConfig;
+    native: AudioConfig;
+}): AudioConfig;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,CAG7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,OAAO,GAAG,QAAQ,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,WAAW,CAE7F"}

package/dist/assets.js

@@ -0,0 +1,58 @@
+/**
+ * True when running in a web browser DOM. False under React Native (no
+ * `document`) and false in Node/Vitest, so server-side tooling and unit tests
+ * take the native code path.
+ */
+export function isWebRuntime() {
+    return typeof document !== 'undefined';
+}
+/**
+ * On web, derive the app's path prefix from the current URL (the first
+ * non-empty path segment, e.g. `/sim-game`). Replit serves each artifact behind
+ * such a prefix, and `public/` assets must be requested through it. Returns an
+ * empty string off-web or when the app is served from the root.
+ */
+export function webBasePath() {
+    if (!isWebRuntime() || typeof window === 'undefined')
+        return '';
+    const segment = window.location.pathname.split('/').find((s) => s.length > 0);
+    return segment ? `/${segment}` : '';
+}
+/**
+ * Build a web URL for a file served from the app's `public/` directory,
+ * prefixed with the artifact base path so Replit's proxy routes it correctly.
+ * `relativePath` is relative to `public/` (e.g. `audio/theme.mp3`).
+ */
+export function webPublicAsset(relativePath) {
+    const clean = relativePath.replace(/^\/+/, '');
+    return `${webBasePath()}/${clean}`;
+}
+/**
+ * Guard a literal `require()` of a bundled asset so it can't crash environments
+ * where the bundler isn't present (Node, Vitest, web). Pass a thunk that does
+ * the require with a STRING LITERAL argument:
+ *
+ *   tryRequireAsset(() => require('../assets/audio/theme.mp3'))
+ *
+ * Returns the resolved asset reference, or an empty string when the require
+ * fails (asset missing, or running outside Metro).
+ */
+export function tryRequireAsset(load) {
+    try {
+        const ref = load();
+        if (typeof ref === 'number' || typeof ref === 'string')
+            return ref;
+        return '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pick the runtime-appropriate AudioConfig: the web map (public/ URLs) in a
+ * browser, the native map (bundled requires) everywhere else. Keeps the
+ * isWebRuntime() branch out of each game's audio setup.
+ */
+export function buildAudioConfig(maps) {
+    return isWebRuntime() ? maps.web : maps.native;
+}

package/dist/audio.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Audio abstraction for the engine.
+ *
+ * The engine is platform-agnostic: it does NOT depend on Expo or any concrete
+ * audio backend. The consuming app provides an implementation of `AudioPlayer`
+ * (e.g. an expo-av-backed player) and injects it where the engine is mounted.
+ * A no-op player is used by default so the engine runs headless (tests, SSR).
+ */
+export interface AudioPlayer {
+    preload(): Promise<void>;
+    playMusic(key: string): Promise<void>;
+    stopMusic(): Promise<void>;
+    playSfx(key: string): Promise<void>;
+    setMusicVolume(vol: number): void;
+    setSfxVolume(vol: number): void;
+    unload(): Promise<void>;
+}
+/** A silent AudioPlayer — used when no concrete implementation is injected. */
+export declare function createNoopAudioPlayer(): AudioPlayer;
+//# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,IAAI,WAAW,CAUnD"}

package/dist/audio.js

@@ -0,0 +1,12 @@
+/** A silent AudioPlayer — used when no concrete implementation is injected. */
+export function createNoopAudioPlayer() {
+    return {
+        async preload() { },
+        async playMusic() { },
+        async stopMusic() { },
+        async playSfx() { },
+        setMusicVolume() { },
+        setSfxVolume() { },
+        async unload() { },
+    };
+}