@datamoc/mw_games 0.7.6 → 0.7.7

package/dist/ai/score.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The numbers behind a decision, for an AI that weighs outcomes instead of matching a behaviour.
+ *
+ * A rules agent decides from an opaque `perception` the game fills and from its own `state`, and a
+ * score exists only inside `alphaBetaSearch`, as the `evaluate` callback the game hands its own
+ * search. So a mind that wants to compare attacking against holding has nothing to weigh, and has
+ * to re-derive the game's valuation out of the perception blob, which is the duplication the
+ * envelope exists to prevent. These functions are that missing half: the framework owns how a view
+ * is assembled, the game owns what anything is worth (`scoreOf`), and the mind owns what it cares
+ * about (`ScorePersonality`).
+ *
+ * Both granularities the contract already names (`AIAgentDefinition.scope` is `'actor' |
+ * 'controller'`) run the same code and differ in one thing only: the visibility set they are handed.
+ * A unit's own sight for an actor, `FactionFog.sees(side)` for a whole side.
+ */
+/** A subject as a score view needs it: the game's own handle, its side, and where it stands. */
+export interface ScoreSubject<T> {
+    readonly id: T;
+    /** who it fights for; sides are compared by name, so allies share one */
+    readonly side: string;
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * What one mind can see, and what it is worth.
+ *
+ * The totals stay separate because which of them matter, and how much, is the mind's business -
+ * see `scoreWith`. Plain numbers, so a view crosses the AI boundary like any other `AIValue`.
+ */
+export interface ScoreView {
+    /** the subject's own score; 0 for a whole side, which has no body of its own */
+    readonly own: number;
+    /** the summed score of everyone on the subject's side that it can see, itself excluded */
+    readonly allies: number;
+    /** the summed score of everyone on another side that it can see */
+    readonly enemies: number;
+    /** how many subjects it could see at all, itself included: a diagnostic, never a score */
+    readonly seen: number;
+}
+/**
+ * A personality, as data: how much of each total is its owner's business.
+ *
+ * Weights rather than code, on purpose. A selfish scout is `{ own: 1, allies: 0, enemies: 0 }` and
+ * a loyal one `{ own: 0.5, allies: 1, enemies: 0 }`, both authored as content, and neither of them
+ * needing an AI implementation of its own. An enemy weight is usually negative, since an enemy's
+ * score rising is usually the subject's loss.
+ */
+export interface ScorePersonality {
+    readonly own: number;
+    readonly allies: number;
+    readonly enemies: number;
+}
+/**
+ * The view one subject has: its own score, and the scores of the allies and enemies it can see.
+ *
+ * `sees` is the visibility set, injected rather than assumed: a unit's own sight for an actor, the
+ * union over a side's units for a whole-side mind. The subject sees its own score whether or not it
+ * can see where it stands, so `own` is always read and `seen` always counts it.
+ *
+ * @example
+ * ```ts
+ * import { personalScoreView, scoreWith } from '@datamoc/mw_games/ai';
+ *
+ * const hero = { id: 'hero', side: 'blue', x: 2, y: 2 };
+ * const world = [
+ *   hero,
+ *   { id: 'ally', side: 'blue', x: 3, y: 2 },
+ *   { id: 'rat', side: 'red', x: 4, y: 2 },
+ *   { id: 'dragon', side: 'red', x: 9, y: 9 },
+ * ];
+ * const worth = (id: string) => ({ hero: 10, ally: 4, rat: -2, dragon: -40 })[id] ?? 0;
+ *
+ * // what a scout with a two-cell reach can see
+ * const sees = (x: number, y: number) => Math.abs(x - hero.x) + Math.abs(y - hero.y) <= 2;
+ *
+ * const view = personalScoreView(hero, world, worth, sees);
+ * console.log(view); // { own: 10, allies: 4, enemies: -2, seen: 3 } - the dragon is out of reach
+ * console.log(scoreWith(view, { own: 1, allies: 1, enemies: -1 })); // 16 - the rat is a nuisance
+ * ```
+ */
+export declare function personalScoreView<T>(subject: ScoreSubject<T>, world: readonly ScoreSubject<T>[], scoreOf: (id: T) => number, sees: (x: number, y: number) => boolean): ScoreView;
+/**
+ * The view a whole side has: every unit on it that the side can see, and every enemy it can see.
+ *
+ * `own` is 0, because a side has no body of its own - its units are what `allies` counts. Hand this
+ * the union of a side's sight (`FactionFog.sees(side)` after syncing every unit of it) and the same
+ * arithmetic that reads for one character reads for the player.
+ *
+ * @example
+ * ```ts
+ * import { FactionFog } from '@datamoc/mw_games/board';
+ * import { scoreWith, sideScoreView } from '@datamoc/mw_games/ai';
+ *
+ * const fog = new FactionFog(10, 10);
+ * const world = [
+ *   { id: 'scout', side: 'blue', x: 1, y: 1 },
+ *   { id: 'guard', side: 'blue', x: 7, y: 7 },
+ *   { id: 'rat', side: 'red', x: 3, y: 1 },
+ * ];
+ * const worth = (id: string) => ({ scout: 6, guard: 9, rat: -3 })[id] ?? 0;
+ *
+ * // the side reads what its units see: the scout alone would miss the rat at (3, 1)
+ * fog.sync('blue', [{ x: 4, y: 1 }], (source) => [source]);
+ * console.log(sideScoreView('blue', world, worth, fog.sees('blue')).enemies); // -3
+ * fog.sync('blue', [], () => []); // nobody watching, so nothing is read
+ * console.log(sideScoreView('blue', world, worth, fog.sees('blue')).enemies); // 0
+ * console.log(scoreWith(sideScoreView('blue', world, worth, fog.sees('blue')), { own: 0, allies: 1, enemies: -1 }));
+ * ```
+ */
+export declare function sideScoreView<T>(side: string, world: readonly ScoreSubject<T>[], scoreOf: (id: T) => number, sees: (x: number, y: number) => boolean): ScoreView;
+/**
+ * A view collapsed into the one number a mind compares, according to what that mind cares about.
+ *
+ * @example
+ * ```ts
+ * import { scoreWith, type ScoreView } from '@datamoc/mw_games/ai';
+ *
+ * const view: ScoreView = { own: 10, allies: 4, enemies: -2, seen: 3 };
+ *
+ * console.log(scoreWith(view, { own: 1, allies: 0, enemies: 0 })); // 10 - out for itself
+ * console.log(scoreWith(view, { own: 0, allies: 1, enemies: 0 })); // 4 - holds for the line
+ * console.log(scoreWith(view, { own: 1, allies: 1, enemies: -1 })); // 16 - the enemy is the point
+ * ```
+ */
+export declare function scoreWith(view: ScoreView, personality: ScorePersonality): number;
+//# sourceMappingURL=score.d.ts.map

package/dist/ai/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../../src/ai/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEf,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,EACjC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,MAAM,EAC1B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GACrC,SAAS,CAcX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,EACjC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,MAAM,EAC1B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GACrC,SAAS,CAaX;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,GAAG,MAAM,CAEhF"}

package/dist/ai/score.js

@@ -0,0 +1,121 @@
+/**
+ * The numbers behind a decision, for an AI that weighs outcomes instead of matching a behaviour.
+ *
+ * A rules agent decides from an opaque `perception` the game fills and from its own `state`, and a
+ * score exists only inside `alphaBetaSearch`, as the `evaluate` callback the game hands its own
+ * search. So a mind that wants to compare attacking against holding has nothing to weigh, and has
+ * to re-derive the game's valuation out of the perception blob, which is the duplication the
+ * envelope exists to prevent. These functions are that missing half: the framework owns how a view
+ * is assembled, the game owns what anything is worth (`scoreOf`), and the mind owns what it cares
+ * about (`ScorePersonality`).
+ *
+ * Both granularities the contract already names (`AIAgentDefinition.scope` is `'actor' |
+ * 'controller'`) run the same code and differ in one thing only: the visibility set they are handed.
+ * A unit's own sight for an actor, `FactionFog.sees(side)` for a whole side.
+ */
+/**
+ * The view one subject has: its own score, and the scores of the allies and enemies it can see.
+ *
+ * `sees` is the visibility set, injected rather than assumed: a unit's own sight for an actor, the
+ * union over a side's units for a whole-side mind. The subject sees its own score whether or not it
+ * can see where it stands, so `own` is always read and `seen` always counts it.
+ *
+ * @example
+ * ```ts
+ * import { personalScoreView, scoreWith } from '@datamoc/mw_games/ai';
+ *
+ * const hero = { id: 'hero', side: 'blue', x: 2, y: 2 };
+ * const world = [
+ *   hero,
+ *   { id: 'ally', side: 'blue', x: 3, y: 2 },
+ *   { id: 'rat', side: 'red', x: 4, y: 2 },
+ *   { id: 'dragon', side: 'red', x: 9, y: 9 },
+ * ];
+ * const worth = (id: string) => ({ hero: 10, ally: 4, rat: -2, dragon: -40 })[id] ?? 0;
+ *
+ * // what a scout with a two-cell reach can see
+ * const sees = (x: number, y: number) => Math.abs(x - hero.x) + Math.abs(y - hero.y) <= 2;
+ *
+ * const view = personalScoreView(hero, world, worth, sees);
+ * console.log(view); // { own: 10, allies: 4, enemies: -2, seen: 3 } - the dragon is out of reach
+ * console.log(scoreWith(view, { own: 1, allies: 1, enemies: -1 })); // 16 - the rat is a nuisance
+ * ```
+ */
+export function personalScoreView(subject, world, scoreOf, sees) {
+    let allies = 0;
+    let enemies = 0;
+    let seen = 1;
+    for (const other of world) {
+        if (other.id === subject.id)
+            continue;
+        if (!sees(other.x, other.y))
+            continue;
+        seen++;
+        if (other.side === subject.side)
+            allies += scoreOf(other.id);
+        else
+            enemies += scoreOf(other.id);
+    }
+    return { own: scoreOf(subject.id), allies, enemies, seen };
+}
+/**
+ * The view a whole side has: every unit on it that the side can see, and every enemy it can see.
+ *
+ * `own` is 0, because a side has no body of its own - its units are what `allies` counts. Hand this
+ * the union of a side's sight (`FactionFog.sees(side)` after syncing every unit of it) and the same
+ * arithmetic that reads for one character reads for the player.
+ *
+ * @example
+ * ```ts
+ * import { FactionFog } from '@datamoc/mw_games/board';
+ * import { scoreWith, sideScoreView } from '@datamoc/mw_games/ai';
+ *
+ * const fog = new FactionFog(10, 10);
+ * const world = [
+ *   { id: 'scout', side: 'blue', x: 1, y: 1 },
+ *   { id: 'guard', side: 'blue', x: 7, y: 7 },
+ *   { id: 'rat', side: 'red', x: 3, y: 1 },
+ * ];
+ * const worth = (id: string) => ({ scout: 6, guard: 9, rat: -3 })[id] ?? 0;
+ *
+ * // the side reads what its units see: the scout alone would miss the rat at (3, 1)
+ * fog.sync('blue', [{ x: 4, y: 1 }], (source) => [source]);
+ * console.log(sideScoreView('blue', world, worth, fog.sees('blue')).enemies); // -3
+ * fog.sync('blue', [], () => []); // nobody watching, so nothing is read
+ * console.log(sideScoreView('blue', world, worth, fog.sees('blue')).enemies); // 0
+ * console.log(scoreWith(sideScoreView('blue', world, worth, fog.sees('blue')), { own: 0, allies: 1, enemies: -1 }));
+ * ```
+ */
+export function sideScoreView(side, world, scoreOf, sees) {
+    let allies = 0;
+    let enemies = 0;
+    let seen = 0;
+    for (const other of world) {
+        if (!sees(other.x, other.y))
+            continue;
+        seen++;
+        if (other.side === side)
+            allies += scoreOf(other.id);
+        else
+            enemies += scoreOf(other.id);
+    }
+    return { own: 0, allies, enemies, seen };
+}
+/**
+ * A view collapsed into the one number a mind compares, according to what that mind cares about.
+ *
+ * @example
+ * ```ts
+ * import { scoreWith, type ScoreView } from '@datamoc/mw_games/ai';
+ *
+ * const view: ScoreView = { own: 10, allies: 4, enemies: -2, seen: 3 };
+ *
+ * console.log(scoreWith(view, { own: 1, allies: 0, enemies: 0 })); // 10 - out for itself
+ * console.log(scoreWith(view, { own: 0, allies: 1, enemies: 0 })); // 4 - holds for the line
+ * console.log(scoreWith(view, { own: 1, allies: 1, enemies: -1 })); // 16 - the enemy is the point
+ * ```
+ */
+export function scoreWith(view, personality) {
+    return view.own * personality.own + view.allies * personality.allies + view.enemies * personality.enemies;
+}
+//# sourceMappingURL=score.js.map

package/dist/ai/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../../src/ai/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA+CH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iBAAiB,CAChC,OAAwB,EACxB,KAAiC,EACjC,OAA0B,EAC1B,IAAuC;IAEvC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE;YAAE,SAAS;QACtC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QACtC,IAAI,EAAE,CAAC;QACP,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI;YAAE,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;;YACxD,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,aAAa,CAC5B,IAAY,EACZ,KAAiC,EACjC,OAA0B,EAC1B,IAAuC;IAEvC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QACtC,IAAI,EAAE,CAAC;QACP,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;YAAE,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;;YAChD,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,WAA6B;IACvE,OAAO,IAAI,CAAC,GAAG,GAAG,WAAW,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;AAC3G,CAAC"}

package/dist/assets/loader.d.ts

@@ -29,6 +29,16 @@ export interface LoadAssetsOptions {
      * own default, which is the SVG's intrinsic size.
      */
     resolution?: number;
+    /**
+     * Paths a game can do without - a portrait variant, an optional decal - loaded separately
+     * from the rest of the batch so one missing file never aborts every other asset the batch
+     * was loading. A path in here that fails to load is simply left unloaded: `isLoaded` reports
+     * `false` for it and `texture`'s fallback argument (or `get`'s) is what a caller reads
+     * instead, rather than every caller writing its own try/catch around `load()`.
+     */
+    optional?: readonly string[];
+    /** called once per `optional` path that failed to load, with whatever `Assets.load` threw */
+    onMissing?: (path: string, error: unknown) => void;
 }
 /**
  * Loads assets by path, giving each one an alias equal to its path.
@@ -38,10 +48,14 @@ export interface LoadAssetsOptions {
  * (the original signature) or a `LoadAssetsOptions` object for the resolution option.
  */
 export declare function load(paths: string[], options?: AssetProgress | LoadAssetsOptions): Promise<void>;
-/** a loaded texture, by the same path it was loaded with */
-export declare function texture(path: string): Texture;
-/** a loaded asset of any other kind, such as parsed JSON */
-export declare function get<T>(path: string): T;
+/**
+ * A loaded texture, by the same path it was loaded with. `fallback` is what an `optional`
+ * `load()` path was for: pass it (typically `Texture.EMPTY`) to get that back instead of a
+ * throw when the path never loaded, rather than every caller writing its own `isLoaded` guard.
+ */
+export declare function texture(path: string, fallback?: Texture): Texture;
+/** a loaded asset of any other kind, such as parsed JSON; `fallback` behaves as it does on `texture` */
+export declare function get<T>(path: string, fallback?: T): T;
 /** true once `load` has resolved for this path and it has not since been `release`d */
 export declare function isLoaded(path: string): boolean;
 /**

package/dist/assets/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/assets/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,aAAa,CAAC;IAE3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAa,GAAG,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB1G;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7C;AAED,4DAA4D;AAC5D,wBAAgB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKtC;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5D"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/assets/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,aAAa,CAAC;IAE3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7B,6FAA6F;IAC7F,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AASD;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAa,GAAG,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC1G;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAMjE;AAED,wGAAwG;AACxG,wBAAgB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAMpD;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5D"}

package/dist/assets/loader.js

@@ -8,30 +8,59 @@ import { resolve } from './paths.js';
  * (the original signature) or a `LoadAssetsOptions` object for the resolution option.
  */
 export async function load(paths, options = {}) {
-    const { onProgress, resolution } = typeof options === 'function' ? { onProgress: options, resolution: undefined } : options;
+    const { onProgress, resolution, optional, onMissing } = typeof options === 'function'
+        ? { onProgress: options, resolution: undefined, optional: undefined, onMissing: undefined }
+        : options;
+    const optionalPaths = new Set(optional ?? []);
     const pending = paths.filter((path) => !Assets.cache.has(path));
-    if (pending.length === 0) {
-        onProgress?.(1);
-        return;
-    }
-    for (const path of pending) {
+    const requiredPending = pending.filter((path) => !optionalPaths.has(path));
+    const optionalPending = pending.filter((path) => optionalPaths.has(path));
+    const add = (path) => {
         const descriptor = { alias: path, src: resolve(path) };
         if (resolution !== undefined)
             descriptor.data = { resolution };
         Assets.add(descriptor);
+    };
+    if (optionalPending.length === 0 && requiredPending.length === 0) {
+        onProgress?.(1);
+        return;
     }
-    await Assets.load(pending, onProgress);
+    for (const path of requiredPending)
+        add(path);
+    const requiredLoad = requiredPending.length > 0 ? Assets.load(requiredPending, onProgress) : Promise.resolve();
+    //loaded one at a time and never rejected past this function: one missing optional asset
+    //must never take the required batch (or any other optional path) down with it
+    const optionalLoads = optionalPending.map(async (path) => {
+        add(path);
+        try {
+            await Assets.load(path);
+        }
+        catch (error) {
+            onMissing?.(path, error);
+        }
+    });
+    await Promise.all([requiredLoad, ...optionalLoads]);
+    if (optionalPending.length > 0 && requiredPending.length === 0)
+        onProgress?.(1);
 }
-/** a loaded texture, by the same path it was loaded with */
-export function texture(path) {
+/**
+ * A loaded texture, by the same path it was loaded with. `fallback` is what an `optional`
+ * `load()` path was for: pass it (typically `Texture.EMPTY`) to get that back instead of a
+ * throw when the path never loaded, rather than every caller writing its own `isLoaded` guard.
+ */
+export function texture(path, fallback) {
     if (!Assets.cache.has(path)) {
+        if (fallback !== undefined)
+            return fallback;
         throw new Error(`texture "${path}" has not been loaded - pass it to load() first`);
     }
     return Assets.get(path);
 }
-/** a loaded asset of any other kind, such as parsed JSON */
-export function get(path) {
+/** a loaded asset of any other kind, such as parsed JSON; `fallback` behaves as it does on `texture` */
+export function get(path, fallback) {
     if (!Assets.cache.has(path)) {
+        if (fallback !== undefined)
+            return fallback;
         throw new Error(`asset "${path}" has not been loaded - pass it to load() first`);
     }
     return Assets.get(path);

package/dist/assets/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/assets/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAsB,MAAM,YAAY,CAAC;AA0CzD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,KAAe,EAAE,OAAO,GAAsC,EAAE;IAC1F,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAC/B,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAE1F,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO;IACR,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAoB,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,IAAI,UAAU,KAAK,SAAS;YAAE,UAAU,CAAC,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC;QAC/D,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACxB,CAAC;IACD,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,iDAAiD,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAU,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,GAAG,CAAI,IAAY;IAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,iDAAiD,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAI,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACpC,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAe;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/assets/loader.ts"],"names":[],"mappings":"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"}

package/dist/audio/Positional.d.ts

@@ -0,0 +1,125 @@
+import type { Sound } from './Sound.ts';
+/** A point in the same 2D space the game's camera works in, in world units. */
+export interface AudioPoint {
+    x: number;
+    y: number;
+}
+/**
+ * How far away a source can be heard from, and how fast it fades.
+ *
+ * `refDistance` is full volume, `maxDistance` is silence, and `rolloff` shapes the drop
+ * between them: 1 is inverse-linear, 2 inverse-square. These are the names the Web Audio
+ * `PannerNode` uses for the same three numbers, so a game that later moves to a real panner
+ * does not have to re-author them.
+ */
+export interface AudioFalloff {
+    /** distance at which the source is at full volume; defaults to 1 */
+    refDistance?: number;
+    /** distance at which the source is silent; defaults to Infinity */
+    maxDistance?: number;
+    /** exponent of the inverse-distance drop; defaults to 1 */
+    rolloff?: number;
+}
+/**
+ * The gain a listener at `distance` hears a source at, clamped to [0, 1]: 1 at or inside
+ * `refDistance`, 0 at or beyond `maxDistance`, an inverse-distance curve between them.
+ *
+ * @example
+ * ```ts
+ * import { audioGain } from '@datamoc/mw_games/audio';
+ *
+ * audioGain(0, { refDistance: 2 }); // 1 - inside the full-volume radius
+ * audioGain(2, { refDistance: 2 }); // 1 - the reference distance itself
+ * audioGain(4, { refDistance: 2 }); // 0.5 - one doubling away
+ * audioGain(4, { refDistance: 2, maxDistance: 4 }); // 0 - at the edge of hearing
+ * ```
+ */
+export declare function audioGain(distance: number, falloff?: AudioFalloff): number;
+/**
+ * Stereo pan in [-1, 1] for a source: -1 is hard left of the listener, 1 hard right, 0
+ * directly ahead or behind. The listener's `facing` is its heading in radians (0 faces +x,
+ * increasing clockwise on a screen where y grows downward), so turning the listener turns
+ * what counts as "right" with it - a sound to the world's east is centred when the listener
+ * faces east and hard right when the listener faces north.
+ *
+ * A game with a stereo backend applies this itself; the framework has no panner node of its
+ * own, so it reports the number rather than pretending to pan.
+ *
+ * @example
+ * ```ts
+ * import { audioPan } from '@datamoc/mw_games/audio';
+ *
+ * const listener = { x: 0, y: 0, facing: 0 }; // facing east
+ * audioPan(listener, { x: 10, y: 0 }); // 0 - straight ahead
+ * audioPan(listener, { x: 0, y: 10 }); // 1 - to the listener's right
+ * audioPan(listener, { x: 0, y: -10 }); // -1 - to its left
+ * ```
+ */
+export declare function audioPan(listener: AudioPoint & {
+    facing: number;
+}, source: AudioPoint): number;
+/**
+ * Where sounds are heard from: a game moves one listener to its camera or its party leader
+ * each frame, and every `SoundSource` is mixed against it.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 40, y: 12 });
+ * listener.moveTo(41, 12); // following the camera
+ * listener.face(Math.PI / 2); // now facing the world's south
+ * ```
+ */
+export declare class AudioListener implements AudioPoint {
+    x: number;
+    y: number;
+    /** heading in radians: 0 faces +x, increasing clockwise on a y-down screen */
+    facing: number;
+    constructor(options?: {
+        x?: number;
+        y?: number;
+        facing?: number;
+    });
+    moveTo(x: number, y: number): void;
+    face(radians: number): void;
+}
+export interface SoundSourceOptions extends AudioFalloff {
+    x?: number;
+    y?: number;
+}
+/**
+ * One positional one-shot: a `Sound` attached to a point in the world, heard from a
+ * listener with the distance gain `audioGain` computes. `playFor` applies that gain through
+ * `Sound.play(gain)`, and stays silent past `maxDistance` rather than playing at volume 0.
+ *
+ * Long-running position (a waterfall, an engine) is the game's own loop calling `playFor` on
+ * a cadence it chooses; this is the placement and the mix, not a scheduler.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener, Sound, SoundSource } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 0, y: 0 });
+ * const arrow = new Sound('sounds/arrow.mp3');
+ * const source = new SoundSource(arrow, { x: 6, y: 8, refDistance: 4, maxDistance: 20 });
+ *
+ * const gain = source.gainTo(listener); // 0.4 at distance 10
+ * source.playFor(listener); // plays at that gain, or not at all when silent
+ * ```
+ */
+export declare class SoundSource implements AudioPoint {
+    x: number;
+    y: number;
+    private readonly sound;
+    private readonly falloff;
+    constructor(sound: Sound, options?: SoundSourceOptions);
+    moveTo(x: number, y: number): void;
+    gainTo(listener: AudioPoint): number;
+    panTo(listener: AudioPoint & {
+        facing: number;
+    }): number;
+    /** Plays the source at the gain the listener hears it; returns the gain actually used. */
+    playFor(listener: AudioPoint): number;
+}
+//# sourceMappingURL=Positional.d.ts.map

package/dist/audio/Positional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Positional.d.ts","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAU9E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAW9F;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC/C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EAIpE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1B;CACD;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,YAAY,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,kBAAuB,EASzD;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,MAAM,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAEnC;IAED,KAAK,CAAC,QAAQ,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEvD;IAED,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAKpC;CACD"}

package/dist/audio/Positional.js

@@ -0,0 +1,135 @@
+/**
+ * The gain a listener at `distance` hears a source at, clamped to [0, 1]: 1 at or inside
+ * `refDistance`, 0 at or beyond `maxDistance`, an inverse-distance curve between them.
+ *
+ * @example
+ * ```ts
+ * import { audioGain } from '@datamoc/mw_games/audio';
+ *
+ * audioGain(0, { refDistance: 2 }); // 1 - inside the full-volume radius
+ * audioGain(2, { refDistance: 2 }); // 1 - the reference distance itself
+ * audioGain(4, { refDistance: 2 }); // 0.5 - one doubling away
+ * audioGain(4, { refDistance: 2, maxDistance: 4 }); // 0 - at the edge of hearing
+ * ```
+ */
+export function audioGain(distance, falloff = {}) {
+    const refDistance = falloff.refDistance ?? 1;
+    const maxDistance = falloff.maxDistance ?? Infinity;
+    const rolloff = falloff.rolloff ?? 1;
+    if (!(distance > refDistance))
+        return 1;
+    if (!(distance < maxDistance))
+        return 0;
+    const gain = Math.pow(refDistance / distance, rolloff);
+    return Math.max(0, Math.min(1, gain));
+}
+/**
+ * Stereo pan in [-1, 1] for a source: -1 is hard left of the listener, 1 hard right, 0
+ * directly ahead or behind. The listener's `facing` is its heading in radians (0 faces +x,
+ * increasing clockwise on a screen where y grows downward), so turning the listener turns
+ * what counts as "right" with it - a sound to the world's east is centred when the listener
+ * faces east and hard right when the listener faces north.
+ *
+ * A game with a stereo backend applies this itself; the framework has no panner node of its
+ * own, so it reports the number rather than pretending to pan.
+ *
+ * @example
+ * ```ts
+ * import { audioPan } from '@datamoc/mw_games/audio';
+ *
+ * const listener = { x: 0, y: 0, facing: 0 }; // facing east
+ * audioPan(listener, { x: 10, y: 0 }); // 0 - straight ahead
+ * audioPan(listener, { x: 0, y: 10 }); // 1 - to the listener's right
+ * audioPan(listener, { x: 0, y: -10 }); // -1 - to its left
+ * ```
+ */
+export function audioPan(listener, source) {
+    const dx = source.x - listener.x;
+    const dy = source.y - listener.y;
+    const distance = Math.hypot(dx, dy);
+    if (distance === 0)
+        return 0;
+    //the listener's right-hand direction at heading `facing`, in screen coordinates
+    const rightX = Math.sin(listener.facing);
+    const rightY = Math.cos(listener.facing);
+    const pan = (dx * rightX + dy * rightY) / distance;
+    return Math.max(-1, Math.min(1, pan));
+}
+/**
+ * Where sounds are heard from: a game moves one listener to its camera or its party leader
+ * each frame, and every `SoundSource` is mixed against it.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 40, y: 12 });
+ * listener.moveTo(41, 12); // following the camera
+ * listener.face(Math.PI / 2); // now facing the world's south
+ * ```
+ */
+export class AudioListener {
+    constructor(options = {}) {
+        this.x = options.x ?? 0;
+        this.y = options.y ?? 0;
+        this.facing = options.facing ?? 0;
+    }
+    moveTo(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    face(radians) {
+        this.facing = radians;
+    }
+}
+/**
+ * One positional one-shot: a `Sound` attached to a point in the world, heard from a
+ * listener with the distance gain `audioGain` computes. `playFor` applies that gain through
+ * `Sound.play(gain)`, and stays silent past `maxDistance` rather than playing at volume 0.
+ *
+ * Long-running position (a waterfall, an engine) is the game's own loop calling `playFor` on
+ * a cadence it chooses; this is the placement and the mix, not a scheduler.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener, Sound, SoundSource } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 0, y: 0 });
+ * const arrow = new Sound('sounds/arrow.mp3');
+ * const source = new SoundSource(arrow, { x: 6, y: 8, refDistance: 4, maxDistance: 20 });
+ *
+ * const gain = source.gainTo(listener); // 0.4 at distance 10
+ * source.playFor(listener); // plays at that gain, or not at all when silent
+ * ```
+ */
+export class SoundSource {
+    constructor(sound, options = {}) {
+        this.sound = sound;
+        this.x = options.x ?? 0;
+        this.y = options.y ?? 0;
+        this.falloff = {
+            refDistance: options.refDistance,
+            maxDistance: options.maxDistance,
+            rolloff: options.rolloff,
+        };
+    }
+    moveTo(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    gainTo(listener) {
+        return audioGain(Math.hypot(this.x - listener.x, this.y - listener.y), this.falloff);
+    }
+    panTo(listener) {
+        return audioPan(listener, this);
+    }
+    /** Plays the source at the gain the listener hears it; returns the gain actually used. */
+    playFor(listener) {
+        const gain = this.gainTo(listener);
+        if (gain <= 0)
+            return 0;
+        this.sound.play(gain);
+        return gain;
+    }
+}
+//# sourceMappingURL=Positional.js.map