@datamoc/mw_games 0.4.1 → 0.4.2

package/dist/roguelike/Placement.d.ts

@@ -0,0 +1,62 @@
+import type { Level } from './Level.ts';
+/**
+ * Filters over terrain and occupancy for a placement pool - the seam a dungeon's
+ * feature/content hooks use to ask "which cells could this go on" without `FeatureLayer` or
+ * a game's own item/monster classes ever entering the picture. Every field is optional and
+ * narrows the pool further; omitting all of them is every cell on the level.
+ */
+export interface PlacementFilter {
+    /** raw terrain kind ids eligible (indices into the `Level`'s own `kinds`); omit for any kind */
+    terrain?: ReadonlySet<number>;
+    /** cells to exclude - already taken by another feature, a monster, an item */
+    occupied?: ReadonlySet<number>;
+    /** restrict the search to these cells (a room's interior, a hand-picked region); omit for the whole level */
+    within?: Iterable<number>;
+}
+/** Every cell on `level` matching `filter` - the pool a placement selects from. */
+export declare function candidateCells(level: Level, filter?: PlacementFilter): number[];
+/** Cells within `radius` neighbour-steps of `center` (via `Level.neighbors`, so hex and square both work), never including `center` itself. */
+export declare function cellsNear(level: Level, center: number, radius: number): number[];
+export interface PlacementTraceEntry {
+    requested: number;
+    available: number;
+    selected: number[];
+}
+export interface PlacementResult {
+    cells: number[];
+    trace: PlacementTraceEntry;
+}
+/**
+ * Picks `count` distinct cells out of `candidates` without replacement, falling back to
+ * however many exist when fewer are available rather than throwing or looping forever - a
+ * crowded region just gets fewer placements, the same "fail gracefully, place fewer" shape
+ * `generateDungeonGraph`'s own room placement already uses. Pure: nothing is placed or
+ * marked taken until the caller acts on `cells` itself (typically `FeatureLayer.place`, or
+ * folding `cells` into the next call's own `occupied` set). `trace` is plain, JSON-safe data
+ * a game can push straight into `DungeonArtifacts.content` for a parity check, or persist
+ * across save/load the same way any other roll trace does.
+ *
+ * Composes with `candidateCells` and `cellsNear` for the three shapes a regional generator
+ * needs: several neighbouring items (`cellsNear` around one anchor, intersected with a
+ * terrain/occupancy pool, then selected from), scattered decorations across a whole region
+ * (`candidateCells` with a large `within`, then selected from with a larger `count`), and a
+ * single branch or room reward (`candidateCells` scoped to one room, `count: 1`).
+ *
+ * @example
+ * ```ts
+ * import { candidateCells, cellsNear, selectDistinctCells } from '@datamoc/mw_games/roguelike';
+ *
+ * declare const level: import('@datamoc/mw_games/roguelike').Level;
+ * const FLOOR = new Set([1]);
+ *
+ * // scatter 3 decorations anywhere on the floor
+ * const pool = candidateCells(level, { terrain: FLOOR });
+ * const { cells: decorations, trace } = selectDistinctCells(pool, 3);
+ *
+ * // then release 2 more items clustered around one of those cells
+ * const nearby = cellsNear(level, decorations[0], 2).filter((c) => pool.includes(c));
+ * const { cells: cluster } = selectDistinctCells(nearby, 2);
+ * ```
+ */
+export declare function selectDistinctCells(candidates: readonly number[], count: number): PlacementResult;
+//# sourceMappingURL=Placement.d.ts.map

package/dist/roguelike/Placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Placement.d.ts","sourceRoot":"","sources":["../../src/roguelike/Placement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,gGAAgG;IAChG,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAE9B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAE/B,6GAA6G;IAC7G,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,eAAoB,GAAG,MAAM,EAAE,CAOnF;AAED,+IAA+I;AAC/I,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBhF;AAED,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,mBAAmB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAKjG"}

package/dist/roguelike/Placement.js

@@ -0,0 +1,79 @@
+import * as Random from '../core/Random.js';
+/** Every cell on `level` matching `filter` - the pool a placement selects from. */
+export function candidateCells(level, filter = {}) {
+    const source = filter.within ? [...filter.within] : range(level.cellCount);
+    return source.filter((cell) => {
+        if (filter.occupied?.has(cell))
+            return false;
+        if (filter.terrain && !filter.terrain.has(level.terrain[cell]))
+            return false;
+        return true;
+    });
+}
+/** Cells within `radius` neighbour-steps of `center` (via `Level.neighbors`, so hex and square both work), never including `center` itself. */
+export function cellsNear(level, center, radius) {
+    const seen = new Set([center]);
+    let frontier = [center];
+    for (let step = 0; step < Math.max(0, radius); step++) {
+        const next = [];
+        for (const cell of frontier) {
+            for (const { x, y } of level.neighbors(level.xOf(cell), level.yOf(cell))) {
+                if (!level.inside(x, y))
+                    continue;
+                const neighbor = level.index(x, y);
+                if (seen.has(neighbor))
+                    continue;
+                seen.add(neighbor);
+                next.push(neighbor);
+            }
+        }
+        frontier = next;
+    }
+    seen.delete(center);
+    return [...seen];
+}
+/**
+ * Picks `count` distinct cells out of `candidates` without replacement, falling back to
+ * however many exist when fewer are available rather than throwing or looping forever - a
+ * crowded region just gets fewer placements, the same "fail gracefully, place fewer" shape
+ * `generateDungeonGraph`'s own room placement already uses. Pure: nothing is placed or
+ * marked taken until the caller acts on `cells` itself (typically `FeatureLayer.place`, or
+ * folding `cells` into the next call's own `occupied` set). `trace` is plain, JSON-safe data
+ * a game can push straight into `DungeonArtifacts.content` for a parity check, or persist
+ * across save/load the same way any other roll trace does.
+ *
+ * Composes with `candidateCells` and `cellsNear` for the three shapes a regional generator
+ * needs: several neighbouring items (`cellsNear` around one anchor, intersected with a
+ * terrain/occupancy pool, then selected from), scattered decorations across a whole region
+ * (`candidateCells` with a large `within`, then selected from with a larger `count`), and a
+ * single branch or room reward (`candidateCells` scoped to one room, `count: 1`).
+ *
+ * @example
+ * ```ts
+ * import { candidateCells, cellsNear, selectDistinctCells } from '@datamoc/mw_games/roguelike';
+ *
+ * declare const level: import('@datamoc/mw_games/roguelike').Level;
+ * const FLOOR = new Set([1]);
+ *
+ * // scatter 3 decorations anywhere on the floor
+ * const pool = candidateCells(level, { terrain: FLOOR });
+ * const { cells: decorations, trace } = selectDistinctCells(pool, 3);
+ *
+ * // then release 2 more items clustered around one of those cells
+ * const nearby = cellsNear(level, decorations[0], 2).filter((c) => pool.includes(c));
+ * const { cells: cluster } = selectDistinctCells(nearby, 2);
+ * ```
+ */
+export function selectDistinctCells(candidates, count) {
+    const pool = [...new Set(candidates)];
+    Random.shuffle(pool);
+    const cells = pool.slice(0, Math.max(0, count));
+    return { cells, trace: { requested: count, available: pool.length, selected: cells } };
+}
+function range(n) {
+    const out = new Array(n);
+    for (let i = 0; i < n; i++)
+        out[i] = i;
+    return out;
+}
+//# sourceMappingURL=Placement.js.map

package/dist/roguelike/Placement.js.map

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

package/dist/roguelike/index.d.ts

@@ -34,4 +34,6 @@ export type { StealthOptions } from './Stealth.ts';
 export { TriggerTracker } from './TriggerTracker.ts';
 export { MultiStageAbility } from './MultiStageAbility.ts';
 export type { AbilityStage } from './MultiStageAbility.ts';
+export { candidateCells, cellsNear, selectDistinctCells } from './Placement.ts';
+export type { PlacementFilter, PlacementResult, PlacementTraceEntry } from './Placement.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/roguelike/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACjH,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAErG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE/G,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEhG,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEzF,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACtG,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChH,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/roguelike/index.ts"],"names":[],"mappings":"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"}

package/dist/roguelike/index.js

@@ -19,4 +19,5 @@ export { CombatHooks } from './Combat.js';
 export { Stealth } from './Stealth.js';
 export { TriggerTracker } from './TriggerTracker.js';
 export { MultiStageAbility } from './MultiStageAbility.js';
+export { candidateCells, cellsNear, selectDistinctCells } from './Placement.js';
 //# sourceMappingURL=index.js.map

package/dist/roguelike/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/roguelike/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGjH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEtG,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGhH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/roguelike/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGjH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEtG,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGhH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/three-d/Models.d.ts

@@ -1,5 +1,6 @@
 import '@babylonjs/loaders/glTF/index.js';
-import type { ImportMeshOptions, ISceneLoaderAsyncResult } from '@babylonjs/core/Loading/sceneLoader.js';
+import type { ImportMeshOptions, ISceneLoaderAsyncResult, LoadAssetContainerOptions } from '@babylonjs/core/Loading/sceneLoader.js';
+import type { AssetContainer } from '@babylonjs/core/assetContainer.js';
 import type { Scene } from '@babylonjs/core/scene.js';
 export type ModelSource3D = string | File | ArrayBufferView;
 /**
@@ -7,6 +8,42 @@ export type ModelSource3D = string | File | ArrayBufferView;
  * asset path is resolved through `mwg/assets` first, the same way every other loader in the
  * framework becomes `file://`-safe once assets are compiled to `data:` URIs; a URI that is
  * already resolved is passed through unchanged.
+ *
+ * For a single copy of a model this is the whole job; for several copies of the *same*
+ * model, `loadModelContainer3D` fetches and parses once and instantiates independent copies
+ * from it - calling this a second time for the same source imports and parses it again.
  */
 export declare function loadModel3D(source: ModelSource3D, scene: Scene, options?: ImportMeshOptions): Promise<ISceneLoaderAsyncResult>;
+/**
+ * Loads a model once per resolved source and caches the in-flight/loaded `AssetContainer`,
+ * so a second call for the same source returns the same container instead of importing and
+ * parsing it again over the network. A container is not itself scene content - call
+ * `container.instantiateModelsToScene()` for each independent copy a game wants to place,
+ * which is Babylon's own way to get several unaliased instances of one loaded model without
+ * a second fetch; `loadModel3D` imports straight into the scene instead, for the common case
+ * of only ever wanting one copy.
+ *
+ * Only caches when `source` is a string (an asset path or already-resolved URI) - a `File`
+ * or in-memory byte view has no stable identity to key a cache on, so those always load
+ * fresh, the same way `loadModel3D` never tries to resolve them as a path either.
+ *
+ * @example
+ * ```ts
+ * import { loadModelContainer3D, isModelContainerLoaded, releaseModelContainer } from '@datamoc/mw_games/3d/models';
+ *
+ * declare const scene: import('@babylonjs/core/scene.js').Scene;
+ *
+ * const container = await loadModelContainer3D('models/tree.glb', scene);
+ * const treeA = container.instantiateModelsToScene();
+ * const treeB = container.instantiateModelsToScene(); // a second, independent copy - no re-fetch
+ *
+ * console.log(isModelContainerLoaded('models/tree.glb')); // true
+ * releaseModelContainer('models/tree.glb'); // frees the container once every copy is placed
+ * ```
+ */
+export declare function loadModelContainer3D(source: ModelSource3D, scene: Scene, options?: LoadAssetContainerOptions): Promise<AssetContainer>;
+/** true once `loadModelContainer3D` has resolved for this source and it has not since been `releaseModelContainer`d */
+export declare function isModelContainerLoaded(source: string): boolean;
+/** disposes and forgets a cached container; a source never loaded (or already released) is silently skipped */
+export declare function releaseModelContainer(source: string): Promise<void>;
 //# sourceMappingURL=Models.d.ts.map

package/dist/three-d/Models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Models.d.ts","sourceRoot":"","sources":["../../src/three-d/Models.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACzG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAItD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,eAAe,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAG9H"}
+{"version":3,"file":"Models.d.ts","sourceRoot":"","sources":["../../src/three-d/Models.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACpI,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAItD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,eAAe,CAAC;AAM5D;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAE9H;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAYtI;AAED,uHAAuH;AACvH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,+GAA+G;AAC/G,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzE"}

package/dist/three-d/Models.js

@@ -1,14 +1,77 @@
 import '@babylonjs/loaders/glTF/index.js';
-import { ImportMeshAsync } from '@babylonjs/core/Loading/sceneLoader.js';
+import { ImportMeshAsync, LoadAssetContainerAsync } from '@babylonjs/core/Loading/sceneLoader.js';
 import { resolve } from '../assets/paths.js';
+function resolveSource(source) {
+    return typeof source === 'string' && !/^(?:data|blob|https?):/i.test(source) ? resolve(source) : source;
+}
 /**
  * Loads glTF/GLB from an asset path, data/blob/http(s) URI, File, or in-memory byte view. An
  * asset path is resolved through `mwg/assets` first, the same way every other loader in the
  * framework becomes `file://`-safe once assets are compiled to `data:` URIs; a URI that is
  * already resolved is passed through unchanged.
+ *
+ * For a single copy of a model this is the whole job; for several copies of the *same*
+ * model, `loadModelContainer3D` fetches and parses once and instantiates independent copies
+ * from it - calling this a second time for the same source imports and parses it again.
  */
 export function loadModel3D(source, scene, options) {
-    const resolved = typeof source === 'string' && !/^(?:data|blob|https?):/i.test(source) ? resolve(source) : source;
-    return ImportMeshAsync(resolved, scene, options);
+    return ImportMeshAsync(resolveSource(source), scene, options);
+}
+const containerCache = new Map();
+/**
+ * Loads a model once per resolved source and caches the in-flight/loaded `AssetContainer`,
+ * so a second call for the same source returns the same container instead of importing and
+ * parsing it again over the network. A container is not itself scene content - call
+ * `container.instantiateModelsToScene()` for each independent copy a game wants to place,
+ * which is Babylon's own way to get several unaliased instances of one loaded model without
+ * a second fetch; `loadModel3D` imports straight into the scene instead, for the common case
+ * of only ever wanting one copy.
+ *
+ * Only caches when `source` is a string (an asset path or already-resolved URI) - a `File`
+ * or in-memory byte view has no stable identity to key a cache on, so those always load
+ * fresh, the same way `loadModel3D` never tries to resolve them as a path either.
+ *
+ * @example
+ * ```ts
+ * import { loadModelContainer3D, isModelContainerLoaded, releaseModelContainer } from '@datamoc/mw_games/3d/models';
+ *
+ * declare const scene: import('@babylonjs/core/scene.js').Scene;
+ *
+ * const container = await loadModelContainer3D('models/tree.glb', scene);
+ * const treeA = container.instantiateModelsToScene();
+ * const treeB = container.instantiateModelsToScene(); // a second, independent copy - no re-fetch
+ *
+ * console.log(isModelContainerLoaded('models/tree.glb')); // true
+ * releaseModelContainer('models/tree.glb'); // frees the container once every copy is placed
+ * ```
+ */
+export function loadModelContainer3D(source, scene, options) {
+    const resolved = resolveSource(source);
+    if (typeof resolved !== 'string')
+        return LoadAssetContainerAsync(resolved, scene, options);
+    const cached = containerCache.get(resolved);
+    if (cached)
+        return cached;
+    const promise = LoadAssetContainerAsync(resolved, scene, options);
+    containerCache.set(resolved, promise);
+    //a rejected load must not poison the cache - the next call gets a fresh attempt
+    promise.catch(() => containerCache.delete(resolved));
+    return promise;
+}
+/** true once `loadModelContainer3D` has resolved for this source and it has not since been `releaseModelContainer`d */
+export function isModelContainerLoaded(source) {
+    const resolved = resolveSource(source);
+    return typeof resolved === 'string' && containerCache.has(resolved);
+}
+/** disposes and forgets a cached container; a source never loaded (or already released) is silently skipped */
+export async function releaseModelContainer(source) {
+    const resolved = resolveSource(source);
+    if (typeof resolved !== 'string')
+        return;
+    const cached = containerCache.get(resolved);
+    if (!cached)
+        return;
+    containerCache.delete(resolved);
+    (await cached).dispose();
 }
 //# sourceMappingURL=Models.js.map

package/dist/three-d/Models.js.map

@@ -1 +1 @@
-{"version":3,"file":"Models.js","sourceRoot":"","sources":["../../src/three-d/Models.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAIzE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,KAAY,EAAE,OAA2B;IAC3F,MAAM,QAAQ,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAClH,OAAO,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"Models.js","sourceRoot":"","sources":["../../src/three-d/Models.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAKlG,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C,SAAS,aAAa,CAAC,MAAqB;IAC3C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AACzG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,KAAY,EAAE,OAA2B;IAC3F,OAAO,eAAe,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,cAAc,GAAG,IAAI,GAAG,EAAmC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAqB,EAAE,KAAY,EAAE,OAAmC;IAC5G,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,uBAAuB,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAE3F,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAClE,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtC,gFAAgF;IAChF,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACpD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAAc;IACzD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO;IAEzC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC,MAAM,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;AAC1B,CAAC"}

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

@@ -1,6 +1,17 @@
 import type { AnimatedSprite } from './AnimatedSprite.ts';
 /** the three states any character's animation ever needs to be in */
 export type ActorAnimationState = 'idle' | 'move' | 'action';
+/**
+ * @example
+ * ```ts
+ * import type { ActorAnimatorOptions } from '@datamoc/mw_games/two-d/render';
+ *
+ * const options: ActorAnimatorOptions = {
+ * 	animationName: (state, facing) => `${state}-${facing}`,
+ * 	variant: 'down',
+ * };
+ * ```
+ */
 export interface ActorAnimatorOptions {
     /**
      * Names a state's animation, given whatever varies it - a facing direction for a grid
@@ -30,6 +41,27 @@ export interface ActorAnimatorOptions {
  *
  * This owns the sprite's `onFinish` hook entirely; a game driving one through
  * `ActorAnimator` should not also set `onFinish` itself.
+ *
+ * @example
+ * ```ts
+ * import { ActorAnimator, AnimatedSprite, SpriteSheet } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const sheet: SpriteSheet;
+ *
+ * const hero = new AnimatedSprite();
+ * hero.add('idle-down', sheet.pick(0), { fps: 2 });
+ * hero.add('move-down', sheet.range(1, 4), { fps: 10 });
+ * hero.add('action-down', sheet.range(5, 7), { fps: 12, loop: false });
+ *
+ * const animator = new ActorAnimator(hero, {
+ * 	animationName: (state, facing) => `${state}-${facing}`,
+ * 	variant: 'down',
+ * });
+ *
+ * animator.setMoving(true); // walk cycle starts
+ * animator.playAction(); // an attack swing cuts in over the walk cycle
+ * console.log(animator.state); // 'action' - overrides idle/move while it plays
+ * ```
  */
 export declare class ActorAnimator {
     private sprite;

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

@@ -1 +1 @@
-{"version":3,"file":"ActorAnimator.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/ActorAnimator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvE,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,aAAa,CAA0D;IAE/E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,oBAAoB,EAOhE;IAED,2FAA2F;IAC3F,IAAI,KAAK,IAAI,mBAAmB,CAE/B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIjD;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,IAAI,CAMlD;IAED,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,KAAK;CAIb"}
+{"version":3,"file":"ActorAnimator.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/ActorAnimator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvE,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,aAAa,CAA0D;IAE/E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,oBAAoB,EAOhE;IAED,2FAA2F;IAC3F,IAAI,KAAK,IAAI,mBAAmB,CAE/B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIjD;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,IAAI,CAMlD;IAED,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,KAAK;CAIb"}

package/dist/two-d/render/ActorAnimator.js

@@ -15,6 +15,27 @@
  *
  * This owns the sprite's `onFinish` hook entirely; a game driving one through
  * `ActorAnimator` should not also set `onFinish` itself.
+ *
+ * @example
+ * ```ts
+ * import { ActorAnimator, AnimatedSprite, SpriteSheet } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const sheet: SpriteSheet;
+ *
+ * const hero = new AnimatedSprite();
+ * hero.add('idle-down', sheet.pick(0), { fps: 2 });
+ * hero.add('move-down', sheet.range(1, 4), { fps: 10 });
+ * hero.add('action-down', sheet.range(5, 7), { fps: 12, loop: false });
+ *
+ * const animator = new ActorAnimator(hero, {
+ * 	animationName: (state, facing) => `${state}-${facing}`,
+ * 	variant: 'down',
+ * });
+ *
+ * animator.setMoving(true); // walk cycle starts
+ * animator.playAction(); // an attack swing cuts in over the walk cycle
+ * console.log(animator.state); // 'action' - overrides idle/move while it plays
+ * ```
  */
 export class ActorAnimator {
     constructor(sprite, options) {

package/dist/two-d/render/ActorAnimator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ActorAnimator.js","sourceRoot":"","sources":["../../../src/two-d/render/ActorAnimator.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,aAAa;IAQzB,YAAY,MAAsB,EAAE,OAA6B;QAHzD,eAAU,GAAoB,MAAM,CAAC;QACrC,aAAQ,GAAG,KAAK,CAAC;QAGxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IAED,2FAA2F;IAC3F,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IACnD,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAe,EAAE,OAAgB;QAC1C,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAClD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAgB,EAAE,OAAO,GAAG,KAAK;QAC3C,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;YAAE,OAAO;QACtC,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAElD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IAEO,cAAc;QACrB,gFAAgF;QAChF,iFAAiF;QACjF,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IAEO,KAAK,CAAC,KAA0B;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC;IACvE,CAAC;CACD"}
+{"version":3,"file":"ActorAnimator.js","sourceRoot":"","sources":["../../../src/two-d/render/ActorAnimator.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,OAAO,aAAa;IAQzB,YAAY,MAAsB,EAAE,OAA6B;QAHzD,eAAU,GAAoB,MAAM,CAAC;QACrC,aAAQ,GAAG,KAAK,CAAC;QAGxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IAED,2FAA2F;IAC3F,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IACnD,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAe,EAAE,OAAgB;QAC1C,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAClD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAgB,EAAE,OAAO,GAAG,KAAK;QAC3C,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;YAAE,OAAO;QACtC,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAElD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IAEO,cAAc;QACrB,gFAAgF;QAChF,iFAAiF;QACjF,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IAEO,KAAK,CAAC,KAA0B;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC;IACvE,CAAC;CACD"}

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

@@ -6,6 +6,18 @@ export interface AnimationOptions {
     /** whether to start again at the end, or hold on the last frame */
     loop?: boolean;
 }
+/**
+ * @example
+ * ```ts
+ * import { Animation } from '@datamoc/mw_games/two-d/render';
+ * import type { Texture2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const frames: Texture2D[];
+ *
+ * const walk = new Animation(frames, { fps: 10 });
+ * console.log(walk.duration); // frames.length / 10, in seconds
+ * ```
+ */
 export declare class Animation {
     readonly frames: readonly Texture2D[];
     readonly frameDuration: number;
@@ -17,18 +29,26 @@ export declare class Animation {
  * A sprite that plays named animations, and can still be tinted.
  *
  * Animations are registered once and played by name, which is how a character ends up
- * reading as `hero.play('walk')` rather than juggling frame arrays:
+ * reading as `hero.play('walk')` rather than juggling frame arrays.
  *
+ * Nothing advances on its own: call `update(dt)` from the scene, or add the sprite to a
+ * `SpriteGroup`, so that pausing the game pauses the animations with it.
+ *
+ * @example
  * ```ts
+ * import { AnimatedSprite, SpriteSheet } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const sheet: SpriteSheet;
+ *
  * const hero = new AnimatedSprite();
  * hero.add('idle', sheet.pick(0, 0, 0, 1), { fps: 2 });
  * hero.add('walk', sheet.range(6, 10), { fps: 10 });
  * hero.add('die', sheet.range(11, 14), { fps: 10, loop: false });
  * hero.play('idle');
- * ```
  *
- * Nothing advances on its own: call `update(dt)` from the scene, or add the sprite to a
- * `SpriteGroup`, so that pausing the game pauses the animations with it.
+ * hero.onFinish = (name) => console.log(`${name} finished`);
+ * hero.update(1 / 60); // advance one frame's worth of time
+ * ```
  */
 export declare class AnimatedSprite extends TintedSprite {
     private animations;

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

@@ -1 +1 @@
-{"version":3,"file":"AnimatedSprite.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/AnimatedSprite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAChC,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,mEAAmE;IACnE,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,SAAS;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,YAAY,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,EAAE,GAAQ,EAAE,IAAW,EAAE,GAAE,gBAAqB,EAKzF;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;CACD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC/C,OAAO,CAAC,UAAU,CAAgC;IAElD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAS;IAEzB,qEAAqE;IACrE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAEjD,MAAM,UAAS;IAEf,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGhF;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,IAAI,CAcxC;IAED,IAAI,IAAI,IAAI,CAGX;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAuBvB;CACD"}
+{"version":3,"file":"AnimatedSprite.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/AnimatedSprite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAChC,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,mEAAmE;IACnE,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,YAAY,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,EAAE,GAAQ,EAAE,IAAW,EAAE,GAAE,gBAAqB,EAKzF;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC/C,OAAO,CAAC,UAAU,CAAgC;IAElD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAS;IAEzB,qEAAqE;IACrE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAEjD,MAAM,UAAS;IAEf,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGhF;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,IAAI,CAcxC;IAED,IAAI,IAAI,IAAI,CAGX;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAuBvB;CACD"}

package/dist/two-d/render/AnimatedSprite.js

@@ -1,4 +1,16 @@
 import { TintedSprite } from './TintedSprite.js';
+/**
+ * @example
+ * ```ts
+ * import { Animation } from '@datamoc/mw_games/two-d/render';
+ * import type { Texture2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const frames: Texture2D[];
+ *
+ * const walk = new Animation(frames, { fps: 10 });
+ * console.log(walk.duration); // frames.length / 10, in seconds
+ * ```
+ */
 export class Animation {
     constructor(frames, { fps = 10, loop = true } = {}) {
         if (frames.length === 0)
@@ -15,18 +27,26 @@ export class Animation {
  * A sprite that plays named animations, and can still be tinted.
  *
  * Animations are registered once and played by name, which is how a character ends up
- * reading as `hero.play('walk')` rather than juggling frame arrays:
+ * reading as `hero.play('walk')` rather than juggling frame arrays.
  *
+ * Nothing advances on its own: call `update(dt)` from the scene, or add the sprite to a
+ * `SpriteGroup`, so that pausing the game pauses the animations with it.
+ *
+ * @example
  * ```ts
+ * import { AnimatedSprite, SpriteSheet } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const sheet: SpriteSheet;
+ *
  * const hero = new AnimatedSprite();
  * hero.add('idle', sheet.pick(0, 0, 0, 1), { fps: 2 });
  * hero.add('walk', sheet.range(6, 10), { fps: 10 });
  * hero.add('die', sheet.range(11, 14), { fps: 10, loop: false });
  * hero.play('idle');
- * ```
  *
- * Nothing advances on its own: call `update(dt)` from the scene, or add the sprite to a
- * `SpriteGroup`, so that pausing the game pauses the animations with it.
+ * hero.onFinish = (name) => console.log(`${name} finished`);
+ * hero.update(1 / 60); // advance one frame's worth of time
+ * ```
  */
 export class AnimatedSprite extends TintedSprite {
     constructor() {

package/dist/two-d/render/AnimatedSprite.js.map

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

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

@@ -24,9 +24,30 @@ export interface NeighborMask {
  * different engine's autotile layout will need its frames reordered into this one. What is
  * guaranteed: `BLOB_SHAPES` lists all 47 shapes in the exact order `blobIndex` returns them
  * in, so a tool (or a person, reading it once) can draw or arrange frames against it directly.
+ *
+ * @example
+ * ```ts
+ * import { BLOB_SHAPES } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(BLOB_SHAPES.length); // 47
+ * console.log(BLOB_SHAPES[0]); // { n: false, e: false, s: false, w: false, ne: false, se: false, sw: false, nw: false }
+ * ```
  */
 export declare const BLOB_SHAPES: readonly NeighborMask[];
-/** the blob index (0 to 46) for one cell's 8-neighbour membership test */
+/**
+ * the blob index (0 to 46) for one cell's 8-neighbour membership test
+ *
+ * @example
+ * ```ts
+ * import { blobIndex } from '@datamoc/mw_games/two-d/render';
+ *
+ * const surroundedOnAllSides = blobIndex({
+ * 	n: true, e: true, s: true, w: true,
+ * 	ne: true, se: true, sw: true, nw: true,
+ * });
+ * console.log(surroundedOnAllSides); // 46 - the fully-interior shape
+ * ```
+ */
 export declare function blobIndex(neighbors: NeighborMask): number;
 /**
  * One frame per cell of a terrain, autotiled from a same-terrain test alone.
@@ -37,6 +58,17 @@ export declare function blobIndex(neighbors: NeighborMask): number;
  * @param frames the 47 frames a `blobIndex` of 0 to 46 selects between, drawn (or arranged)
  * against `BLOB_SHAPES`
  * @returns one frame index per cell, row-major, `EMPTY` wherever `sameTerrain` is false
+ *
+ * @example
+ * ```ts
+ * import { autotileFrames, BLOB_SHAPES } from '@datamoc/mw_games/two-d/render';
+ *
+ * const water = new Set([0, 1, 10, 11]); // a 2x2 pond in a wider grid
+ * const frames = Array.from({ length: BLOB_SHAPES.length }, (_, index) => index); // frame N = shape N
+ *
+ * const cellFrames = autotileFrames(10, 10, (x, y) => water.has(y * 10 + x), frames);
+ * console.log(cellFrames[0]); // the blob frame for the pond's top-left corner
+ * ```
  */
 export declare function autotileFrames(width: number, height: number, sameTerrain: (x: number, y: number) => boolean, frames: readonly number[]): Int32Array;
 //# sourceMappingURL=Autotile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Autotile.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Autotile.ts"],"names":[],"mappings":"AAEA,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC5B,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,YAAY,EAAsB,CAAC;AAoEtE,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,EAC9C,MAAM,EAAE,SAAS,MAAM,EAAE,GACvB,UAAU,CA+BZ"}
+{"version":3,"file":"Autotile.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Autotile.ts"],"names":[],"mappings":"AAEA,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC5B,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,YAAY,EAAsB,CAAC;AAoEtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,EAC9C,MAAM,EAAE,SAAS,MAAM,EAAE,GACvB,UAAU,CA+BZ"}