@datamoc/mw_games 0.15.0 → 0.17.0

package/dist/simulation/Runtime.js

@@ -1,5 +1,6 @@
 import { Generator } from '../core/Random.js';
 import { ActionJournal } from '../core/ActionJournal.js';
+import { cloneData } from '../core/Clone.js';
 import { stateChecksum } from '../core/SyncGuard.js';
 import { UndoHistory } from '../core/UndoHistory.js';
 import { Scheduler } from '../roguelike/Scheduler.js';
@@ -85,6 +86,15 @@ export function validateSimulationReplay(initial, entries, options) {
  * automatic-actor loop and fixed-command replay respectively; a game composes both against
  * the same `scheduler` rather than choosing one over the other.
  *
+ * Every command and event batch is journalled, and with `history` every committed state is
+ * checkpointed, all through `structuredClone`: `Command`, `Event` and `State` must be plain data.
+ * A command naming its target as a live actor object (one that owns a `ReactionTable`, or any
+ * other callback) cannot be copied, so carry the actor's id and resolve it in the rule. A
+ * `dispatch` whose command, events or checkpoint cannot be copied throws a `TypeError` naming
+ * the offending path and commits nothing: state, scheduler, random stream and journal stay as
+ * they were before the call. The type system cannot enforce this, since a class instance with
+ * methods is perfectly cloneable while a plain object with one function field is not.
+ *
  * @example
  * ```ts
  * import { SimulationRuntime, type SimulationRuntimeRule } from '@datamoc/mw_games/simulation';
@@ -142,13 +152,23 @@ export class SimulationRuntime {
     /** Runs one command through the rule, commits the resulting state, and charges its cost
      * to the scheduler's current actor when one is given. */
     dispatch(command) {
+        const random = this.random.getState();
         const outcome = this.rule(this._state, command, { random: this.random, scheduler: this._scheduler });
+        let checkpoint;
+        try {
+            checkpoint = this.history ? cloneData(outcome.state, 'state') : null;
+            // Last fallible step, so a refused command or event batch leaves the journal unchanged.
+            this.journal.append(command, outcome.events);
+        }
+        catch (error) {
+            this.random.setState(random);
+            throw error;
+        }
         this._state = outcome.state;
         if (outcome.cost != null)
             this._scheduler.spend(outcome.cost);
-        this.journal.append(command, outcome.events);
         if (this.history)
-            this.history.push(this.historySnapshot());
+            this.history.push(this.historySnapshot(checkpoint));
         return outcome;
     }
     get canUndo() {
@@ -204,8 +224,9 @@ export class SimulationRuntime {
             actorId: options.actorId,
         });
     }
-    historySnapshot() {
-        return structuredClone(this.snapshot());
+    /** `snapshot()` already copies the scheduler, random state and journal; only state is live. */
+    historySnapshot(state = cloneData(this._state, 'state')) {
+        return { ...this.snapshot(), state };
     }
     restoreCheckpoint(snapshot) {
         if (!this.actorOf)

package/dist/simulation/Runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"Runtime.js","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Runtime.js","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,105 @@
+import { type SaveStorage } from '../core/Save.ts';
+import type { WebSocketLike } from '../core/Multiplayer.ts';
+import type { Playable } from '../audio/Playable.ts';
+/**
+ * Test doubles for the seams mwg already takes by injection, so a game's tests (and this
+ * repository's own) do not each rewrite them: a storage for `SaveSystem`, `Settings`,
+ * `Collection` and the stored counters, a `Playable` for `Sound`/`Music`'s `create`, a socket for
+ * `LockstepClient`'s `create`, and a `fetch` for every `HttpTransport` client. Renderer-free and
+ * dependency-free, and kept off the root barrel, so nothing here reaches a shipped game unless
+ * a test imports it.
+ *
+ * @example
+ * ```ts
+ * import { SaveSystem } from '@datamoc/mw_games/core';
+ * import { memoryStorage } from '@datamoc/mw_games/testing';
+ *
+ * const saves = new SaveSystem<{ gold: number }>({ namespace: 'test', version: 1, storage: memoryStorage() });
+ * saves.save('slot1', { gold: 3 });
+ * ```
+ */
+export declare function memoryStorage(): SaveStorage;
+/** a `Playable` that records how often it was played */
+export interface FakePlayable extends Playable {
+    playCount: number;
+    paused: boolean;
+}
+/**
+ * A `Playable` for `Sound`/`Music`'s `create` option (`create: fakeAudio` works as is):
+ * `play()` counts and unpauses, `pause()` pauses.
+ *
+ * @example
+ * ```ts
+ * import { Sound } from '@datamoc/mw_games/audio';
+ * import { fakeAudio } from '@datamoc/mw_games/testing';
+ *
+ * const audio = fakeAudio();
+ * const sound = new Sound('hit.wav', { poolSize: 1, create: () => audio });
+ * sound.play();
+ * console.log(audio.playCount); // 1
+ * ```
+ */
+export declare function fakeAudio(): FakePlayable;
+/**
+ * `fakeAudio` with an `onended` slot, which is how a backend that reports the end of a track
+ * looks to the audio classes; `audio.onended?.(new Event('ended'))` ends it.
+ */
+export declare function fakeAudioWithEnded(): FakePlayable;
+/**
+ * A `WebSocketLike` for `LockstepClient`'s `create` option: `sent` holds what the client sent,
+ * `receive(message)` delivers a server message as JSON (`receiveRaw` delivers text as is), and
+ * `close()` fires `onclose`.
+ *
+ * @example
+ * ```ts
+ * import { LockstepClient } from '@datamoc/mw_games/core';
+ * import { FakeSocket } from '@datamoc/mw_games/testing';
+ *
+ * const socket = new FakeSocket();
+ * const client = new LockstepClient({ url: 'wss://example.test', create: () => socket });
+ * client.connect();
+ * socket.receive({ type: 'welcome', id: 'p1' });
+ * ```
+ */
+export declare class FakeSocket implements WebSocketLike {
+    readyState: number;
+    readonly sent: string[];
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    send(data: string): void;
+    close(): void;
+    receive(message: unknown): void;
+    receiveRaw(data: string): void;
+}
+/** one request a `fakeFetch` received */
+export interface FakeFetchCall {
+    url: string;
+    init?: RequestInit;
+}
+/**
+ * A `fetch` for any `HttpTransport` client's `fetch` option: `respond` answers each request,
+ * with a `Response` or with a plain value sent as a JSON body, and `calls` records them in order.
+ *
+ * @example
+ * ```ts
+ * import { NewsClient } from '@datamoc/mw_games/core';
+ * import { fakeFetch } from '@datamoc/mw_games/testing';
+ *
+ * const fetch = fakeFetch(() => [{ id: '1', title: 'Patch notes', body: 'Fixed things.' }]);
+ * const news = new NewsClient({ endpoint: 'https://example.test/news', fetch });
+ * ```
+ */
+export declare function fakeFetch(respond: (url: string, init?: RequestInit) => unknown): typeof globalThis.fetch & {
+    calls: FakeFetchCall[];
+};
+/**
+ * A `Gamepad` for `Input`/`PlayerInput` tests: `buttons` are values from 0 to 1 (pressed above
+ * 0.5), `axes` from -1 to 1. Hand it to the code under test the way `navigator.getGamepads()`
+ * would.
+ */
+export declare function fakeGamepad(index: number, buttons?: number[], axes?: number[]): Gamepad;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,WAAW,CAE3C;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAexC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,YAAW,aAAa;IAC/C,UAAU,SAAK;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAM;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAClD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAClD,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAE7D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvB;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE9B;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7B;CACD;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,GACnD,OAAO,UAAU,CAAC,KAAK,GAAG;IAAE,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAStD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,EAAO,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAM/F"}

package/dist/testing/index.js

@@ -0,0 +1,134 @@
+import { MemoryStorage } from '../core/Save.js';
+/**
+ * Test doubles for the seams mwg already takes by injection, so a game's tests (and this
+ * repository's own) do not each rewrite them: a storage for `SaveSystem`, `Settings`,
+ * `Collection` and the stored counters, a `Playable` for `Sound`/`Music`'s `create`, a socket for
+ * `LockstepClient`'s `create`, and a `fetch` for every `HttpTransport` client. Renderer-free and
+ * dependency-free, and kept off the root barrel, so nothing here reaches a shipped game unless
+ * a test imports it.
+ *
+ * @example
+ * ```ts
+ * import { SaveSystem } from '@datamoc/mw_games/core';
+ * import { memoryStorage } from '@datamoc/mw_games/testing';
+ *
+ * const saves = new SaveSystem<{ gold: number }>({ namespace: 'test', version: 1, storage: memoryStorage() });
+ * saves.save('slot1', { gold: 3 });
+ * ```
+ */
+export function memoryStorage() {
+    return new MemoryStorage();
+}
+/**
+ * A `Playable` for `Sound`/`Music`'s `create` option (`create: fakeAudio` works as is):
+ * `play()` counts and unpauses, `pause()` pauses.
+ *
+ * @example
+ * ```ts
+ * import { Sound } from '@datamoc/mw_games/audio';
+ * import { fakeAudio } from '@datamoc/mw_games/testing';
+ *
+ * const audio = fakeAudio();
+ * const sound = new Sound('hit.wav', { poolSize: 1, create: () => audio });
+ * sound.play();
+ * console.log(audio.playCount); // 1
+ * ```
+ */
+export function fakeAudio() {
+    return {
+        playCount: 0,
+        paused: true,
+        volume: 1,
+        currentTime: 0,
+        loop: false,
+        play() {
+            this.playCount++;
+            this.paused = false;
+        },
+        pause() {
+            this.paused = true;
+        },
+    };
+}
+/**
+ * `fakeAudio` with an `onended` slot, which is how a backend that reports the end of a track
+ * looks to the audio classes; `audio.onended?.(new Event('ended'))` ends it.
+ */
+export function fakeAudioWithEnded() {
+    return { ...fakeAudio(), onended: null };
+}
+/**
+ * A `WebSocketLike` for `LockstepClient`'s `create` option: `sent` holds what the client sent,
+ * `receive(message)` delivers a server message as JSON (`receiveRaw` delivers text as is), and
+ * `close()` fires `onclose`.
+ *
+ * @example
+ * ```ts
+ * import { LockstepClient } from '@datamoc/mw_games/core';
+ * import { FakeSocket } from '@datamoc/mw_games/testing';
+ *
+ * const socket = new FakeSocket();
+ * const client = new LockstepClient({ url: 'wss://example.test', create: () => socket });
+ * client.connect();
+ * socket.receive({ type: 'welcome', id: 'p1' });
+ * ```
+ */
+export class FakeSocket {
+    constructor() {
+        this.readyState = 1;
+        this.sent = [];
+        this.onopen = null;
+        this.onclose = null;
+        this.onerror = null;
+        this.onmessage = null;
+    }
+    send(data) {
+        this.sent.push(data);
+    }
+    close() {
+        this.readyState = 3;
+        this.onclose?.(undefined);
+    }
+    receive(message) {
+        this.receiveRaw(JSON.stringify(message));
+    }
+    receiveRaw(data) {
+        this.onmessage?.({ data });
+    }
+}
+/**
+ * A `fetch` for any `HttpTransport` client's `fetch` option: `respond` answers each request,
+ * with a `Response` or with a plain value sent as a JSON body, and `calls` records them in order.
+ *
+ * @example
+ * ```ts
+ * import { NewsClient } from '@datamoc/mw_games/core';
+ * import { fakeFetch } from '@datamoc/mw_games/testing';
+ *
+ * const fetch = fakeFetch(() => [{ id: '1', title: 'Patch notes', body: 'Fixed things.' }]);
+ * const news = new NewsClient({ endpoint: 'https://example.test/news', fetch });
+ * ```
+ */
+export function fakeFetch(respond) {
+    const calls = [];
+    const fetch = async (input, init) => {
+        const url = String(input);
+        calls.push({ url, init });
+        const answer = await respond(url, init);
+        return answer instanceof Response ? answer : new Response(JSON.stringify(answer), { status: 200 });
+    };
+    return Object.assign(fetch, { calls });
+}
+/**
+ * A `Gamepad` for `Input`/`PlayerInput` tests: `buttons` are values from 0 to 1 (pressed above
+ * 0.5), `axes` from -1 to 1. Hand it to the code under test the way `navigator.getGamepads()`
+ * would.
+ */
+export function fakeGamepad(index, buttons = [], axes = []) {
+    return {
+        index,
+        buttons: buttons.map((value) => ({ pressed: value > 0.5, touched: value > 0.5, value })),
+        axes,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,iBAAiB,CAAC;AAIlE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa;IAC5B,OAAO,IAAI,aAAa,EAAE,CAAC;AAC5B,CAAC;AAQD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS;IACxB,OAAO;QACN,SAAS,EAAE,CAAC;QACZ,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,CAAC;QACT,WAAW,EAAE,CAAC;QACd,IAAI,EAAE,KAAK;QACX,IAAI;YACH,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,KAAK;YACJ,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACpB,CAAC;KACD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IACjC,OAAO,EAAE,GAAG,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,UAAU;IAAvB;QACC,eAAU,GAAG,CAAC,CAAC;QACN,SAAI,GAAa,EAAE,CAAC;QAC7B,WAAM,GAAsC,IAAI,CAAC;QACjD,YAAO,GAAsC,IAAI,CAAC;QAClD,YAAO,GAAsC,IAAI,CAAC;QAClD,cAAS,GAA+C,IAAI,CAAC;IAkB9D,CAAC;IAhBA,IAAI,CAAC,IAAY;QAChB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,KAAK;QACJ,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,CAAC,OAAgB;QACvB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU,CAAC,IAAY;QACtB,IAAI,CAAC,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5B,CAAC;CACD;AAQD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACxB,OAAqD;IAErD,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,KAAK,EAAE,KAAwB,EAAE,IAAkB,EAAE,EAAE;QACpE,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,OAAO,MAAM,YAAY,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACpG,CAAC,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,KAAgC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,OAAO,GAAa,EAAE,EAAE,IAAI,GAAa,EAAE;IACrF,OAAO;QACN,KAAK;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,GAAG,GAAG,EAAE,OAAO,EAAE,KAAK,GAAG,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACxF,IAAI;KACkB,CAAC;AACzB,CAAC"}

package/dist/two-d/render/RpgmAutotile.d.ts

@@ -62,4 +62,221 @@ export declare class RpgmAutotileAtlas {
     get(tileId: number, slot: RpgmAutotileSlot, shape: number): RpgmAutotileFrame;
     clear(): void;
 }
+/**
+ * The first MV tile id of each autotile family (A1-A4): slot 0 covers
+ * 2048-2815, slot 1 covers 2816-4351, slot 2 covers 4352-5887 and slot 3
+ * covers 5888-8191. Measured against real A-sheets rather than assumed.
+ */
+export declare const RPGM_AUTOTILE_SLOT_BASES: readonly [2048, 2816, 4352, 5888];
+/**
+ * How many MV tile ids each family holds: 16, 32, 32 and 48 kinds of
+ * 48 shapes each. A sheet holding fewer cells than its slot needs is a
+ * truncated custom sheet, not a different layout.
+ */
+export declare const RPGM_AUTOTILE_SLOT_COUNTS: readonly [768, 1536, 1536, 2304];
+/**
+ * Which MV autotile family a raw map tile id belongs to, or null when the id
+ * is not an autotile at all (an `EMPTY` cell, a static B-E tile, an A5 tile).
+ *
+ * @example
+ * ```ts
+ * import {
+ * 	rpgmAutotileSlot,
+ * 	RPGM_AUTOTILE_SLOT_BASES,
+ * 	RPGM_AUTOTILE_SLOT_COUNTS,
+ * } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(rpgmAutotileSlot(2048)); // 0 - the first A1 tile
+ * console.log(rpgmAutotileSlot(3000)); // 1 - inside the A2 range
+ * console.log(rpgmAutotileSlot(42)); // null - a static tile, not an autotile
+ * console.log(rpgmAutotileSlot(-1)); // null - EMPTY reads as blank, never as a slot
+ * console.log(RPGM_AUTOTILE_SLOT_BASES[0]); // 2048 - where slot 0 starts
+ * console.log(RPGM_AUTOTILE_SLOT_COUNTS[0]); // 768 - 16 kinds times 48 shapes
+ * ```
+ */
+export declare function rpgmAutotileSlot(tile: number): RpgmAutotileSlot | null;
+/**
+ * The standard MV floor-autotile shape table (48 shapes), for slots 0-1:
+ * which four atlas quadrants each baked shape assembles, in 24px source
+ * cells. Entries are `[x, y]` offsets, row-major `[topLeft, topRight,
+ * bottomLeft, bottomRight]`, exactly the shape numbering MV bakes into map
+ * tile ids (`shape = (tile - base) % 48`).
+ *
+ * Functional interop data, the same category as `BLOB_SHAPES`: every game
+ * reading MV maps needs these numbers, so they live here once rather than
+ * pasted into every port.
+ *
+ * @example
+ * ```ts
+ * import { RPGM_FLOOR_AUTOTILE_TABLE, RPGM_WALL_AUTOTILE_TABLE } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(RPGM_FLOOR_AUTOTILE_TABLE.length); // 48 - one entry per baked shape
+ * console.log(RPGM_WALL_AUTOTILE_TABLE.length); // 16 - walls cycle every 16 shapes
+ * console.log(RPGM_FLOOR_AUTOTILE_TABLE[47]); // [[0,0],[1,0],[0,1],[1,1]] - the full tile
+ * ```
+ */
+export declare const RPGM_FLOOR_AUTOTILE_TABLE: RpgmAutotileShapeTable;
+/**
+ * The standard MV wall-autotile shape table (16 shapes), for slots 2-3.
+ * Wall shapes cycle every 16 (`table[shape % 16]`), so a wall family holds
+ * three full cycles where a floor family holds one run of 48.
+ */
+export declare const RPGM_WALL_AUTOTILE_TABLE: RpgmAutotileShapeTable;
+/** one XP autotile pattern: four 16px mini-block indices, row-major `[topLeft, topRight, bottomLeft, bottomRight]` */
+export type XpAutotilePattern = readonly [number, number, number, number];
+/**
+ * The standard XP autotile pattern table (48 patterns). An XP autotile image
+ * is a 96 by 128 template: a 6-column grid of 16px mini-blocks, and each
+ * baked pattern assembles four of them. `tile % 48` selects the pattern;
+ * `tile / 48` (floored) selects which of the map's autotile images.
+ *
+ * Miniblock entries are 0-based here (block `n` sits at `(n % 6) * 16`,
+ * `(n / 6) * 16`). Learned from real XP autotile images and map data rather
+ * than assumed: the 6 by 8 mini-grid fits the measured 96 by 128 template
+ * exactly, and the neighbor table below reproduces baked map patterns.
+ *
+ * @example
+ * ```ts
+ * import { XP_AUTOTILE_PATTERNS, XP_NEIGHBORS_TO_PATTERN } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(XP_AUTOTILE_PATTERNS.length); // 48 - one entry per baked pattern
+ * console.log(XP_AUTOTILE_PATTERNS[0]); // [26,27,32,33] - the filled interior tile
+ * console.log(XP_NEIGHBORS_TO_PATTERN.length); // 256 - one entry per 8-neighbour mask
+ * console.log(XP_NEIGHBORS_TO_PATTERN[255]); // 0 - surrounded on all sides is the interior
+ * ```
+ */
+export declare const XP_AUTOTILE_PATTERNS: readonly XpAutotilePattern[];
+/**
+ * Which XP pattern an 8-neighbourhood of same-autotile cells bakes to. Index
+ * with a bit mask - north `0x01`, northeast `0x02`, east `0x04`, southeast
+ * `0x08`, south `0x10`, southwest `0x20`, west `0x40`, northwest `0x80` - for
+ * games computing patterns procedurally instead of reading baked map data.
+ */
+export declare const XP_NEIGHBORS_TO_PATTERN: readonly number[];
+/** an XP map cell decoded into its autotile image and baked pattern */
+export interface XpAutotileRef {
+    /** which autotile image, 0-7 (`tile / 48` floored) */
+    index: number;
+    /** which pattern in that image, 0-47 (`tile % 48`) */
+    pattern: number;
+}
+/**
+ * Decodes a raw XP map cell into its autotile image and pattern, or null
+ * when the cell holds no autotile reference: `EMPTY`, a static tileset tile
+ * (384 and up), or anything outside the 1-383 autotile range.
+ *
+ * @example
+ * ```ts
+ * import { xpAutotileRef } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(xpAutotileRef(97)); // { index: 2, pattern: 1 } - second image, second pattern
+ * console.log(xpAutotileRef(0)); // null - EMPTY is blank, never an autotile
+ * console.log(xpAutotileRef(384)); // null - the first static tileset tile
+ * ```
+ */
+export declare function xpAutotileRef(tile: number): XpAutotileRef | null;
+/**
+ * Which XP pattern a cell's 8-neighbourhood bakes to, for maps computed
+ * procedurally rather than read from baked data. `sameTerrain` is asked once
+ * per direction, with `(dx, dy)` offsets (`(0, -1)` is north); off the map is
+ * the caller's to answer (false reads as a border, the edge cell's own value
+ * clamps like the editor).
+ *
+ * @example
+ * ```ts
+ * import { xpAutotilePattern } from '@datamoc/mw_games/two-d/render';
+ *
+ * const filled = new Set(['0,0', '1,0', '0,1', '1,1', '-1,0', '0,-1', '2,1', '1,2']);
+ * console.log(xpAutotilePattern((dx, dy) => filled.has(`${dx},${dy}`))); // 0 - the interior
+ * console.log(xpAutotilePattern(() => false)); // 46 - isolated on all sides
+ * ```
+ */
+export declare function xpAutotilePattern(sameTerrain: (dx: number, dy: number) => boolean): number;
+/**
+ * One drawn piece of an autotile cell: where to sample the source sheet and
+ * where the piece lands on the map tile, the destination in fractions of one
+ * tile (quadrant halves at `0`/`0.5` with size `0.5`, or the whole tile at
+ * `0` with size `1` for single-tile strips).
+ */
+export interface AutotileCellPart {
+    sourceX: number;
+    sourceY: number;
+    sourceWidth: number;
+    sourceHeight: number;
+    destX: number;
+    destY: number;
+    destWidth: number;
+    destHeight: number;
+}
+/**
+ * An autotile source fully described: everything `autotileCellParts` needs
+ * except the sheet texture itself (which lives renderer-side, in the layer).
+ * `TileMap.addAutotileLayer` resolves a user-facing `AutotileSet` into one
+ * of these and validates it once with `assertAutotileLayout`, so per-cell
+ * resolution never re-checks the table.
+ */
+export type AutotileLayout = {
+    format: 'rpgm-mv';
+    slot: RpgmAutotileSlot;
+    table: RpgmAutotileShapeTable;
+    /** kind runs that advance together; a cell whose kind is in no run ignores the frame */
+    cycles: ReadonlyArray<ReadonlyArray<number>>;
+} | {
+    format: 'rpgm-xp';
+    /** which autotile image, 0-7 */
+    index: number;
+    /** animation stripes in the image; frame wraps around this count */
+    frames: number;
+    /** a 32px-tall single-tile strip: one whole-tile piece per frame, patterns ignored */
+    single: boolean;
+};
+/**
+ * Checks a resolved autotile layout once, up front. Throws naming the first
+ * problem: a bad slot, an empty shape table, an empty animation cycle, a
+ * cycle kind outside its slot's kinds, a bad XP index, or a frame count
+ * below one.
+ *
+ * @example
+ * ```ts
+ * import {
+ * 	assertAutotileLayout,
+ * 	RPGM_FLOOR_AUTOTILE_TABLE,
+ * } from '@datamoc/mw_games/two-d/render';
+ *
+ * assertAutotileLayout({ format: 'rpgm-mv', slot: 0, table: RPGM_FLOOR_AUTOTILE_TABLE, cycles: [[0, 1, 2]] });
+ * assertAutotileLayout({ format: 'rpgm-xp', index: 2, frames: 1, single: false });
+ * ```
+ */
+export declare function assertAutotileLayout(layout: AutotileLayout): void;
+/**
+ * Resolves one autotile cell to its drawn pieces: four quadrant halves for a
+ * template cell, one whole-tile piece for an XP single-tile strip, or null
+ * for a blank cell (`tile <= 0` reads as blank; `EMPTY` is -1).
+ *
+ * The layout is assumed valid (`assertAutotileLayout`); only the cell and
+ * frame are checked here. `tile` must be an integer the layout claims - an
+ * MV id in the layout's slot range, an XP id in `index * 48` to
+ * `index * 48 + 47` - and `frame` an integer at or above zero, wrapping
+ * around the animation cycles (MV) or frame stripes (XP).
+ *
+ * @example
+ * ```ts
+ * import {
+ * 	autotileCellParts,
+ * 	RPGM_FLOOR_AUTOTILE_TABLE,
+ * } from '@datamoc/mw_games/two-d/render';
+ *
+ * const parts = autotileCellParts(
+ * 	{ format: 'rpgm-mv', slot: 0, table: RPGM_FLOOR_AUTOTILE_TABLE, cycles: [] },
+ * 	2048, 0,
+ * );
+ * console.log(parts?.length); // 4 - one piece per quadrant
+ * console.log(parts?.[0].sourceWidth); // 24 - MV quadrant halves
+ * console.log(autotileCellParts(
+ * 	{ format: 'rpgm-xp', index: 2, frames: 1, single: false },
+ * 	97, 0,
+ * )?.[0].sourceWidth); // 16 - XP quadrant halves
+ * ```
+ */
+export declare function autotileCellParts(layout: AutotileLayout, tile: number, frame: number): AutotileCellPart[] | null;
 //# sourceMappingURL=RpgmAutotile.d.ts.map

package/dist/two-d/render/RpgmAutotile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RpgmAutotile.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/RpgmAutotile.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE7C,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;CAC7G;AAED,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,SAAS;IACxC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,SAAS,iBAAiB,EAAE,CAAC;AA2ClE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,sBAAsB,GAC3B,iBAAiB,CAqBnB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAE/C,YAAY,KAAK,EAAE,sBAAsB,EAGxC;IAED,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAO5E;IAED,KAAK,IAAI,IAAI,CAEZ;CACD"}
+{"version":3,"file":"RpgmAutotile.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/RpgmAutotile.ts"],"names":[],"mappings":"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"}