@datamoc/mw_games 0.4.1 → 0.4.3

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"}

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

@@ -14,6 +14,14 @@ import { EMPTY } from './TileMap.js';
  * 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 const BLOB_SHAPES = buildBlobShapes();
 const blobIndexByMask = new Map(BLOB_SHAPES.map((shape, index) => [maskOf(shape), index]));
@@ -73,7 +81,20 @@ function buildBlobShapes() {
     shapes.sort((a, b) => a.mask - b.mask);
     return shapes.map((entry) => entry.shape);
 }
-/** 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 function blobIndex(neighbors) {
     return blobIndexByMask.get(maskOf(neighbors));
 }
@@ -86,6 +107,17 @@ export function blobIndex(neighbors) {
  * @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 function autotileFrames(width, height, sameTerrain, frames) {
     if (frames.length !== BLOB_SHAPES.length) {

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

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

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

@@ -7,6 +7,23 @@ import { Container } from 'pixi.js';
  * anything that should stay put on screen (the HUD, a dialogue box) goes outside it.
  *
  * Positions are in world units. At `zoom = 3` a 16px tile is 48 screen pixels.
+ *
+ * @example
+ * ```ts
+ * import { Camera, createCamera } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const stage: Container2D;
+ * declare const hero: { x: number; y: number };
+ *
+ * const camera = createCamera({ zoom: 3, deadzone: 0.3, pixelPerfectTileSize: 16 });
+ * stage.addChild(camera.world);
+ * camera.follow(hero);
+ *
+ * function onFrame(dt: number): void {
+ * 	camera.update(dt);
+ * }
+ * ```
  */
 export interface CameraOptions {
     /** screen pixels per world unit */
@@ -33,6 +50,25 @@ export interface CameraOptions {
      */
     pixelPerfectTileSize?: number;
 }
+/**
+ * @example
+ * ```ts
+ * import { Camera } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const stage: Container2D;
+ *
+ * const camera = new Camera({ zoom: 2 });
+ * camera.setViewport(960, 540);
+ * stage.addChild(camera.world);
+ *
+ * camera.snapTo(160, 160); // jump to the start room, no easing
+ * camera.follow({ x: 176, y: 160 }); // then ease towards wherever the hero is
+ * camera.update(1 / 60);
+ *
+ * const screenPoint = camera.toScreen(160, 160);
+ * ```
+ */
 export declare class Camera {
     /** put the map and everything in it here */
     readonly world: Container<import("pixi.js").ContainerChild>;
@@ -109,8 +145,24 @@ export declare class Camera {
  * The nearest zoom to `zoom` at which `tileSize * zoom` is a whole number of screen pixels -
  * the pure math behind `CameraOptions.pixelPerfectTileSize`, exported so a game can snap a
  * zoom value (from a slider, say) before ever handing it to a `Camera`.
+ *
+ * @example
+ * ```ts
+ * import { snapZoom } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(snapZoom(2.4, 16)); // 2.375 - 16 * 2.375 = 38, a whole number of pixels
+ * ```
  */
 export declare function snapZoom(zoom: number, tileSize: number): number;
-/** a camera sized to the running game's viewport, updated on every frame */
+/**
+ * a camera sized to the running game's viewport, updated on every frame
+ *
+ * @example
+ * ```ts
+ * import { createCamera } from '@datamoc/mw_games/two-d/render';
+ *
+ * const camera = createCamera({ zoom: 2 }); // sized to Game.current automatically
+ * ```
+ */
 export declare function createCamera(options?: CameraOptions): Camera;
 //# sourceMappingURL=Camera.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIpC;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,MAAM;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,8CAAmB;IAEjC,yCAAyC;IACzC,CAAC,SAAK;IACN,CAAC,SAAK;IAEN,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAS;IAE/C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAK;IAEpB,OAAO,CAAC,YAAY,CAAyC;IAG7D,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IAEnB,yFAAyF;IACzF,OAAO,CAAC,MAAM,CAA2E;IAEzF,YAAY,OAAO,GAAE,aAAkB,EAKtC;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAGrB;IAED;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAI,EAAE,OAAO,SAAI,GAAG,IAAI,CAKzE;IAED,4DAA4D;IAC5D,IAAI,IAAI,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAKlE;IAED,oEAAoE;IACpE,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,IAAI,CAEzF;IAED,wEAAwE;IACxE,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAMjC;IAED,kCAAkC;IAClC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,IAAI,CAG/C;IAED,oEAAoE;IACpE,MAAM,CAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,SAAS,SAAI,GAAG,IAAI,CAG5D;IAED,aAAa,IAAI,IAAI,CAGpB;IAED,2DAA2D;IAC3D,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,IAAI,CAG7C;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAgCvB;IAED,mCAAmC;IACnC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAUvD;IAED,oEAAoE;IACpE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAMtD;IAID,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,KAAK;CAQb;AAMD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAMhE"}
+{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Camera.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,25 @@
 import { Container } from 'pixi.js';
 import { Game } from '../Game.js';
 import * as Random from '../../core/Random.js';
+/**
+ * @example
+ * ```ts
+ * import { Camera } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const stage: Container2D;
+ *
+ * const camera = new Camera({ zoom: 2 });
+ * camera.setViewport(960, 540);
+ * stage.addChild(camera.world);
+ *
+ * camera.snapTo(160, 160); // jump to the start room, no easing
+ * camera.follow({ x: 176, y: 160 }); // then ease towards wherever the hero is
+ * camera.update(1 / 60);
+ *
+ * const screenPoint = camera.toScreen(160, 160);
+ * ```
+ */
 export class Camera {
     constructor(options = {}) {
         /** put the map and everything in it here */
@@ -166,12 +185,28 @@ function clamp(value, min, max) {
  * The nearest zoom to `zoom` at which `tileSize * zoom` is a whole number of screen pixels -
  * the pure math behind `CameraOptions.pixelPerfectTileSize`, exported so a game can snap a
  * zoom value (from a slider, say) before ever handing it to a `Camera`.
+ *
+ * @example
+ * ```ts
+ * import { snapZoom } from '@datamoc/mw_games/two-d/render';
+ *
+ * console.log(snapZoom(2.4, 16)); // 2.375 - 16 * 2.375 = 38, a whole number of pixels
+ * ```
  */
 export function snapZoom(zoom, tileSize) {
     const pixels = Math.max(1, Math.round(zoom * tileSize));
     return pixels / tileSize;
 }
-/** a camera sized to the running game's viewport, updated on every frame */
+/**
+ * a camera sized to the running game's viewport, updated on every frame
+ *
+ * @example
+ * ```ts
+ * import { createCamera } from '@datamoc/mw_games/two-d/render';
+ *
+ * const camera = createCamera({ zoom: 2 }); // sized to Game.current automatically
+ * ```
+ */
 export function createCamera(options = {}) {
     const camera = new Camera(options);
     const game = Game.current;