@datamoc/mw_games 0.2.1 → 0.4.0

package/README.md

@@ -1,7 +1,9 @@
 # mwg
 
-A framework for building primarily 2D top-down games that run **from a local file**: no
-server, no install, no runtime to download. An optional Babylon.js module supports 3D maps.
+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
+PixiJS in 2D (`mwg/two-d`) or Babylon.js in 3D (`mwg/3d`), and the dungeon generation, map
+events, quests, stats and turn order underneath are the same either way.
 
 Licensed under the [MPL-2.0](LICENSE): games built with `mwg` carry no licence obligation
 of their own; improvements to `mwg`'s own files are shared back.
@@ -9,10 +11,14 @@ of their own; improvements to `mwg`'s own files are shared back.
 **[Live examples and API docs](https://datamoc.github.io/mwg/)**: every example below,
 playable in the browser with no download, plus the generated API reference.
 
-> **Status: early release (v0.2.1).** Every module in the shared floor below, plus optional
+> **Status: early release (v0.4.0).** Every module in the shared floor below, plus optional
 > 3D, mobile (Capacitor) and desktop (WebView2) packaging, is built and tested - see
-> [ROADMAP.md](ROADMAP.md) for the full, numbered history. Still `0.y.z`: the "public API"
-> can still change between minor versions, and the wider genre-specific modules keep growing.
+> [ROADMAP.md](ROADMAP.md) for the full, numbered history.
+>
+> 0.4.0 is the reshaping release: the renderer moved out of `mwg/core`, `render`/`ui`/`stage`
+> became `mwg/two-d`, and a set of names that meant several things each were made to mean one.
+> It is deliberately the last such release planned before 1.0. Still `0.y.z` until then, but
+> the intent from here is additions rather than renames.
 
 ## What it is for
 
@@ -75,7 +81,7 @@ npm install @datamoc/mw_games
 ```
 ```ts
 import { Game, Scene } from '@datamoc/mw_games/core';
-import { Sprite } from '@datamoc/mw_games/render';
+import { Sprite } from '@datamoc/mw_games/two-d/render';
 ```
 
 No npm registry access (an offline machine, a pinned artifact for reproducible builds)?
@@ -130,21 +136,21 @@ only some do.
 | | deterministic seeded RNG, reproducible across machines | `mwg/core` |
 | | named, versioned save slots with a preview | `mwg/core` |
 | **render** | sprite batching at thousands of tiles | PixiJS |
-| | per-sprite colour transform: multiply **and** add | `mwg/render` |
-| | animated sprites driven by named frame sets | `mwg/render` |
-| | dense tile maps, multi-layer, with per-cell visibility | `mwg/render` |
-| | hexagonal tile maps, alongside square, as a second grid shape | `mwg/render` |
-| | camera with follow, pan, shake and zoom | `mwg/render` |
-| | particle effects | `mwg/render` |
-| | screen transitions: fade, flash, tint | `mwg/render` |
-| **ui** | windows, lists, tooltips | `mwg/ui` |
+| | per-sprite colour transform: multiply **and** add | `mwg/two-d/render` |
+| | animated sprites driven by named frame sets | `mwg/two-d/render` |
+| | dense tile maps, multi-layer, with per-cell visibility | `mwg/two-d/render` |
+| | hexagonal tile maps, alongside square, as a second grid shape | `mwg/two-d/render` |
+| | camera with follow, pan, shake and zoom | `mwg/two-d/render` |
+| | particle effects | `mwg/two-d/render` |
+| | screen transitions: fade, flash, tint | `mwg/two-d/render` |
+| **ui** | windows, lists, tooltips | `mwg/two-d/ui` |
 | | text and fonts, including non-latin fallback | PixiJS |
 | | pointer, keyboard and gamepad input with rebinding | `mwg/core` |
 | **text** | message tables per language, compiled at build time | `mwg/i18n` |
 | | plurals, gendered forms and interpolation | `mwg/i18n` |
 | | Fluent-style FTL catalogs with locale-aware fallback and variants | `mwg/i18n` |
 | | left-to-right, right-to-left and vertical writing | `mwg/i18n` |
-| | interface mirrored for right-to-left languages | `mwg/ui` |
+| | interface mirrored for right-to-left languages | `mwg/two-d/ui` |
 | | a missing translation falls back rather than showing a key | `mwg/i18n` |
 | **audio** | sound effects with pooling, music with crossfade | `mwg/audio` |
 
@@ -175,10 +181,10 @@ The Wesnoth-shaped half: a grid whose shape is a parameter, not a parallel imple
 
 | capability | provided by |
 | --- | --- |
-| hexagonal tile maps, addressed by axial or offset coordinates | `mwg/render` |
+| hexagonal tile maps, addressed by axial or offset coordinates | `mwg/two-d/render` |
 | movement cost and defense bonus by terrain, hex or square alike | `mwg/roguelike` |
 | field of view and pathfinding over a hex grid, not just square | `mwg/roguelike` |
-| isometric (and staggered) projection, alongside orthogonal and hex | `mwg/render` |
+| isometric (and staggered) projection, alongside orthogonal and hex | `mwg/two-d/render` |
 | zone of control: a hex a unit can only move into, not through, unless already engaged | `mwg/board` |
 | an army economy: recruiting against a currency, recalling from a pool, per-turn upkeep | `mwg/board` |
 
@@ -199,11 +205,11 @@ reference, the same way Wesnoth is the hex-shaped one.
 | event triggers: action, touch, autorun, parallel | `mwg/rpg` |
 | a command interpreter for cutscenes: move routes, waits, branches, calls | `mwg/rpg` |
 | global switches and variables, saved with the game | `mwg/rpg` |
-| message box with portraits, choices and typewriter reveal | `mwg/rpg` + `mwg/ui` |
+| message box with portraits, choices and typewriter reveal | `mwg/rpg` + `mwg/two-d/ui` |
 | grid movement tweened between tiles, with a walk cycle | `mwg/rpg` |
-| a dialogue stage: backdrop, characters, expressions, speaker focus | `mwg/stage` |
-| scenes written as a list of commands, awaited as one call | `mwg/stage` |
-| named passages a choice can jump between, for a story that is a graph, not a line | `mwg/stage` |
+| a dialogue stage: backdrop, characters, expressions, speaker focus | `mwg/two-d/stage` |
+| scenes written as a list of commands, awaited as one call | `mwg/two-d/stage` |
+| named passages a choice can jump between, for a story that is a graph, not a line | `mwg/two-d/stage` |
 | named save slots with a preview | `mwg/core` |
 
 ### Characters, equipment and stats
@@ -220,7 +226,7 @@ rather than classes.
 | modifiers from equipment, buffs and states, resolved in a stated order | `mwg/actors` |
 | an inventory with stacking, weight and containers | `mwg/actors` |
 | item identification, and cursed or blessed states | `mwg/actors` |
-| a layered character sprite, so worn equipment is visible | `mwg/render` |
+| a layered character sprite, so worn equipment is visible | `mwg/two-d/render` |
 
 That last row is why `tools/make-example-assets.mjs` draws its character in parts. A figure
 assembled from skin, eyes, hair and garments is one palette away from being a second
@@ -256,7 +262,7 @@ white on a hit, a room lit by a fireplace, a screen-wide tint for a night scene:
 is that one operation.
 
 Pixi's built-in `tint` is multiply-only, which can only ever darken. The additive term is
-what `mwg/render` adds, in the batch shader rather than as a per-object filter, so it costs
+what `mwg/two-d/render` adds, in the batch shader rather than as a per-object filter, so it costs
 nothing per sprite. See `examples/colour-transform`.
 
 ### Why maps and events are data, not code
@@ -279,7 +285,7 @@ Supporting more than one language is mostly bookkeeping. Supporting more than on
   can handle: canvas applies the Unicode bidirectional algorithm and shapes the glyphs, so
   a label mostly comes out right once its direction is declared. The *interface* is the
   harder half, because a right-to-left reader expects it mirrored: lists indent from the
-  right, a back arrow points the other way, a progress bar fills the other way. `mwg/ui`
+  right, a back arrow points the other way, a progress bar fills the other way. `mwg/two-d/ui`
   lays widgets out against a direction rather than against "left" so this can be flipped,
   and a game only has to mark which of its own icons must not be mirrored.
 - **Vertical**, top to bottom (traditional Chinese, Japanese, Mongolian), gets no help at
@@ -310,6 +316,49 @@ play imported animation clips. `parseVox` and `createVoxModel3D` load one Magica
 `loadModel3D` handles glTF/GLB.
 Run `npm run example:3d` for the live example or `npm run benchmark:3d` for its FPS gate.
 
+## Headless simulation
+
+`@datamoc/mw_games/simulation` has no rendering or browser imports. It provides two
+small runners while games keep their state, commands, rules, and event types:
+
+- `advanceToInput(rules, budget)` runs automatic scheduled actions until an actor needs
+  input, the game finishes, the queue is empty, or the action budget is reached. Rules
+  supply `scheduler`, `finished`, `needsInput`, and `act`. `act` returns the cost to
+  charge to the current queue entry after the action, or `null` when it handled its own
+  scheduling. A `limit` result does not grant input; the caller chooses how to resume.
+- `runScenario({ state, commands, random, step, status? })` applies a finite command
+  sequence, preserving event order and stopping when a rule returns `finished`. Each
+  rule returns `{ state, events, status: 'ready' | 'finished' }`. Results also report
+  `processedCommands`; a command need not consume a game turn.
+
+```ts
+import { runScenario } from '@datamoc/mw_games/simulation';
+
+const result = runScenario({
+  state: { position: 0 },
+  commands: [1, 2, -1],
+  random: null, // This example has no randomness; supply a generator when needed.
+  step: (state, distance, _random) => ({
+    state: { position: state.position + distance },
+    events: [{ moved: distance }],
+    status: 'ready',
+  }),
+});
+// result.state.position === 2; result.processedCommands === 3
+```
+
+The root/standalone build also exposes these as `Simulation`. The dungeon example uses
+the scheduled runner and shares its own damage rule between the scene and headless
+scenario tests. Neither runner implements a game's combat, inventory, or movement rules.
+
+For reproducibility, supply the same initial state, commands, and random state, and keep
+rules independent of wall-clock time and ambient randomness. Existing `Generator`
+instances expose `getState()`/`setState()`; store that state alongside a game's snapshot.
+The runners do not clone state, serialize arbitrary graphs, or roll back a throwing rule.
+Frame-based `core.Recorder`/`Player` remains available for UI replay; command scenarios do
+not need a frame loop. Callers must bound automatic work inside each rule, for example
+with `advanceToInput`.
+
 ## Roadmap
 
 See [ROADMAP.md](ROADMAP.md) for the full, numbered build order and implementation notes.

package/dist/actors/Affix.d.ts

@@ -11,9 +11,22 @@ import type { InventoryItem } from './Inventory.ts';
  * itself when that trigger fires, the same way `Move.effects` is data `mwg` never reads.
  */
 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 +54,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;;;;;;;;;;GAUG;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;AAmD5C;;;;;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/Barrier.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+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;;;;;;;GAOG;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":"AAeA,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

@@ -25,7 +25,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;;;;;;;;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;;;;;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":"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;;;;;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"}

package/dist/actors/Equipment.d.ts

@@ -32,9 +32,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;;;;;;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,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

@@ -29,11 +29,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 +57,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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"}