@datamoc/mw_games 0.3.1 → 0.4.1

package/dist/actors/Equipment.d.ts

@@ -17,6 +17,24 @@ export interface EquipmentOptions<Slot extends string, Item extends EquippableIt
  * Whatever an item's `modifiers` are, equipping it applies them to the given `StatBlock` and
  * unequipping removes exactly those - tagged by the item itself as their `source`, so two
  * rings of the same kind never remove each other's bonus by mistake.
+ *
+ * @example
+ * ```ts
+ * import { EquipmentSlots, StatBlock } from '@datamoc/mw_games/actors';
+ *
+ * const stats = new StatBlock({ base: { attack: 3 } });
+ * const equipment = new EquipmentSlots<'weapon' | 'armor', { modifiers?: import('@datamoc/mw_games/actors').Modifier[] }>(
+ *   ['weapon', 'armor'],
+ *   stats
+ * );
+ *
+ * const sword = { modifiers: [{ stat: 'attack', op: 'add' as const, value: 5 }] };
+ * equipment.equip('weapon', sword);
+ * console.log(stats.get('attack')); // 8
+ *
+ * equipment.unequip('weapon');
+ * console.log(stats.get('attack')); // 3
+ * ```
  */
 export declare class EquipmentSlots<Slot extends string, Item extends EquippableItem> {
     private readonly names;
@@ -32,9 +50,39 @@ export declare class EquipmentSlots<Slot extends string, Item extends Equippable
      * changing anything when the slot is locked
      */
     equip(slot: Slot, item: Item): Item | undefined;
+    /** puts an item on and applies its modifiers, with no lock check - the shared half of `equip` and `fromJSON` */
+    private wear;
     /** @returns the removed item, or undefined for an empty slot - or a locked one, which stays put */
     unequip(slot: Slot): Item | undefined;
     get slots(): readonly Slot[];
     private assertSlot;
+    /**
+     * Which slot holds which item, by whatever id `identify` gives each one.
+     *
+     * An item is a game's own object here (`Item` is a type parameter, and `EquippableItem`
+     * requires only `modifiers`), so this framework has no idea what identifies one. The
+     * caller says, usually with the same id its item table is keyed by.
+     */
+    toJSON(identify: (item: Item) => string): SavedEquipment<Slot>;
+    /**
+     * Rebuilds the slots and re-equips everything, so each item's modifiers land back on the
+     * `StatBlock` exactly as they were.
+     *
+     * That reapplication is the point: `StatBlock.toJSON` deliberately saves no modifiers,
+     * precisely because whatever applied them puts them back on load. A locked item is
+     * restored rather than refused - a cursed ring the character was already wearing is still
+     * on their finger after a reload, and `equip`'s refusal is about *putting one on*, which
+     * is not what this is doing.
+     */
+    static fromJSON<Slot extends string, Item extends EquippableItem>(defs: {
+        slots: readonly Slot[];
+        /** turns a saved id back into the game's own item object */
+        resolve: (id: string) => Item;
+        stats?: StatBlock | null;
+        locked?: (slot: Slot, item: Item) => boolean;
+    }, data: SavedEquipment<Slot>): EquipmentSlots<Slot, Item>;
+}
+export interface SavedEquipment<Slot extends string> {
+    worn: [Slot, string][];
 }
 //# sourceMappingURL=Equipment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Equipment.d.ts","sourceRoot":"","sources":["../../src/actors/Equipment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,SAAS,cAAc;IACjF;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,SAAS,cAAc;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,YAAY,CAAsC;IAE1D,YAAY,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,GAAE,SAAS,GAAG,IAAW,EAAE,OAAO,GAAE,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAM,EAI7G;IAED,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAEhC;IAED,4JAA4J;IAC5J,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAG5B;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAU9C;IAED,mGAAmG;IACnG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAQpC;IAED,IAAI,KAAK,IAAI,SAAS,IAAI,EAAE,CAE3B;IAED,OAAO,CAAC,UAAU;CAGlB"}
+{"version":3,"file":"Equipment.d.ts","sourceRoot":"","sources":["../../src/actors/Equipment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,SAAS,cAAc;IACjF;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,SAAS,cAAc;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,YAAY,CAAsC;IAE1D,YAAY,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,GAAE,SAAS,GAAG,IAAW,EAAE,OAAO,GAAE,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAM,EAI7G;IAED,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAEhC;IAED,4JAA4J;IAC5J,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAG5B;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAO9C;IAED,gHAAgH;IAChH,OAAO,CAAC,IAAI;IAOZ,mGAAmG;IACnG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAQpC;IAED,IAAI,KAAK,IAAI,SAAS,IAAI,EAAE,CAE3B;IAED,OAAO,CAAC,UAAU;IAIlB;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAE7D;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,SAAS,cAAc,EAC/D,IAAI,EAAE;QACL,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;QACvB,4DAA4D;QAC5D,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;QAC9B,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;KAC7C,EACD,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAQ5B;CACD;AAED,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,MAAM;IAClD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;CACvB"}

package/dist/actors/Equipment.js

@@ -4,6 +4,24 @@
  * Whatever an item's `modifiers` are, equipping it applies them to the given `StatBlock` and
  * unequipping removes exactly those - tagged by the item itself as their `source`, so two
  * rings of the same kind never remove each other's bonus by mistake.
+ *
+ * @example
+ * ```ts
+ * import { EquipmentSlots, StatBlock } from '@datamoc/mw_games/actors';
+ *
+ * const stats = new StatBlock({ base: { attack: 3 } });
+ * const equipment = new EquipmentSlots<'weapon' | 'armor', { modifiers?: import('@datamoc/mw_games/actors').Modifier[] }>(
+ *   ['weapon', 'armor'],
+ *   stats
+ * );
+ *
+ * const sword = { modifiers: [{ stat: 'attack', op: 'add' as const, value: 5 }] };
+ * equipment.equip('weapon', sword);
+ * console.log(stats.get('attack')); // 8
+ *
+ * equipment.unequip('weapon');
+ * console.log(stats.get('attack')); // 3
+ * ```
  */
 export class EquipmentSlots {
     constructor(slots, stats = null, options = {}) {
@@ -29,11 +47,15 @@ export class EquipmentSlots {
         if (this.isLocked(slot))
             return undefined;
         const previous = this.unequip(slot);
+        this.wear(slot, item);
+        return previous;
+    }
+    /** puts an item on and applies its modifiers, with no lock check - the shared half of `equip` and `fromJSON` */
+    wear(slot, item) {
         this.worn.set(slot, item);
         for (const modifier of item.modifiers ?? []) {
             this.stats?.addModifier({ ...modifier, source: item });
         }
-        return previous;
     }
     /** @returns the removed item, or undefined for an empty slot - or a locked one, which stays put */
     unequip(slot) {
@@ -53,5 +75,33 @@ export class EquipmentSlots {
         if (!this.names.has(slot))
             throw new Error(`no such equipment slot: "${slot}"`);
     }
+    /**
+     * Which slot holds which item, by whatever id `identify` gives each one.
+     *
+     * An item is a game's own object here (`Item` is a type parameter, and `EquippableItem`
+     * requires only `modifiers`), so this framework has no idea what identifies one. The
+     * caller says, usually with the same id its item table is keyed by.
+     */
+    toJSON(identify) {
+        return { worn: [...this.worn].map(([slot, item]) => [slot, identify(item)]) };
+    }
+    /**
+     * Rebuilds the slots and re-equips everything, so each item's modifiers land back on the
+     * `StatBlock` exactly as they were.
+     *
+     * That reapplication is the point: `StatBlock.toJSON` deliberately saves no modifiers,
+     * precisely because whatever applied them puts them back on load. A locked item is
+     * restored rather than refused - a cursed ring the character was already wearing is still
+     * on their finger after a reload, and `equip`'s refusal is about *putting one on*, which
+     * is not what this is doing.
+     */
+    static fromJSON(defs, data) {
+        const equipment = new EquipmentSlots(defs.slots, defs.stats ?? null, { locked: defs.locked });
+        for (const [slot, id] of data.worn) {
+            equipment.assertSlot(slot);
+            equipment.wear(slot, defs.resolve(id));
+        }
+        return equipment;
+    }
 }
 //# sourceMappingURL=Equipment.js.map

package/dist/actors/Equipment.js.map

@@ -1 +1 @@
-{"version":3,"file":"Equipment.js","sourceRoot":"","sources":["../../src/actors/Equipment.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAM1B,YAAY,KAAsB,EAAE,KAAK,GAAqB,IAAI,EAAE,OAAO,GAAiC,EAAE;QAJtG,SAAI,GAAG,IAAI,GAAG,EAAc,CAAC;QAKpC,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,GAAG,CAAC,IAAU;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,4JAA4J;IAC5J,QAAQ,CAAC,IAAU;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAU,EAAE,IAAU;QAC3B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,mGAAmG;IACnG,OAAO,CAAC,IAAU;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,SAAS,CAAC;QAEpD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,KAAK;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAEO,UAAU,CAAC,IAAU;QAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,GAAG,CAAC,CAAC;IACjF,CAAC;CACD"}
+{"version":3,"file":"Equipment.js","sourceRoot":"","sources":["../../src/actors/Equipment.ts"],"names":[],"mappings":"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"}

package/dist/actors/Inventory.d.ts

@@ -5,13 +5,33 @@
  * stacking means in practice - forty arrows are one inventory slot, not forty. Weight and
  * capacity are optional: a game that does not track carry weight simply never sets a
  * capacity, and every check trivially passes.
+ *
+ * @example
+ * ```ts
+ * import { Inventory } from '@datamoc/mw_games/actors';
+ *
+ * const bag = new Inventory({ capacity: 50 });
+ * bag.add({ id: 'potion', quantity: 3, stackable: true, weight: 0.5 });
+ * bag.add({ id: 'potion', quantity: 2, stackable: true, weight: 0.5 }); // merges into one stack of 5
+ *
+ * const potion = bag.find('potion');
+ * console.log(potion?.quantity, bag.totalWeight);
+ * ```
  */
 export interface InventoryItem {
-    /** identifies the kind of item; two stackable entries with the same id merge */
+    /** identifies the kind of item; two stackable entries with the same id (and `instanceId`) merge */
     id: string;
     quantity: number;
     stackable?: boolean;
     weight?: number;
+    /**
+     * Distinguishes otherwise-identical instances of the same item id - two `"sword"`s, one
+     * enchanted and one not, or two enchanted differently - so they never silently merge into
+     * one stack the way plain quantity stacking assumes every unit of an id is interchangeable.
+     * Omitted (the default, and the only behaviour before this existed), every stackable item
+     * of an id still merges into a single stack.
+     */
+    instanceId?: string;
     /** an unidentified potion, a cursed ring the player does not yet know is cursed */
     identified?: boolean;
     cursed?: boolean;
@@ -37,7 +57,8 @@ export declare class Inventory {
     get items(): readonly InventoryItem[];
     get totalWeight(): number;
     private weightOf;
-    find(id: string): InventoryItem | undefined;
+    /** Finds the first item of a kind, or the matching instance when `instanceId` is supplied. */
+    find(id: string, instanceId?: string): InventoryItem | undefined;
     /**
      * Adds an item, merging into an existing stack when both are stackable.
      *
@@ -45,6 +66,52 @@ export declare class Inventory {
      */
     add(item: InventoryItem): boolean;
     /** removes up to `quantity` (default: the whole stack); the slot disappears once empty */
-    remove(id: string, quantity?: number): void;
+    remove(id: string, quantity?: number, instanceId?: string): void;
+    /**
+     * Takes up to `quantity` from one stack and returns an item snapshot suitable for adding to
+     * another inventory. All instance state travels with it; only the quantity is split.
+     */
+    take(id: string, quantity?: number, instanceId?: string): InventoryItem | undefined;
+    /**
+     * What a save has to remember about one slot: its id, how many, and every field that can
+     * diverge between two items sharing that id.
+     *
+     * The split is the whole design question here. `stackable` and `weight` describe the *kind*
+     * of item and live in a game's own item table, so they are supplied fresh on load like
+     * every other definition in this framework, and a game that rebalances an item's weight
+     * sees the new value on an old save rather than the stale one baked into it. Everything
+     * else - an enchantment level, wear, a rolled affix, whether it has been identified, the
+     * `instanceId` keeping two otherwise-identical swords apart - belongs to the individual
+     * item and is exactly what would be lost if a save recorded only "3 x potion".
+     */
+    toJSON(): SavedInventory;
+    /**
+     * Rebuilds an inventory, taking each item's kind-level fields from `defs`.
+     *
+     * Throws on an id `defs` does not know, rather than restoring a weightless unstackable
+     * ghost of it: a save naming an item the game no longer has is a real problem, and finding
+     * out at load is far cheaper than finding out when a carry-weight check silently disagrees.
+     */
+    static fromJSON(defs: ReadonlyMap<string, ItemDefinition>, data: SavedInventory): Inventory;
+}
+/** the kind-level fields a game's own item table supplies, rather than the save file */
+export type ItemDefinition = Pick<InventoryItem, 'stackable' | 'weight'>;
+/** one slot as saved: instance state only, no kind-level fields */
+export interface SavedInventoryItem {
+    id: string;
+    quantity: number;
+    instanceId?: string;
+    identified?: boolean;
+    cursed?: boolean;
+    blessed?: boolean;
+    level?: number;
+    affix?: string;
+    durability?: number;
+    maxDurability?: number;
+    contents?: SavedInventory;
+}
+export interface SavedInventory {
+    capacity?: number;
+    slots: SavedInventoryItem[];
 }
 //# sourceMappingURL=Inventory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Inventory.d.ts","sourceRoot":"","sources":["../../src/actors/Inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC7B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACrB,OAAO,CAAC,KAAK,CAAuB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,YAAY,OAAO,GAAE,gBAAqB,EAEzC;IAED,IAAI,KAAK,IAAI,SAAS,aAAa,EAAE,CAEpC;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,OAAO,CAAC,QAAQ;IAIhB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAehC;IAED,0FAA0F;IAC1F,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAO1C;CACD"}
+{"version":3,"file":"Inventory.d.ts","sourceRoot":"","sources":["../../src/actors/Inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC7B,mGAAmG;IACnG,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACrB,OAAO,CAAC,KAAK,CAAuB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,YAAY,OAAO,GAAE,gBAAqB,EAEzC;IAED,IAAI,KAAK,IAAI,SAAS,aAAa,EAAE,CAEpC;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,OAAO,CAAC,QAAQ;IAIhB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE/D;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAiBhC;IAED,0FAA0F;IAC1F,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ/D;IAED;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAY7E;IAED;;;;;;;;;;;OAWG;IACH,MAAM,IAAI,cAAc,CAiBvB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,SAAS,CAiB1F;CACD;AAED,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AAEzE,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC5B"}

package/dist/actors/Inventory.js

@@ -5,6 +5,18 @@
  * stacking means in practice - forty arrows are one inventory slot, not forty. Weight and
  * capacity are optional: a game that does not track carry weight simply never sets a
  * capacity, and every check trivially passes.
+ *
+ * @example
+ * ```ts
+ * import { Inventory } from '@datamoc/mw_games/actors';
+ *
+ * const bag = new Inventory({ capacity: 50 });
+ * bag.add({ id: 'potion', quantity: 3, stackable: true, weight: 0.5 });
+ * bag.add({ id: 'potion', quantity: 2, stackable: true, weight: 0.5 }); // merges into one stack of 5
+ *
+ * const potion = bag.find('potion');
+ * console.log(potion?.quantity, bag.totalWeight);
+ * ```
  */
 export class Inventory {
     constructor(options = {}) {
@@ -20,8 +32,9 @@ export class Inventory {
     weightOf(item) {
         return (item.weight ?? 0) * item.quantity + (item.contents?.totalWeight ?? 0);
     }
-    find(id) {
-        return this.slots.find((item) => item.id === id);
+    /** Finds the first item of a kind, or the matching instance when `instanceId` is supplied. */
+    find(id, instanceId) {
+        return this.slots.find((item) => item.id === id && (instanceId === undefined || item.instanceId === instanceId));
     }
     /**
      * Adds an item, merging into an existing stack when both are stackable.
@@ -29,11 +42,15 @@ export class Inventory {
      * @returns false when a capacity is set and this would exceed it - nothing is added
      */
     add(item) {
+        if (!Number.isFinite(item.quantity) || item.quantity <= 0)
+            return false;
+        if (item.weight !== undefined && (!Number.isFinite(item.weight) || item.weight < 0))
+            return false;
         if (this.capacity !== undefined && this.totalWeight + this.weightOf(item) > this.capacity) {
             return false;
         }
         if (item.stackable) {
-            const existing = this.slots.find((s) => s.id === item.id && s.stackable);
+            const existing = this.slots.find((s) => s.id === item.id && s.stackable && s.instanceId === item.instanceId);
             if (existing) {
                 existing.quantity += item.quantity;
                 return true;
@@ -43,8 +60,10 @@ export class Inventory {
         return true;
     }
     /** removes up to `quantity` (default: the whole stack); the slot disappears once empty */
-    remove(id, quantity) {
-        const index = this.slots.findIndex((item) => item.id === id);
+    remove(id, quantity, instanceId) {
+        if (quantity !== undefined && (!Number.isFinite(quantity) || quantity <= 0))
+            return;
+        const index = this.slots.findIndex((item) => item.id === id && (instanceId === undefined || item.instanceId === instanceId));
         if (index === -1)
             return;
         const item = this.slots[index];
@@ -52,5 +71,90 @@ export class Inventory {
         if (item.quantity <= 0)
             this.slots.splice(index, 1);
     }
+    /**
+     * Takes up to `quantity` from one stack and returns an item snapshot suitable for adding to
+     * another inventory. All instance state travels with it; only the quantity is split.
+     */
+    take(id, quantity = 1, instanceId) {
+        if (!Number.isFinite(quantity) || quantity <= 0)
+            return undefined;
+        const index = this.slots.findIndex((item) => item.id === id && (instanceId === undefined || item.instanceId === instanceId));
+        if (index === -1)
+            return undefined;
+        const item = this.slots[index];
+        const taken = Math.min(Math.floor(quantity), item.quantity);
+        if (taken <= 0)
+            return undefined;
+        const snapshot = { ...item, quantity: taken };
+        item.quantity -= taken;
+        if (item.quantity <= 0)
+            this.slots.splice(index, 1);
+        return snapshot;
+    }
+    /**
+     * What a save has to remember about one slot: its id, how many, and every field that can
+     * diverge between two items sharing that id.
+     *
+     * The split is the whole design question here. `stackable` and `weight` describe the *kind*
+     * of item and live in a game's own item table, so they are supplied fresh on load like
+     * every other definition in this framework, and a game that rebalances an item's weight
+     * sees the new value on an old save rather than the stale one baked into it. Everything
+     * else - an enchantment level, wear, a rolled affix, whether it has been identified, the
+     * `instanceId` keeping two otherwise-identical swords apart - belongs to the individual
+     * item and is exactly what would be lost if a save recorded only "3 x potion".
+     */
+    toJSON() {
+        return {
+            capacity: this.capacity,
+            slots: this.slots.map((item) => ({
+                id: item.id,
+                quantity: item.quantity,
+                instanceId: item.instanceId,
+                identified: item.identified,
+                cursed: item.cursed,
+                blessed: item.blessed,
+                level: item.level,
+                affix: item.affix,
+                durability: item.durability,
+                maxDurability: item.maxDurability,
+                contents: item.contents?.toJSON(),
+            })),
+        };
+    }
+    /**
+     * Rebuilds an inventory, taking each item's kind-level fields from `defs`.
+     *
+     * Throws on an id `defs` does not know, rather than restoring a weightless unstackable
+     * ghost of it: a save naming an item the game no longer has is a real problem, and finding
+     * out at load is far cheaper than finding out when a carry-weight check silently disagrees.
+     */
+    static fromJSON(defs, data) {
+        const inventory = new Inventory({ capacity: data.capacity });
+        inventory.slots = data.slots.map((saved) => {
+            const definition = defs.get(saved.id);
+            if (!definition)
+                throw new Error(`Inventory.fromJSON: no definition for item "${saved.id}"`);
+            const { contents, ...instance } = saved;
+            //the definition first, then the saved instance state over it, with absent optional
+            //fields dropped rather than written as undefined - spreading those would overwrite
+            //the definition's own weight or stackable flag with nothing
+            const item = { ...definition, ...stripUndefined(instance), id: saved.id, quantity: saved.quantity };
+            if (contents)
+                item.contents = Inventory.fromJSON(defs, contents);
+            return item;
+        });
+        return inventory;
+    }
+}
+/**
+ * Drops keys whose value is `undefined`.
+ *
+ * `toJSON` writes every optional field, so a slot that never had a `level` round-trips as
+ * `level: undefined`. Spreading that over a definition would overwrite the definition's own
+ * value with `undefined` rather than leaving it alone, which is how a restored item would
+ * quietly lose its weight.
+ */
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
 }
 //# sourceMappingURL=Inventory.js.map

package/dist/actors/Inventory.js.map

@@ -1 +1 @@
-{"version":3,"file":"Inventory.js","sourceRoot":"","sources":["../../src/actors/Inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiCH,MAAM,OAAO,SAAS;IAIrB,YAAY,OAAO,GAAqB,EAAE;QAHlC,UAAK,GAAoB,EAAE,CAAC;QAInC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;IAEO,QAAQ,CAAC,IAAmB;QACnC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,IAAI,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,CAAC,EAAU;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAmB;QACtB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3F,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC;YACzE,IAAI,QAAQ,EAAE,CAAC;gBACd,QAAQ,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC;gBACnC,OAAO,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACb,CAAC;IAED,0FAA0F;IAC1F,MAAM,CAAC,EAAU,EAAE,QAAiB;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7D,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO;QAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,QAAQ,IAAI,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC3C,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;CACD"}
+{"version":3,"file":"Inventory.js","sourceRoot":"","sources":["../../src/actors/Inventory.ts"],"names":[],"mappings":"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"}

package/dist/actors/ItemState.d.ts

@@ -4,11 +4,33 @@ import type { InventoryItem } from './Inventory.ts';
  * an enchantment/upgrade level, and durability that wears down with use. Small, focused
  * functions over a plain `InventoryItem` - the same size of primitive `skillCheck` already is -
  * rather than a class, since none of the three need to remember anything beyond the item.
+ *
+ * @example
+ * ```ts
+ * import { identify, enchant, damageItem, repairItem } from '@datamoc/mw_games/actors';
+ *
+ * const sword = { id: 'sword', quantity: 1, durability: 30, maxDurability: 50 };
+ *
+ * identify(sword);
+ * enchant(sword, 1); // now +1
+ *
+ * const broke = damageItem(sword, 40); // durability floors at 0
+ * repairItem(sword, 10);
+ * ```
  */
 /** reveals an item's real nature - a potion's true effect, a ring's curse - once identified */
 export declare function identify(item: InventoryItem): void;
-/** raises (or, given a negative delta, lowers) an item's enchantment/upgrade level */
-export declare function enchant(item: InventoryItem, delta: number): number;
+/** whether an upgrade leaves an item's affix as it is, or strips it */
+export type AffixUpgradePolicy = 'keep' | 'remove';
+/**
+ * Raises (or, given a negative delta, lowers) an item's enchantment/upgrade level.
+ *
+ * @param affixPolicy `'keep'` (the default, and the only behaviour before this option
+ * existed) leaves whatever affix the item carries untouched; `'remove'` strips it - some
+ * upgrade paths only preserve an enchantment past a certain rarity tier, a game's own rule
+ * this only ever applies when asked to
+ */
+export declare function enchant(item: InventoryItem, delta: number, affixPolicy?: AffixUpgradePolicy): number;
 /**
  * Wears an item down by `amount`. An item with no `maxDurability` set cannot wear out at all
  * and this is a no-op - durability is opt-in per item, not a hidden default every item pays for.

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

@@ -1 +1 @@
-{"version":3,"file":"ItemState.d.ts","sourceRoot":"","sources":["../../src/actors/ItemState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;GAKG;AAEH,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAElD;AAED,sFAAsF;AACtF,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGpE"}
+{"version":3,"file":"ItemState.d.ts","sourceRoot":"","sources":["../../src/actors/ItemState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAElD;AAED,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAE,kBAA2B,GAAG,MAAM,CAK5G;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIpE"}

package/dist/actors/ItemState.js

@@ -1,16 +1,41 @@
+import { removeAffix } from './Affix.js';
 /**
  * The three item-shaped states `Inventory` only had fields for, not behaviour: identification,
  * an enchantment/upgrade level, and durability that wears down with use. Small, focused
  * functions over a plain `InventoryItem` - the same size of primitive `skillCheck` already is -
  * rather than a class, since none of the three need to remember anything beyond the item.
+ *
+ * @example
+ * ```ts
+ * import { identify, enchant, damageItem, repairItem } from '@datamoc/mw_games/actors';
+ *
+ * const sword = { id: 'sword', quantity: 1, durability: 30, maxDurability: 50 };
+ *
+ * identify(sword);
+ * enchant(sword, 1); // now +1
+ *
+ * const broke = damageItem(sword, 40); // durability floors at 0
+ * repairItem(sword, 10);
+ * ```
  */
 /** reveals an item's real nature - a potion's true effect, a ring's curse - once identified */
 export function identify(item) {
     item.identified = true;
 }
-/** raises (or, given a negative delta, lowers) an item's enchantment/upgrade level */
-export function enchant(item, delta) {
+/**
+ * Raises (or, given a negative delta, lowers) an item's enchantment/upgrade level.
+ *
+ * @param affixPolicy `'keep'` (the default, and the only behaviour before this option
+ * existed) leaves whatever affix the item carries untouched; `'remove'` strips it - some
+ * upgrade paths only preserve an enchantment past a certain rarity tier, a game's own rule
+ * this only ever applies when asked to
+ */
+export function enchant(item, delta, affixPolicy = 'keep') {
+    if (!Number.isFinite(delta))
+        return item.level ?? 0;
     item.level = (item.level ?? 0) + delta;
+    if (affixPolicy === 'remove')
+        removeAffix(item);
     return item.level;
 }
 /**
@@ -22,6 +47,8 @@ export function enchant(item, delta) {
 export function damageItem(item, amount) {
     if (item.maxDurability === undefined)
         return false;
+    if (!Number.isFinite(amount) || amount <= 0)
+        return (item.durability ?? item.maxDurability) <= 0;
     item.durability = Math.max(0, (item.durability ?? item.maxDurability) - amount);
     return item.durability <= 0;
 }
@@ -29,6 +56,8 @@ export function damageItem(item, amount) {
 export function repairItem(item, amount) {
     if (item.maxDurability === undefined)
         return;
+    if (!Number.isFinite(amount) || amount <= 0)
+        return;
     item.durability = Math.min(item.maxDurability, (item.durability ?? item.maxDurability) + amount);
 }
 //# sourceMappingURL=ItemState.js.map

package/dist/actors/ItemState.js.map

@@ -1 +1 @@
-{"version":3,"file":"ItemState.js","sourceRoot":"","sources":["../../src/actors/ItemState.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,IAAmB;IAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;AACxB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,OAAO,CAAC,IAAmB,EAAE,KAAa;IACzD,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,MAAc;IAC7D,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAEnD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,MAAc;IAC7D,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,OAAO;IAC7C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,CAAC;AAClG,CAAC"}
+{"version":3,"file":"ItemState.js","sourceRoot":"","sources":["../../src/actors/ItemState.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,IAAmB;IAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;AACxB,CAAC;AAKD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,IAAmB,EAAE,KAAa,EAAE,WAAW,GAAuB,MAAM;IACnG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;IACvC,IAAI,WAAW,KAAK,QAAQ;QAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,MAAc;IAC7D,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAEjG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,MAAc;IAC7D,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,OAAO;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO;IACpD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,CAAC;AAClG,CAAC"}

package/dist/actors/ItemStatusEffect.d.ts

@@ -22,6 +22,19 @@ export interface ItemStatusEffectHandle {
  * it), and restores exactly that value once `clock` expires the effect or `cancel()` is
  * called early - the same "never has to remember to remove what it added" guarantee
  * `applyStatusEffect` already gives a `StatBlock`.
+ *
+ * @example
+ * ```ts
+ * import { applyItemStatusEffect } from '@datamoc/mw_games/actors';
+ * import { TurnClock } from '@datamoc/mw_games/world';
+ *
+ * const sword = { id: 'sword', quantity: 1, blessed: false };
+ * const clock = new TurnClock();
+ *
+ * const blessing = applyItemStatusEffect(sword, clock, { fields: { blessed: true }, duration: 3 });
+ * clock.advance(3); // blessed reverts to false automatically
+ * blessing.cancel(); // or end it early
+ * ```
  */
 export declare function applyItemStatusEffect<T extends object>(item: T, clock: EffectClock, options: ItemStatusEffectOptions<T>): ItemStatusEffectHandle;
 //# sourceMappingURL=ItemStatusEffect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ItemStatusEffect.d.ts","sourceRoot":"","sources":["../../src/actors/ItemStatusEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACzC,2FAA2F;IAC3F,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,sGAAsG;AACtG,MAAM,WAAW,sBAAsB;IACtC,MAAM,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACrD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,sBAAsB,CAuBxB"}
+{"version":3,"file":"ItemStatusEffect.d.ts","sourceRoot":"","sources":["../../src/actors/ItemStatusEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACzC,2FAA2F;IAC3F,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,sGAAsG;AACtG,MAAM,WAAW,sBAAsB;IACtC,MAAM,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACrD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,sBAAsB,CAuBxB"}

package/dist/actors/ItemStatusEffect.js

@@ -9,6 +9,19 @@
  * it), and restores exactly that value once `clock` expires the effect or `cancel()` is
  * called early - the same "never has to remember to remove what it added" guarantee
  * `applyStatusEffect` already gives a `StatBlock`.
+ *
+ * @example
+ * ```ts
+ * import { applyItemStatusEffect } from '@datamoc/mw_games/actors';
+ * import { TurnClock } from '@datamoc/mw_games/world';
+ *
+ * const sword = { id: 'sword', quantity: 1, blessed: false };
+ * const clock = new TurnClock();
+ *
+ * const blessing = applyItemStatusEffect(sword, clock, { fields: { blessed: true }, duration: 3 });
+ * clock.advance(3); // blessed reverts to false automatically
+ * blessing.cancel(); // or end it early
+ * ```
  */
 export function applyItemStatusEffect(item, clock, options) {
     const previous = new Map();

package/dist/actors/ItemStatusEffect.js.map

@@ -1 +1 @@
-{"version":3,"file":"ItemStatusEffect.js","sourceRoot":"","sources":["../../src/actors/ItemStatusEffect.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACpC,IAAO,EACP,KAAkB,EAClB,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAgB,EAAE,CAAC;QAC9D,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAe,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,GAAS,EAAE;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxD,CAAC,CAAC;IAEF,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;QACpC,QAAQ,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,OAAO;QACN,MAAM,EAAE,GAAG,EAAE;YACZ,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACjB,OAAO,EAAE,CAAC;QACX,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"ItemStatusEffect.js","sourceRoot":"","sources":["../../src/actors/ItemStatusEffect.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CACpC,IAAO,EACP,KAAkB,EAClB,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAgB,EAAE,CAAC;QAC9D,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAe,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,GAAS,EAAE;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxD,CAAC,CAAC;IAEF,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;QACpC,QAAQ,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,OAAO;QACN,MAAM,EAAE,GAAG,EAAE;YACZ,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACjB,OAAO,EAAE,CAAC;QACX,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/actors/Loot.d.ts

@@ -16,7 +16,21 @@ export interface LootTable {
     /** probability that this table drops anything at all, 0 to 1; defaults to 1 (always) */
     chance?: number;
 }
-/** @returns what dropped, or null when the roll misses or the table is empty */
+/**
+ * @returns what dropped, or null when the roll misses or the table is empty
+ *
+ * @example
+ * ```ts
+ * import { rollLoot, type LootTable } from '@datamoc/mw_games/actors';
+ *
+ * const ratLoot: LootTable = {
+ *   chance: 0.5,
+ *   entries: [{ id: 'gold', weight: 3, quantity: 5 }, { id: 'cheese', weight: 1 }],
+ * };
+ *
+ * const drop = rollLoot(ratLoot); // { id: 'gold', quantity: 5 }, or null, most of the time
+ * ```
+ */
 export declare function rollLoot(table: LootTable): {
     id: string;
     quantity: number;

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

@@ -1 +1 @@
-{"version":3,"file":"Loot.d.ts","sourceRoot":"","sources":["../../src/actors/Loot.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IAE9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASlF"}
+{"version":3,"file":"Loot.d.ts","sourceRoot":"","sources":["../../src/actors/Loot.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IAE9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASlF"}