@datamoc/mw_games 0.3.1 → 0.4.1

package/dist/actors/Advancement.d.ts

@@ -11,6 +11,23 @@
  * Points are deliberately only a ledger here, not a spend rule: what a point buys is a
  * game's own design (a stat rank, a talent node), so spending stays game-side the way
  * `skillCheck` is a dice roll and nothing about who is rolling it.
+ *
+ * @example
+ * ```ts
+ * import { Advancement, type AdvancementTrack } from '@datamoc/mw_games/actors';
+ *
+ * const track: AdvancementTrack = {
+ *   tiers: [
+ *     { threshold: 5, kind: 'points', points: 2 },
+ *     { threshold: 10, kind: 'branch', options: [{ id: 'ranger' }, { id: 'mage' }] },
+ *   ],
+ * };
+ *
+ * const advancement = new Advancement(track);
+ * advancement.grant(6); // opens tier 0, granting 2 points
+ * advancement.grant(10); // opens tier 1, a branch to commit to
+ * advancement.choose(1, 'ranger', 10);
+ * ```
  */
 export type AdvancementTierKind = 'points' | 'branch' | 'capstone';
 export interface AdvancementOption {

package/dist/actors/Advancement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Advancement.d.ts","sourceRoot":"","sources":["../../src/actors/Advancement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAElB,IAAI,EAAE,mBAAmB,CAAC;IAE1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sFAAsF;IACtF,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAClC;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,KAAK,CAAmB;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAA6B;IAE5C,YAAY,KAAK,EAAE,gBAAgB,EAElC;IAED,4BAA4B;IAC5B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW3B;IAED,+EAA+E;IAC/E,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAI7B;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAU/D;IAED,yEAAyE;IACzE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEvC;IAED,MAAM,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KAAE,CAE/E;IAED,mHAAmH;IACnH,MAAM,CAAC,QAAQ,CACd,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KAAE,GAC1E,WAAW,CAMb;CACD"}
+{"version":3,"file":"Advancement.d.ts","sourceRoot":"","sources":["../../src/actors/Advancement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAElB,IAAI,EAAE,mBAAmB,CAAC;IAE1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sFAAsF;IACtF,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAClC;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,KAAK,CAAmB;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAA6B;IAE5C,YAAY,KAAK,EAAE,gBAAgB,EAElC;IAED,4BAA4B;IAC5B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW3B;IAED,+EAA+E;IAC/E,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAI7B;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAU/D;IAED,yEAAyE;IACzE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEvC;IAED,MAAM,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KAAE,CAE/E;IAED,mHAAmH;IACnH,MAAM,CAAC,QAAQ,CACd,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KAAE,GAC1E,WAAW,CAMb;CACD"}

package/dist/actors/Advancement.js

@@ -11,6 +11,23 @@
  * Points are deliberately only a ledger here, not a spend rule: what a point buys is a
  * game's own design (a stat rank, a talent node), so spending stays game-side the way
  * `skillCheck` is a dice roll and nothing about who is rolling it.
+ *
+ * @example
+ * ```ts
+ * import { Advancement, type AdvancementTrack } from '@datamoc/mw_games/actors';
+ *
+ * const track: AdvancementTrack = {
+ *   tiers: [
+ *     { threshold: 5, kind: 'points', points: 2 },
+ *     { threshold: 10, kind: 'branch', options: [{ id: 'ranger' }, { id: 'mage' }] },
+ *   ],
+ * };
+ *
+ * const advancement = new Advancement(track);
+ * advancement.grant(6); // opens tier 0, granting 2 points
+ * advancement.grant(10); // opens tier 1, a branch to commit to
+ * advancement.choose(1, 'ranger', 10);
+ * ```
  */
 export class Advancement {
     constructor(track) {

package/dist/actors/Advancement.js.map

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

package/dist/actors/Affix.d.ts

@@ -9,11 +9,44 @@ import type { InventoryItem } from './Inventory.ts';
  * answers to (`strike`, `defend`, or a `passive` that is always on), how likely it is
  * relative to its table, and whether it is a curse - and the game interprets the id
  * itself when that trigger fires, the same way `Move.effects` is data `mwg` never reads.
+ *
+ * @example
+ * ```ts
+ * import { rollAffix, applyAffix, affixOf, removeAffix, copyAffix, matchesContext, type AffixTable } from '@datamoc/mw_games/actors';
+ *
+ * const table: AffixTable = { entries: [{ id: 'flaming', trigger: 'strike', weight: 1, kinds: ['melee'] }] };
+ * const sword = { id: 'sword', quantity: 1 };
+ * const betterSword = { id: 'sword', quantity: 1, instanceId: 'b' };
+ *
+ * const affix = rollAffix(table);
+ * if (affix) applyAffix(sword, affix);
+ * console.log(affixOf(sword)); // 'flaming'
+ *
+ * if (affix && matchesContext(affix, { trigger: 'strike', kind: 'melee' })) {
+ *   console.log('flaming affix fires on this melee hit');
+ * }
+ *
+ * copyAffix(sword, betterSword); // carries the enchantment onto an upgraded item
+ * removeAffix(sword);
+ * ```
  */
 export type AffixTrigger = 'strike' | 'defend' | 'passive';
+/** the kind of action a `strike`/`defend` trigger fired from - melee, thrown, a bow, an ability */
+export type AttackKind = 'melee' | 'thrown' | 'bow' | 'ability' | string;
+/** what actually happened, for `matchesContext` to check an affix against */
+export interface AffixContext {
+    trigger: AffixTrigger;
+    kind?: AttackKind;
+}
 export interface AffixDef {
     id: string;
     trigger: AffixTrigger;
+    /**
+     * restricts this affix to specific attack kinds within its trigger (a "bow only" affix on
+     * a `strike` trigger); omitted, the affix fires for any kind, the same as before this
+     * existed
+     */
+    kinds?: readonly AttackKind[];
     /** relative likelihood within its own table; 0 never rolls */
     weight: number;
     /** a curse locks the item (see `EquipmentSlots`' lock option) once identified */
@@ -41,4 +74,17 @@ export declare function affixOf(item: InventoryItem): string | undefined;
 export declare function applyAffix(item: InventoryItem, affix: AffixDef): void;
 /** removes an item's affix (and its curse mark, if the affix was a curse) */
 export declare function removeAffix(item: InventoryItem): void;
+/**
+ * Copies `from`'s affix (and curse mark) onto `to`, replacing whatever `to` already had -
+ * "transfer" an enchantment or rune between item instances. Clears `to`'s affix when `from`
+ * carries none. A true transfer (move rather than copy) is this plus `removeAffix(from)`,
+ * left to the caller rather than a second near-identical function.
+ */
+export declare function copyAffix(from: InventoryItem, to: InventoryItem): void;
+/**
+ * Whether `affix` should fire for `context`: the trigger must match, and when the affix
+ * restricts itself to specific attack `kinds`, `context.kind` must be one of them. An affix
+ * with no `kinds` fires for any attack kind, unchanged from before this existed.
+ */
+export declare function matchesContext(affix: AffixDef, context: AffixContext): boolean;
 //# sourceMappingURL=Affix.d.ts.map

package/dist/actors/Affix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Affix.d.ts","sourceRoot":"","sources":["../../src/actors/Affix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IAEX,OAAO,EAAE,YAAY,CAAC;IAEtB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAK5D;AAED,yFAAyF;AACzF,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAGrE;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAGrD"}
+{"version":3,"file":"Affix.d.ts","sourceRoot":"","sources":["../../src/actors/Affix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzE,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IAEX,OAAO,EAAE,YAAY,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAE9B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAK5D;AAED,yFAAyF;AACzF,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAOrE;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAGrD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAOtE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAI9E"}

package/dist/actors/Affix.js

@@ -10,7 +10,7 @@ export function rollAffix(table) {
     if (live.length === 0)
         return null;
     const index = Random.weighted(live.map((entry) => entry.weight));
-    return index === -1 ? null : live[index];
+    return index === null ? null : live[index];
 }
 /** the affix an item carries, if any - stored on the item next to its upgrade `level` */
 export function affixOf(item) {
@@ -22,9 +22,14 @@ export function affixOf(item) {
  * wiring them separately.
  */
 export function applyAffix(item, affix) {
+    const hadAffix = item.affix !== undefined;
     item.affix = affix.id;
+    // The curse bit belongs to the affix currently installed.  Replacing a cursed
+    // affix with a benign one must not leave the item permanently cursed.
     if (affix.curse)
         item.cursed = true;
+    else if (hadAffix)
+        item.cursed = false;
 }
 /** removes an item's affix (and its curse mark, if the affix was a curse) */
 export function removeAffix(item) {
@@ -32,4 +37,30 @@ export function removeAffix(item) {
         item.cursed = false;
     delete item.affix;
 }
+/**
+ * Copies `from`'s affix (and curse mark) onto `to`, replacing whatever `to` already had -
+ * "transfer" an enchantment or rune between item instances. Clears `to`'s affix when `from`
+ * carries none. A true transfer (move rather than copy) is this plus `removeAffix(from)`,
+ * left to the caller rather than a second near-identical function.
+ */
+export function copyAffix(from, to) {
+    if (from.affix === undefined) {
+        removeAffix(to);
+        return;
+    }
+    to.affix = from.affix;
+    to.cursed = from.cursed ?? false;
+}
+/**
+ * Whether `affix` should fire for `context`: the trigger must match, and when the affix
+ * restricts itself to specific attack `kinds`, `context.kind` must be one of them. An affix
+ * with no `kinds` fires for any attack kind, unchanged from before this existed.
+ */
+export function matchesContext(affix, context) {
+    if (affix.trigger !== context.trigger)
+        return false;
+    if (affix.kinds && (context.kind === undefined || !affix.kinds.includes(context.kind)))
+        return false;
+    return true;
+}
 //# sourceMappingURL=Affix.js.map

package/dist/actors/Affix.js.map

@@ -1 +1 @@
-{"version":3,"file":"Affix.js","sourceRoot":"","sources":["../../src/actors/Affix.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAmC5C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,OAAO,CAAC,IAAmB;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,KAAe;IAC9D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC;IACtB,IAAI,KAAK,CAAC,KAAK;QAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;AACrC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC9C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC"}
+{"version":3,"file":"Affix.js","sourceRoot":"","sources":["../../src/actors/Affix.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAuE5C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,OAAO,CAAC,IAAmB;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,KAAe;IAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IAC1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC;IACtB,8EAA8E;IAC9E,sEAAsE;IACtE,IAAI,KAAK,CAAC,KAAK;QAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;SAC/B,IAAI,QAAQ;QAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;AACxC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC9C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB,EAAE,EAAiB;IAC/D,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,WAAW,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO;IACR,CAAC;IACD,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACtB,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,OAAqB;IACpE,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrG,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/actors/Appearances.d.ts

@@ -17,6 +17,18 @@ export interface AppearanceTable {
 /**
  * Deals each kind a distinct label from a shuffled copy of the pool - pure, so a game
  * that wants the shuffle scoped (one seed per run, say) wraps it in `Random.withSeed`.
+ *
+ * @example
+ * ```ts
+ * import { assignAppearances, Appearances } from '@datamoc/mw_games/actors';
+ *
+ * const potions = assignAppearances({ kinds: ['healing', 'poison'], labels: ['red', 'blue'] });
+ * console.log(potions.get('healing')); // 'red' or 'blue', fixed for this shuffle
+ *
+ * // Appearances wraps this per category, drawing lazily on first ask and caching for the run
+ * const appearances = new Appearances({ potions: { kinds: ['healing', 'poison'], labels: ['red', 'blue'] } });
+ * const label = appearances.appearanceOf('potions', 'healing');
+ * ```
  */
 export declare function assignAppearances(table: AppearanceTable): Map<string, string>;
 export declare class Appearances {

package/dist/actors/Appearances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Appearances.d.ts","sourceRoot":"","sources":["../../src/actors/Appearances.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,eAAe;IAC/B,uEAAuE;IACvE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzB,gFAAgF;IAChF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc7E;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,QAAQ,CAA0C;IAE1D,YAAY,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAElD;IAED,qFAAqF;IACrF,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAWnD;IAED,MAAM,IAAI;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,CAErD;IAED,yHAAyH;IACzH,MAAM,CAAC,QAAQ,CACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,GAChD,WAAW,CAIb;CACD"}
+{"version":3,"file":"Appearances.d.ts","sourceRoot":"","sources":["../../src/actors/Appearances.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,eAAe;IAC/B,uEAAuE;IACvE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzB,gFAAgF;IAChF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc7E;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,QAAQ,CAA0C;IAE1D,YAAY,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAElD;IAED,qFAAqF;IACrF,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAWnD;IAED,MAAM,IAAI;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,CAErD;IAED,yHAAyH;IACzH,MAAM,CAAC,QAAQ,CACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,GAChD,WAAW,CAIb;CACD"}

package/dist/actors/Appearances.js

@@ -2,6 +2,18 @@ import * as Random from '../core/Random.js';
 /**
  * Deals each kind a distinct label from a shuffled copy of the pool - pure, so a game
  * that wants the shuffle scoped (one seed per run, say) wraps it in `Random.withSeed`.
+ *
+ * @example
+ * ```ts
+ * import { assignAppearances, Appearances } from '@datamoc/mw_games/actors';
+ *
+ * const potions = assignAppearances({ kinds: ['healing', 'poison'], labels: ['red', 'blue'] });
+ * console.log(potions.get('healing')); // 'red' or 'blue', fixed for this shuffle
+ *
+ * // Appearances wraps this per category, drawing lazily on first ask and caching for the run
+ * const appearances = new Appearances({ potions: { kinds: ['healing', 'poison'], labels: ['red', 'blue'] } });
+ * const label = appearances.appearanceOf('potions', 'healing');
+ * ```
  */
 export function assignAppearances(table) {
     if (table.labels.length < table.kinds.length) {

package/dist/actors/Appearances.js.map

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

package/dist/actors/Aura.d.ts

@@ -21,6 +21,22 @@ export interface AuraParticipant {
  * each carrier last time: a unit that just became adjacent gets the carrier's modifiers added,
  * one that just left loses exactly those modifiers, and one that stays adjacent is left alone
  * rather than having its modifiers reapplied on every tick.
+ *
+ * @example
+ * ```ts
+ * import { AuraField, StatBlock, type AuraParticipant } from '@datamoc/mw_games/actors';
+ *
+ * const field = new AuraField();
+ * const captain: AuraParticipant = {
+ *   stats: new StatBlock({ base: {} }),
+ *   aura: { name: 'rally', modifiers: [{ stat: 'attack', op: 'add', value: 2 }] },
+ * };
+ * const soldier: AuraParticipant = { stats: new StatBlock({ base: { attack: 5 } }) };
+ *
+ * // call every time positions change, with whatever "adjacent" means on this grid
+ * field.update([captain, soldier], (a, b) => a === captain && b === soldier);
+ * console.log(soldier.stats.get('attack')); // 7, while adjacent
+ * ```
  */
 export declare class AuraField {
     private affected;

package/dist/actors/Aura.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Aura.d.ts","sourceRoot":"","sources":["../../src/actors/Aura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1D,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;CAC/C;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS;IAGrB,OAAO,CAAC,QAAQ,CAA4D;IAE5E,MAAM,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,KAAK,OAAO,GAAG,IAAI,CA6CtH;CACD"}
+{"version":3,"file":"Aura.d.ts","sourceRoot":"","sources":["../../src/actors/Aura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1D,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;CAC/C;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,SAAS;IAGrB,OAAO,CAAC,QAAQ,CAA4D;IAE5E,MAAM,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,KAAK,OAAO,GAAG,IAAI,CA6CtH;CACD"}

package/dist/actors/Aura.js

@@ -11,6 +11,22 @@ import { StatBlock } from './StatBlock.js';
  * each carrier last time: a unit that just became adjacent gets the carrier's modifiers added,
  * one that just left loses exactly those modifiers, and one that stays adjacent is left alone
  * rather than having its modifiers reapplied on every tick.
+ *
+ * @example
+ * ```ts
+ * import { AuraField, StatBlock, type AuraParticipant } from '@datamoc/mw_games/actors';
+ *
+ * const field = new AuraField();
+ * const captain: AuraParticipant = {
+ *   stats: new StatBlock({ base: {} }),
+ *   aura: { name: 'rally', modifiers: [{ stat: 'attack', op: 'add', value: 2 }] },
+ * };
+ * const soldier: AuraParticipant = { stats: new StatBlock({ base: { attack: 5 } }) };
+ *
+ * // call every time positions change, with whatever "adjacent" means on this grid
+ * field.update([captain, soldier], (a, b) => a === captain && b === soldier);
+ * console.log(soldier.stats.get('attack')); // 7, while adjacent
+ * ```
  */
 export class AuraField {
     constructor() {

package/dist/actors/Aura.js.map

@@ -1 +1 @@
-{"version":3,"file":"Aura.js","sourceRoot":"","sources":["../../src/actors/Aura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAiB,MAAM,gBAAgB,CAAC;AAc1D;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,SAAS;IAAtB;QACC,oFAAoF;QACpF,0FAA0F;QAClF,aAAQ,GAAG,IAAI,GAAG,EAAiD,CAAC;IAgD7E,CAAC;IA9CA,MAAM,CAAC,YAAwC,EAAE,UAA+D;QAC/G,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAA4C,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAkB,QAAQ,CAAC,CAAC;QAEtD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACnD,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACxB,iBAAiB,GAAG,IAAI,GAAG,EAAE,CAAC;gBAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;YAC/C,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;gBAClC,IAAI,KAAK,KAAK,OAAO;oBAAE,SAAS;gBAChC,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAE5C,IAAI,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;oBACzB,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;oBACtD,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS;wBAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;oBAC3G,iBAAiB,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;gBACzC,CAAC;qBAAM,IAAI,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC;oBAChC,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;oBACxC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACjC,CAAC;YACF,CAAC;YAED,gFAAgF;YAChF,wEAAwE;YACxE,8EAA8E;YAC9E,4BAA4B;YAC5B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,EAAE,CAAC;gBACtD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;oBAAE,SAAS;gBAChC,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;gBACxC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;QACF,CAAC;QAED,qFAAqF;QACrF,oFAAoF;QACpF,KAAK,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/D,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YACtC,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,iBAAiB;gBAAE,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YACzF,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"Aura.js","sourceRoot":"","sources":["../../src/actors/Aura.ts"],"names":[],"mappings":"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"}

package/dist/actors/Barrier.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A shield/barrier pool absorbed before HP, decaying on its own each tick unlike a plain
+ * `StatBlock` stat, which only ever changes when something explicitly touches it. Several
+ * layers can be held at once - a fresh cast over an older one, a ward stacked on a shield -
+ * absorption always drains the most recently added layer first, so a ward cast on top of a
+ * standing shield breaks before the shield underneath it does, matching how a layered proc
+ * family (barrier-then-shield, shield-then-barrier) is meant to read regardless of order cast.
+ *
+ * @example
+ * ```ts
+ * import { Barrier } from '@datamoc/mw_games/actors';
+ *
+ * const barrier = new Barrier();
+ * barrier.add(20); // a shield spell
+ * barrier.add(10, 2); // a ward on top, decaying 2 per turn on its own
+ *
+ * const absorbed = barrier.absorb(15); // drains the ward first, then spills into the shield
+ * barrier.advance(1); // one turn of decay
+ * console.log(barrier.total);
+ * ```
+ */
+export interface BarrierLayer {
+    amount: number;
+    /** how much this layer's `amount` drops per turn advanced; 0 (the default) never decays on its own */
+    decayPerTick?: number;
+}
+export declare class Barrier {
+    private layers;
+    /** adds a new outermost layer; a non-positive amount is a no-op rather than an empty layer */
+    add(amount: number, decayPerTick?: number): void;
+    /** total absorption currently held, across every layer */
+    get total(): number;
+    /** how many independent layers are currently held */
+    get layerCount(): number;
+    /**
+     * Absorbs up to `amount` of incoming damage, draining the outermost layer first and
+     * spilling into the next one once a layer empties.
+     *
+     * @returns the amount actually absorbed - never more than `amount`, never more than
+     * `total` was before the call - so the caller applies `amount - absorbed` to HP
+     */
+    absorb(amount: number): number;
+    /**
+     * Decays every layer by its own `decayPerTick`, removing any that reach zero or below.
+     *
+     * Named `advance(turns)` like every other turn-scale ticker here (`TurnClock`, `Charges`,
+     * `Field`, `AbilityCycle`) rather than `decay`, so one word means one thing across the
+     * framework: `advance` takes whole turns, `update` takes `dt` seconds.
+     */
+    advance(turns?: number): void;
+    /** drops every layer at once - a dispel, a fresh encounter starting clean */
+    clear(): void;
+    toJSON(): {
+        layers: BarrierLayer[];
+    };
+    static fromJSON(data: {
+        layers: BarrierLayer[];
+    }): Barrier;
+}
+//# sourceMappingURL=Barrier.d.ts.map

package/dist/actors/Barrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Barrier.d.ts","sourceRoot":"","sources":["../../src/actors/Barrier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IAEf,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,OAAO;IACnB,OAAO,CAAC,MAAM,CAAsB;IAEpC,8FAA8F;IAC9F,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI,CAG1C;IAED,0DAA0D;IAC1D,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,qDAAqD;IACrD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY7B;IAED;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,SAAI,GAAG,IAAI,CAOvB;IAED,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAEZ;IAED,MAAM,IAAI;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAEnC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,GAAG,OAAO,CAIzD;CACD"}

package/dist/actors/Barrier.js

@@ -0,0 +1,70 @@
+export class Barrier {
+    constructor() {
+        this.layers = [];
+    }
+    /** adds a new outermost layer; a non-positive amount is a no-op rather than an empty layer */
+    add(amount, decayPerTick = 0) {
+        if (amount <= 0)
+            return;
+        this.layers.push({ amount, decayPerTick });
+    }
+    /** total absorption currently held, across every layer */
+    get total() {
+        return this.layers.reduce((sum, layer) => sum + layer.amount, 0);
+    }
+    /** how many independent layers are currently held */
+    get layerCount() {
+        return this.layers.length;
+    }
+    /**
+     * Absorbs up to `amount` of incoming damage, draining the outermost layer first and
+     * spilling into the next one once a layer empties.
+     *
+     * @returns the amount actually absorbed - never more than `amount`, never more than
+     * `total` was before the call - so the caller applies `amount - absorbed` to HP
+     */
+    absorb(amount) {
+        let remaining = amount;
+        let absorbed = 0;
+        while (remaining > 0 && this.layers.length > 0) {
+            const layer = this.layers[this.layers.length - 1];
+            const take = Math.min(layer.amount, remaining);
+            layer.amount -= take;
+            remaining -= take;
+            absorbed += take;
+            if (layer.amount <= 0)
+                this.layers.pop();
+        }
+        return absorbed;
+    }
+    /**
+     * Decays every layer by its own `decayPerTick`, removing any that reach zero or below.
+     *
+     * Named `advance(turns)` like every other turn-scale ticker here (`TurnClock`, `Charges`,
+     * `Field`, `AbilityCycle`) rather than `decay`, so one word means one thing across the
+     * framework: `advance` takes whole turns, `update` takes `dt` seconds.
+     */
+    advance(turns = 1) {
+        for (let i = this.layers.length - 1; i >= 0; i--) {
+            const layer = this.layers[i];
+            if (!layer.decayPerTick)
+                continue;
+            layer.amount -= layer.decayPerTick * turns;
+            if (layer.amount <= 0)
+                this.layers.splice(i, 1);
+        }
+    }
+    /** drops every layer at once - a dispel, a fresh encounter starting clean */
+    clear() {
+        this.layers = [];
+    }
+    toJSON() {
+        return { layers: this.layers.map((layer) => ({ ...layer })) };
+    }
+    static fromJSON(data) {
+        const barrier = new Barrier();
+        barrier.layers = data.layers.map((layer) => ({ ...layer }));
+        return barrier;
+    }
+}
+//# sourceMappingURL=Barrier.js.map

package/dist/actors/Barrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Barrier.js","sourceRoot":"","sources":["../../src/actors/Barrier.ts"],"names":[],"mappings":"AA4BA,MAAM,OAAO,OAAO;IAApB;QACS,WAAM,GAAmB,EAAE,CAAC;IAqErC,CAAC;IAnEA,8FAA8F;IAC9F,GAAG,CAAC,MAAc,EAAE,YAAY,GAAG,CAAC;QACnC,IAAI,MAAM,IAAI,CAAC;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,0DAA0D;IAC1D,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,qDAAqD;IACrD,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAc;QACpB,IAAI,SAAS,GAAG,MAAM,CAAC;QACvB,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,OAAO,SAAS,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC/C,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC;YACrB,SAAS,IAAI,IAAI,CAAC;YAClB,QAAQ,IAAI,IAAI,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QAC1C,CAAC;QACD,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,GAAG,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,YAAY;gBAAE,SAAS;YAClC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;YAC3C,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;IAED,6EAA6E;IAC7E,KAAK;QACJ,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IAClB,CAAC;IAED,MAAM;QACL,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAgC;QAC/C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}

package/dist/actors/Charges.d.ts

@@ -6,6 +6,19 @@
  * carries its own regeneration progress instead of leaning on `TurnClock` for it - a charge
  * either has or does not have enough banked turns to regenerate, which is exactly the kind
  * of running total a class holds more naturally than a callback would.
+ *
+ * @example
+ * ```ts
+ * import { Charges } from '@datamoc/mw_games/actors';
+ *
+ * const wand = new Charges({ max: 3, regenRate: 10 }); // one charge every 10 turns
+ * wand.spend(1);
+ *
+ * wand.advance(10); // 10 turns pass; one charge regenerates
+ * console.log(wand.current); // back to max
+ *
+ * wand.refund(1); // a kill or crit grants a charge directly, outside the normal regen path
+ * ```
  */
 export interface ChargesOptions {
     /** the most this can ever hold */
@@ -25,7 +38,29 @@ export declare class Charges {
     canAfford(cost: number): boolean;
     /** @returns false, spending nothing, if `cost` is not affordable right now */
     spend(cost: number): boolean;
+    /**
+     * Restores charges directly, outside the normal regen path - a killing blow or a crit
+     * refunding one on the spot. Capped at `max`.
+     *
+     * @returns how many were actually added, which is less than `amount` once `max` is hit
+     */
+    refund(amount?: number): number;
     /** banks `turns` of regeneration time, converting whole `regenRate`-sized chunks into charges */
     advance(turns?: number): void;
+    /**
+     * Charges held, and progress banked towards the next one.
+     *
+     * The banked progress matters as much as the count: without it, saving and loading part
+     * way to a recharge would silently reset that wait, so a player could refresh a wand a
+     * little faster by reloading. `max` and `regenRate` are definitions, supplied fresh.
+     */
+    toJSON(): {
+        current: number;
+        progress: number;
+    };
+    static fromJSON(options: ChargesOptions, data: {
+        current: number;
+        progress: number;
+    }): Charges;
 }
 //# sourceMappingURL=Charges.d.ts.map

package/dist/actors/Charges.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Charges.d.ts","sourceRoot":"","sources":["../../src/actors/Charges.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IAEZ,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,OAAO;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAK;IAErB,YAAY,OAAO,EAAE,cAAc,EAIlC;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/B;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3B;IAED,iGAAiG;IACjG,OAAO,CAAC,KAAK,SAAI,GAAG,IAAI,CAWvB;CACD"}
+{"version":3,"file":"Charges.d.ts","sourceRoot":"","sources":["../../src/actors/Charges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc;IAC9B,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IAEZ,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,OAAO;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAK;IAErB,YAAY,OAAO,EAAE,cAAc,EAIlC;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/B;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3B;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,SAAI,GAAG,MAAM,CAIzB;IAED,iGAAiG;IACjG,OAAO,CAAC,KAAK,SAAI,GAAG,IAAI,CAWvB;IAED;;;;;;OAMG;IACH,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAE9C;IAED,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAI7F;CACD"}

package/dist/actors/Charges.js

@@ -18,6 +18,17 @@ export class Charges {
         this.value -= cost;
         return true;
     }
+    /**
+     * Restores charges directly, outside the normal regen path - a killing blow or a crit
+     * refunding one on the spot. Capped at `max`.
+     *
+     * @returns how many were actually added, which is less than `amount` once `max` is hit
+     */
+    refund(amount = 1) {
+        const added = Math.min(amount, this.max - this.value);
+        this.value += added;
+        return added;
+    }
     /** banks `turns` of regeneration time, converting whole `regenRate`-sized chunks into charges */
     advance(turns = 1) {
         if (this.value >= this.max)
@@ -31,5 +42,20 @@ export class Charges {
         if (this.value >= this.max)
             this.progress = 0;
     }
+    /**
+     * Charges held, and progress banked towards the next one.
+     *
+     * The banked progress matters as much as the count: without it, saving and loading part
+     * way to a recharge would silently reset that wait, so a player could refresh a wand a
+     * little faster by reloading. `max` and `regenRate` are definitions, supplied fresh.
+     */
+    toJSON() {
+        return { current: this.value, progress: this.progress };
+    }
+    static fromJSON(options, data) {
+        const charges = new Charges({ ...options, current: data.current });
+        charges.progress = data.progress;
+        return charges;
+    }
 }
 //# sourceMappingURL=Charges.js.map

package/dist/actors/Charges.js.map

@@ -1 +1 @@
-{"version":3,"file":"Charges.js","sourceRoot":"","sources":["../../src/actors/Charges.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,OAAO;IAMnB,YAAY,OAAuB;QAF3B,aAAQ,GAAG,CAAC,CAAC;QAGpB,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,SAAS,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IAC3B,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAY;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;QACnB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iGAAiG;IACjG,OAAO,CAAC,KAAK,GAAG,CAAC;QAChB,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO;QAEnC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QACvB,OAAO,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;QAED,qFAAqF;QACrF,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC/C,CAAC;CACD"}
+{"version":3,"file":"Charges.js","sourceRoot":"","sources":["../../src/actors/Charges.ts"],"names":[],"mappings":"AAiCA,MAAM,OAAO,OAAO;IAMnB,YAAY,OAAuB;QAF3B,aAAQ,GAAG,CAAC,CAAC;QAGpB,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,SAAS,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IAC3B,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAY;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;QACnB,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,GAAG,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;QACpB,OAAO,KAAK,CAAC;IACd,CAAC;IAED,iGAAiG;IACjG,OAAO,CAAC,KAAK,GAAG,CAAC;QAChB,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO;QAEnC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QACvB,OAAO,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;QAED,qFAAqF;QACrF,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,MAAM;QACL,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,OAAuB,EAAE,IAA2C;QACnF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACjC,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}