@datamoc/mw_games 0.4.1 → 0.4.2

package/README.md

@@ -1,4 +1,4 @@
-# mwg
+# 🟦🟨mwg
 
 A framework for building tile games that run **from a local file**: no server, no install,
 no runtime to download. The game logic depends on no renderer at all, so a game draws through

package/dist/assets/binary.d.ts

@@ -0,0 +1,52 @@
+import { type AssetProgress } from './paths.ts';
+/**
+ * Raw asset bytes, cached and progress-reported the same way `loader.ts`'s texture cache is -
+ * but renderer-free, so a Babylon-only game (or anything else that just wants an
+ * `ArrayBuffer`) gets the same `load`/`isLoaded`/`release` shape a 2D game's textures already
+ * have, without pulling Pixi in. `Vox.parseVox` is the direct beneficiary: it takes an
+ * `ArrayBuffer` a game previously had to fetch and cache by hand.
+ *
+ * Kept out of `loader.ts` itself for the same reason `paths.ts` is its own file: `loader.ts`
+ * is allowed to know about Pixi, `three-d` is allowed to know about Babylon, but neither
+ * should have to import the other's renderer just to share a byte cache.
+ *
+ * @example
+ * ```ts
+ * import { loadBinary, getBinary } from '@datamoc/mw_games/assets';
+ * import { parseVox, createVoxModel3D } from '@datamoc/mw_games/3d';
+ *
+ * await loadBinary(['models/rock.vox']);
+ * const model = parseVox(getBinary('models/rock.vox'));
+ * ```
+ */
+export interface LoadBinaryOptions {
+    /** overrides the fetch used to load bytes; defaults to `globalThis.fetch` */
+    fetch?: typeof globalThis.fetch;
+}
+/** Loads and caches raw bytes for every path not already cached; a path already loaded is a no-op. */
+export declare function loadBinary(paths: string[], onProgress?: AssetProgress, options?: LoadBinaryOptions): Promise<void>;
+/** a loaded asset's raw bytes, by the same path it was loaded with */
+export declare function getBinary(path: string): ArrayBuffer;
+/**
+ * true once `loadBinary` has resolved for this path and it has not since been `releaseBinary`d
+ *
+ * @example
+ * ```ts
+ * import { isBinaryLoaded } from '@datamoc/mw_games/assets';
+ *
+ * console.log(isBinaryLoaded('models/rock.vox')); // false until loadBinary resolves for it
+ * ```
+ */
+export declare function isBinaryLoaded(path: string): boolean;
+/**
+ * Frees cached bytes; a path never loaded (or already released) is silently skipped.
+ *
+ * @example
+ * ```ts
+ * import { releaseBinary } from '@datamoc/mw_games/assets';
+ *
+ * releaseBinary(['models/rock.vox']); // frees the cached bytes once the model is placed
+ * ```
+ */
+export declare function releaseBinary(paths: string[]): void;
+//# sourceMappingURL=binary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../../src/assets/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,iBAAiB;IACjC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAID,sGAAsG;AACtG,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB5H;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAInD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAEnD"}

package/dist/assets/binary.js

@@ -0,0 +1,57 @@
+import { resolve } from './paths.js';
+const cache = new Map();
+/** Loads and caches raw bytes for every path not already cached; a path already loaded is a no-op. */
+export async function loadBinary(paths, onProgress, options = {}) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (!doFetch)
+        throw new Error('fetch is unavailable; provide LoadBinaryOptions.fetch');
+    const pending = paths.filter((path) => !cache.has(path));
+    if (pending.length === 0) {
+        onProgress?.(1);
+        return;
+    }
+    let done = 0;
+    await Promise.all(pending.map(async (path) => {
+        const response = await doFetch(resolve(path));
+        if (!response.ok)
+            throw new Error(`failed to load binary asset "${path}": ${response.status}`);
+        cache.set(path, await response.arrayBuffer());
+        done++;
+        onProgress?.(done / pending.length);
+    }));
+}
+/** a loaded asset's raw bytes, by the same path it was loaded with */
+export function getBinary(path) {
+    const data = cache.get(path);
+    if (!data)
+        throw new Error(`binary asset "${path}" has not been loaded - pass it to loadBinary() first`);
+    return data;
+}
+/**
+ * true once `loadBinary` has resolved for this path and it has not since been `releaseBinary`d
+ *
+ * @example
+ * ```ts
+ * import { isBinaryLoaded } from '@datamoc/mw_games/assets';
+ *
+ * console.log(isBinaryLoaded('models/rock.vox')); // false until loadBinary resolves for it
+ * ```
+ */
+export function isBinaryLoaded(path) {
+    return cache.has(path);
+}
+/**
+ * Frees cached bytes; a path never loaded (or already released) is silently skipped.
+ *
+ * @example
+ * ```ts
+ * import { releaseBinary } from '@datamoc/mw_games/assets';
+ *
+ * releaseBinary(['models/rock.vox']); // frees the cached bytes once the model is placed
+ * ```
+ */
+export function releaseBinary(paths) {
+    for (const path of paths)
+        cache.delete(path);
+}
+//# sourceMappingURL=binary.js.map

package/dist/assets/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../../src/assets/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAsB,MAAM,YAAY,CAAC;AA4BzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;AAE7C,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAe,EAAE,UAA0B,EAAE,OAAO,GAAsB,EAAE;IAC5G,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAClD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAEvF,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO;IACR,CAAC;IAED,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/F,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9C,IAAI,EAAE,CAAC;QACP,UAAU,EAAE,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC,CAAC,CACF,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,IAAY;IACrC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,uDAAuD,CAAC,CAAC;IACzG,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC"}

package/dist/assets/index.d.ts

@@ -1,15 +1,20 @@
 /**
- * The `file://` story, in two halves.
+ * The `file://` story, split by how renderer-specific each piece is.
  *
  * `paths.ts` resolves an asset path against the compiled `data:` URI map (or the dev server)
- * and needs no renderer at all; `loader.ts` fetches and decodes through Pixi. This barrel
- * exposes both, so `import { load, resolve } from '@datamoc/mw_games/assets'` is unchanged -
- * but a game rendering through something else imports `@datamoc/mw_games/assets/paths`
- * instead and pays nothing for Pixi.
+ * and needs no renderer at all; `binary.ts` caches raw bytes the same renderer-free way, for
+ * anything (`three-d`'s VOX loader, most directly) that wants an `ArrayBuffer` rather than a
+ * decoded texture; `loader.ts` fetches and decodes textures through Pixi specifically. This
+ * barrel exposes all three, so `import { load, resolve } from '@datamoc/mw_games/assets'` is
+ * unchanged - but a game rendering through something else imports
+ * `@datamoc/mw_games/assets/paths` or `@datamoc/mw_games/assets/binary` instead and pays
+ * nothing for Pixi.
  */
 export { setBase, isCompiled, paths, has, resolve } from './paths.ts';
 export type { AssetProgress } from './paths.ts';
 export { load, texture, get, isLoaded, release } from './loader.ts';
+export { loadBinary, getBinary, isBinaryLoaded, releaseBinary } from './binary.ts';
+export type { LoadBinaryOptions } from './binary.ts';
 export { AssetStream } from './Streaming.ts';
 export type { AssetBundle, AssetStreamOptions } from './Streaming.ts';
 export { fetchWithByteProgress } from './ByteProgress.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/assets/index.js

@@ -1,14 +1,18 @@
 /**
- * The `file://` story, in two halves.
+ * The `file://` story, split by how renderer-specific each piece is.
  *
  * `paths.ts` resolves an asset path against the compiled `data:` URI map (or the dev server)
- * and needs no renderer at all; `loader.ts` fetches and decodes through Pixi. This barrel
- * exposes both, so `import { load, resolve } from '@datamoc/mw_games/assets'` is unchanged -
- * but a game rendering through something else imports `@datamoc/mw_games/assets/paths`
- * instead and pays nothing for Pixi.
+ * and needs no renderer at all; `binary.ts` caches raw bytes the same renderer-free way, for
+ * anything (`three-d`'s VOX loader, most directly) that wants an `ArrayBuffer` rather than a
+ * decoded texture; `loader.ts` fetches and decodes textures through Pixi specifically. This
+ * barrel exposes all three, so `import { load, resolve } from '@datamoc/mw_games/assets'` is
+ * unchanged - but a game rendering through something else imports
+ * `@datamoc/mw_games/assets/paths` or `@datamoc/mw_games/assets/binary` instead and pays
+ * nothing for Pixi.
  */
 export { setBase, isCompiled, paths, has, resolve } from './paths.js';
 export { load, texture, get, isLoaded, release } from './loader.js';
+export { loadBinary, getBinary, isBinaryLoaded, releaseBinary } from './binary.js';
 export { AssetStream } from './Streaming.js';
 export { fetchWithByteProgress } from './ByteProgress.js';
 //# sourceMappingURL=index.js.map

package/dist/assets/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGnF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/board/Army.d.ts

@@ -4,14 +4,89 @@ export interface ArmyState {
     currency: number;
     pool: UnitTemplate[];
 }
+/**
+ * Recruit/income economy layered on top of `Tactics`'s board: a currency total plus a pool of
+ * banked unit templates waiting to be recalled onto the map. See `recruit`/`bankUnit`/
+ * `recall`/`armyIncome`/`applyUpkeep` for the rest of the economy this state drives.
+ *
+ * @example
+ * ```ts
+ * import { startingArmy } from '@datamoc/mw_games/board';
+ *
+ * console.log(startingArmy(100)); // { currency: 100, pool: [] }
+ * ```
+ */
 export declare function startingArmy(currency: number): ArmyState;
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ *
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ * console.log(army.currency); // 70 - 100 minus the 30 cost
+ * ```
+ */
 export declare function recruit(army: ArmyState, board: TacticalState, unit: TacticalUnit, cost: number): boolean;
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, bankUnit, recall, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ * bankUnit(army, board, 'scout');
+ *
+ * recall(army, board, 'scout', 1, 1);
+ * console.log(board.units.some((unit) => unit.id === 'scout')); // true - fielded again, at its new position
+ * ```
+ */
 export declare function recall(army: ArmyState, board: TacticalState, unitId: string, x: number, y: number): boolean;
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, bankUnit, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ *
+ * bankUnit(army, board, 'scout');
+ * console.log(board.units.length, army.pool.length); // 0 1 - pulled off the map, into the pool
+ * ```
+ */
 export declare function bankUnit(army: ArmyState, board: TacticalState, unitId: string): boolean;
 export interface UpkeepRates {
     incomePerUnit: number;
     upkeepPerUnit: number;
 }
+/**
+ * @example
+ * ```ts
+ * import { startingTactics, addTacticalUnit, armyIncome } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * addTacticalUnit(board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 });
+ *
+ * console.log(armyIncome(board, 'blue', { incomePerUnit: 5, upkeepPerUnit: 2 })); // 3 - one unit, net of upkeep
+ * ```
+ */
 export declare function armyIncome(board: TacticalState, owner: string, rates: UpkeepRates): number;
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, startingTactics, addTacticalUnit, applyUpkeep } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * addTacticalUnit(board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 });
+ * const army = startingArmy(100);
+ *
+ * applyUpkeep(army, board, 'blue', { incomePerUnit: 5, upkeepPerUnit: 2 });
+ * console.log(army.currency); // 103 - this turn's net income applied
+ * ```
+ */
 export declare function applyUpkeep(army: ArmyState, board: TacticalState, owner: string, rates: UpkeepRates): number;
 //# sourceMappingURL=Army.d.ts.map

package/dist/board/Army.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Army.d.ts","sourceRoot":"","sources":["../../src/board/Army.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKhE,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,EAAE,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAExD;AAKD,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKxG;AAID,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAM3G;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOvF;AAED,MAAM,WAAW,WAAW;IAAG,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;CAAE;AAK9E,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAG1F;AAGD,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAG5G"}
+{"version":3,"file":"Army.d.ts","sourceRoot":"","sources":["../../src/board/Army.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKhE,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAExD;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKxG;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAM3G;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOvF;AAED,MAAM,WAAW,WAAW;IAAG,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;CAAE;AAK9E;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAG1F;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAG5G"}

package/dist/board/Army.js

@@ -1,10 +1,34 @@
 import { addTacticalUnit, canPlaceTacticalUnit } from './Tactics.js';
+/**
+ * Recruit/income economy layered on top of `Tactics`'s board: a currency total plus a pool of
+ * banked unit templates waiting to be recalled onto the map. See `recruit`/`bankUnit`/
+ * `recall`/`armyIncome`/`applyUpkeep` for the rest of the economy this state drives.
+ *
+ * @example
+ * ```ts
+ * import { startingArmy } from '@datamoc/mw_games/board';
+ *
+ * console.log(startingArmy(100)); // { currency: 100, pool: [] }
+ * ```
+ */
 export function startingArmy(currency) {
     return { currency, pool: [] };
 }
 //deducts cost and places a fresh unit, all-or-nothing like actors.Shop's buy/sell: touches
 //neither currency nor the board unless every check already passed - canPlaceTacticalUnit is
 //checked up front rather than letting addTacticalUnit's own throw escape a boolean contract
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ *
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ * console.log(army.currency); // 70 - 100 minus the 30 cost
+ * ```
+ */
 export function recruit(army, board, unit, cost) {
     if (army.currency < cost || !canPlaceTacticalUnit(board, unit.x, unit.y))
         return false;
@@ -14,6 +38,20 @@ export function recruit(army, board, unit, cost) {
 }
 //pulls a previously-fielded unit back onto the map instead of minting a fresh one - the
 //template stays in the pool until recalled, then leaves it the way stock leaves a shop's shelf
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, bankUnit, recall, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ * bankUnit(army, board, 'scout');
+ *
+ * recall(army, board, 'scout', 1, 1);
+ * console.log(board.units.some((unit) => unit.id === 'scout')); // true - fielded again, at its new position
+ * ```
+ */
 export function recall(army, board, unitId, x, y) {
     const index = army.pool.findIndex((template) => template.id === unitId);
     if (index === -1 || !canPlaceTacticalUnit(board, x, y))
@@ -24,6 +62,19 @@ export function recall(army, board, unitId, x, y) {
 }
 //moves a fielded unit into the recall pool instead of discarding it outright - the inverse of
 //recall, for retreating a unit off the map between engagements rather than losing it for good
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, recruit, bankUnit, startingTactics } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * const army = startingArmy(100);
+ * recruit(army, board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 }, 30);
+ *
+ * bankUnit(army, board, 'scout');
+ * console.log(board.units.length, army.pool.length); // 0 1 - pulled off the map, into the pool
+ * ```
+ */
 export function bankUnit(army, board, unitId) {
     const index = board.units.findIndex((unit) => unit.id === unitId);
     if (index === -1)
@@ -36,11 +87,35 @@ export function bankUnit(army, board, unitId) {
 //net currency delta for one turn's income minus upkeep, purely a function of how many units
 //an owner controls on the board - no formula beyond that belongs here, per this project's
 //policy against borrowing any specific game's numbers
+/**
+ * @example
+ * ```ts
+ * import { startingTactics, addTacticalUnit, armyIncome } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * addTacticalUnit(board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 });
+ *
+ * console.log(armyIncome(board, 'blue', { incomePerUnit: 5, upkeepPerUnit: 2 })); // 3 - one unit, net of upkeep
+ * ```
+ */
 export function armyIncome(board, owner, rates) {
     const controlled = board.units.filter((unit) => unit.owner === owner).length;
     return controlled * (rates.incomePerUnit - rates.upkeepPerUnit);
 }
 //applies one turn's income/upkeep tick to an army's currency and returns the new total
+/**
+ * @example
+ * ```ts
+ * import { startingArmy, startingTactics, addTacticalUnit, applyUpkeep } from '@datamoc/mw_games/board';
+ *
+ * const board = startingTactics(6, 6, 'square');
+ * addTacticalUnit(board, { id: 'scout', owner: 'blue', x: 0, y: 0, hp: 6, maxHp: 6, actions: 2 });
+ * const army = startingArmy(100);
+ *
+ * applyUpkeep(army, board, 'blue', { incomePerUnit: 5, upkeepPerUnit: 2 });
+ * console.log(army.currency); // 103 - this turn's net income applied
+ * ```
+ */
 export function applyUpkeep(army, board, owner, rates) {
     army.currency += armyIncome(board, owner, rates);
     return army.currency;

package/dist/board/Army.js.map

@@ -1 +1 @@
-{"version":3,"file":"Army.js","sourceRoot":"","sources":["../../src/board/Army.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAWrE,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED,2FAA2F;AAC3F,4FAA4F;AAC5F,4FAA4F;AAC5F,MAAM,UAAU,OAAO,CAAC,IAAe,EAAE,KAAoB,EAAE,IAAkB,EAAE,IAAY;IAC9F,IAAI,IAAI,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACvF,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;IACtB,OAAO,IAAI,CAAC;AACb,CAAC;AAED,wFAAwF;AACxF,+FAA+F;AAC/F,MAAM,UAAU,MAAM,CAAC,IAAe,EAAE,KAAoB,EAAE,MAAc,EAAE,CAAS,EAAE,CAAS;IACjG,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IACxE,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,eAAe,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACb,CAAC;AAED,8FAA8F;AAC9F,8FAA8F;AAC9F,MAAM,UAAU,QAAQ,CAAC,IAAe,EAAE,KAAoB,EAAE,MAAc;IAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IAClE,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACb,CAAC;AAID,4FAA4F;AAC5F,0FAA0F;AAC1F,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,KAAoB,EAAE,KAAa,EAAE,KAAkB;IACjF,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,MAAM,CAAC;IAC7E,OAAO,UAAU,GAAG,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;AACjE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,IAAe,EAAE,KAAoB,EAAE,KAAa,EAAE,KAAkB;IACnG,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,QAAQ,CAAC;AACtB,CAAC"}
+{"version":3,"file":"Army.js","sourceRoot":"","sources":["../../src/board/Army.ts"],"names":[],"mappings":"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"}