@datamoc/mw_games 0.1.1

package/README.md

@@ -0,0 +1,327 @@
+# mwg
+
+A framework for building 2D top-down games that run **from a local file** — no server, no
+install, no runtime to download.
+
+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.
+
+**[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.** The scaffolding, licence and capability spec are in place. The
+> modules below are being built in the order given in [ROADMAP.md](ROADMAP.md).
+
+## What it is for
+
+Tile-based games with a camera over a grid. Nine existing games mark out the corners of
+what that has to cover:
+
+| reference | what it demands that the others do not |
+| --- | --- |
+| **[Shattered Pixel Dungeon](https://shatteredpixel.com/shatteredpd/)** | generated dungeons, field of view, energy-cost turn scheduling, permadeath, dense inventory UI |
+| **[ADOM](https://www.adom.de/)** | many persistent maps joined by a world map, hunger and long-running effects, skills and attributes, quests inside a roguelike |
+| **[RPG Maker](https://www.rpgmakerweb.com/) projects** | hand-authored maps, events on tiles, dialogue and cutscenes, a party, menu combat, save slots |
+| **[Pokémon](https://www.pokemon.com/), in its traditional form** | encounter tables by terrain, a roster of creatures with derived stats, an effectiveness matrix, speed-ordered battles, capture and storage |
+| **[Ren'Py](https://www.renpy.org/), and the conversation scenes every RPG borrows from it** | a backdrop with characters standing in front of it, expressions, whoever speaks picked out from the rest, branching written as data |
+| **[The Battle for Wesnoth](https://www.wesnoth.org/)** | hexagonal tactical maps, movement cost and defense by terrain, zone of control, turn-based unit combat with recruiting and upkeep |
+| **[Flare](https://flarerpg.org/)'s Empyrean Campaign** | isometric tile maps, loaded straight from Tiled's own isometric export |
+| **[Dungeon Crawl Stone Soup](https://crawl.develz.org/) (Tiles)** | a branching dungeon of many interconnected levels, and autoexplore pathing to the nearest unseen tile |
+| **[Twine](https://twinery.org/)** | a story as named passages, not one linear list - a choice jumps to another passage by name, which can loop back or braid together, entirely on state and no visual stage at all |
+
+Underneath they share almost everything: a grid, a camera following someone across it,
+sprites that need tinting, turn-taking, characters with stats and equipment, an inventory,
+and a great many windows. The differences are narrower than the genre labels suggest — one
+generates its maps and another authors them; one schedules monsters and another schedules
+events; one rolls encounters from the terrain and another places them by hand; one puts its
+conversations in a corner of the map and another gives them the whole screen; one moves in
+four directions on a square grid and another in six on a hex grid.
+
+`mwg` provides that shared floor plus each specialism, on top of
+[PixiJS](https://pixijs.com) for rendering and [rot.js](https://ondras.github.io/rot.js/)
+for the classic roguelike algorithms. See [Capability spec](#capability-spec).
+
+These are references for *what a finished game of each kind has to do*, and nothing more.
+No code, asset, data table or file format is taken from any of them — see
+[Licence and provenance](#licence-and-provenance).
+
+### On being "like RPG Maker"
+
+Worth being precise, because RPG Maker is two things and `mwg` is only aiming at one of
+them for now.
+
+It is a **runtime** — a tile engine, an event interpreter, a battle system, a message box.
+That is what the capability spec below commits to.
+
+It is also an **editor**, and that is what most people actually mean by RPG Maker: drawing
+maps and wiring events without writing code. `mwg` does not have one. What it does instead
+is keep maps, events and dialogue as **plain data** rather than code, so an editor can be
+built against that data later without reworking the runtime — and so that in the meantime
+the data can be written by hand, generated by a script, or exported from
+[Tiled](https://www.mapeditor.org/), which is free and already good at this.
+
+That data is loaded exactly like any other asset, which means the `file://` story covers it
+for free: a finished game is still a folder you double-click.
+
+## Two ways to use it
+
+**With a toolchain**, if you already use a bundler:
+
+```
+npm install @datamoc/mw_games
+```
+```ts
+import { Game, Scene } from '@datamoc/mw_games/core';
+import { Sprite } from '@datamoc/mw_games/render';
+```
+
+No npm registry access (an offline machine, a pinned artifact for reproducible builds)?
+`npm pack @datamoc/mw_games` downloads the exact published tarball; install it by path
+instead of by name:
+
+```
+npm install ./datamoc-mw_games-0.1.1.tgz
+```
+
+**Without either.** Drop one file next to your page and open it — this path exists because
+the framework's own target is a game you can run by double-clicking it. Download
+`mw_games.global.js` from a [release](https://github.com/datamoc/mwg/releases) (no `npm`,
+no `node_modules`, nothing to install):
+
+```html
+<script src="mw_games.global.js"></script>
+<script>
+  const game = new mw_games.Game(document.getElementById('game'));
+</script>
+```
+
+Node and npm are developer tools here, in the same sense that a compiler is. Nothing from
+them is present when the game runs: the output is HTML, JavaScript and assets.
+
+## Running from `file://`
+
+Opening a page from disk takes three capabilities away, and the framework is shaped around
+them rather than pretending otherwise:
+
+| what is blocked | consequence | how `mwg` handles it |
+| --- | --- | --- |
+| ES modules (CORS) | `<script type="module">` will not run | the standalone build is a classic IIFE |
+| `fetch()` / XHR | no asset can be loaded on demand, no directory can be listed | `tools/compile-resources` turns assets into scripts loaded before the game |
+| cross-origin images | an `<img>` from a sibling file taints a WebGL texture in Chrome | assets travel as `data:` URIs inside those scripts |
+
+The practical effect: resources are **compiled at build time**, so at runtime every lookup
+is synchronous. Game code never awaits an asset.
+
+## Capability spec
+
+The definition of done for 1.0, drawn from what each of the nine references actually
+demands. The shared floor is what all of them need; the sections after it are the parts
+only some do.
+
+### Shared floor
+
+| area | capability | provided by |
+| --- | --- | --- |
+| **core** | fixed-step game loop, scenes, timing | `mwg/core` |
+| | signals and listeners | `mwg/core` |
+| | 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` |
+| | 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` |
+| | left-to-right, right-to-left and vertical writing | `mwg/i18n` |
+| | interface mirrored for right-to-left languages | `mwg/ui` |
+| | a missing translation falls back rather than showing a key | `mwg/i18n` |
+| **audio** | sound effects with pooling, music with crossfade | `mwg/audio` |
+
+### World
+
+Shared by everything past a single screen, and the thing ADOM needs most.
+
+| capability | provided by |
+| --- | --- |
+| many maps in one world, joined by transitions | `mwg/world` |
+| maps that persist when left and returned to | `mwg/world` |
+| an overworld map with locations on it | `mwg/world` |
+| a turn clock driving hunger, poison and other long effects | `mwg/world` |
+
+### Roguelike
+
+| capability | provided by |
+| --- | --- |
+| field of view and lighting | rot.js + `mwg/roguelike` |
+| pathfinding over a passability map | rot.js + `mwg/roguelike` |
+| turn scheduling by energy cost | `mwg/roguelike` |
+| level generation from composable room builders | `mwg/roguelike` |
+| autoexplore: pathing to the nearest unexplored cell | `mwg/roguelike` |
+
+### Tactical maps (hex)
+
+The Wesnoth-shaped half: a grid whose shape is a parameter, not a parallel implementation.
+
+| capability | provided by |
+| --- | --- |
+| hexagonal tile maps, addressed by axial or offset coordinates | `mwg/render` |
+| movement cost and defense bonus by terrain, hex or square alike | `mwg/roguelike` |
+| zone of control: a hex a unit cannot move through, only into | `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` |
+
+A game picks a grid shape once; the camera, field of view, pathfinding and turn scheduler
+work the same way over either, rather than a hex game needing its own copy of each. Between
+them, orthogonal, isometric and hex cover every map orientation
+[Tiled](https://www.mapeditor.org/) itself supports — a Tiled map loads and renders through
+the same `TileMap`, whichever orientation it was drawn in, rather than mwg reading only the
+one shape it happens to render natively. Flare's Empyrean Campaign is the isometric-shaped
+reference, the same way Wesnoth is the hex-shaped one.
+
+### RPG
+
+| capability | provided by |
+| --- | --- |
+| maps loaded as data, in any of Tiled's map orientations | `mwg/rpg` |
+| events placed on tiles, with pages selected by conditions | `mwg/rpg` |
+| 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` |
+| 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` |
+| named save slots with a preview | `mwg/core` |
+
+### Characters, equipment and stats
+
+All four references have these, and they are what a game changes most, so they are data
+rather than classes.
+
+| capability | provided by |
+| --- | --- |
+| a stat block: base attributes, derived values, and the rules that derive them | `mwg/actors` |
+| levels, experience and growth curves, all replaceable | `mwg/actors` |
+| skills and proficiencies, checked against a difficulty | `mwg/actors` |
+| equipment slots defined per game, not fixed by the framework | `mwg/actors` |
+| 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` |
+
+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
+character — and one *layer* away from showing the armour it just put on. A single flat
+sprite per character can do neither.
+
+### Creatures and battles
+
+The Pokémon-shaped half, and the part `mwg` deliberately keeps generic.
+
+| capability | provided by |
+| --- | --- |
+| species defined as data, with per-individual stats derived from them | `mwg/battle` |
+| a party with a roster and off-party storage | `mwg/battle` |
+| an effectiveness matrix between arbitrary types | `mwg/battle` |
+| turn order by speed, with move priority overriding it | `mwg/battle` |
+| moves as data: cost, target shape, effects | `mwg/battle` |
+| encounter tables per map region, weighted, with a rate per step | `mwg/world` |
+| capture, experience, levelling and evolution as replaceable rules | `mwg/battle` |
+
+`mwg` supplies the *shape*: a stat block, a type matrix, a turn queue. It supplies no
+formulas, no type chart and no species — those are a game's own design, and copying any
+particular game's would be both wrong and useless to anyone else.
+
+All of these specialisms share the tile map, the camera, the windows, the turn clock and
+the save system, which is why they sit in one framework rather than four.
+
+### Why per-sprite "multiply and add"
+
+The single most load-bearing rendering feature in either genre is the colour transform
+`texel × M + A`. Darkness outside the field of view, tinting a poisoned enemy, flashing
+white on a hit, a room lit by a fireplace, a screen-wide tint for a night scene — all of it
+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
+nothing per sprite. See `examples/colour-transform`.
+
+### Why maps and events are data, not code
+
+An RPG's content is enormous and repetitive, and almost none of it deserves to be written
+by hand in TypeScript. Keeping maps, events, dialogue and item tables as data means they
+can be authored in a spreadsheet, generated by a script, exported from Tiled, or eventually
+edited in a proper editor — without any of those options requiring changes to the runtime.
+
+It also keeps the content out of the bundle: `tools/compile-resources` treats a map file
+exactly like a sprite sheet, so adding a hundred maps does not touch the build at all.
+
+### On writing direction
+
+Supporting more than one language is mostly bookkeeping. Supporting more than one writing
+*direction* is not, and the three cases are genuinely different work:
+
+- **Left-to-right** is what everything assumes by default.
+- **Right-to-left** — Arabic, Hebrew — is two problems at once. The text itself the browser
+  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`
+  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
+  all. Canvas has no vertical writing mode, so the text has to be laid out glyph by glyph,
+  with its own rules for which characters rotate and which stand upright. This is real work
+  and it is scheduled as such, not assumed to fall out of the other two.
+
+Message tables are compiled at build time, the same way every other resource is, so adding
+a language costs nothing at runtime and a missing string falls back to the base language
+rather than showing a raw key to the player.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for the full, numbered build order — 85 items, 74 shipped and
+eleven open (3D rendering broken into a nine-step build-up plus an engine choice, all
+logged at low priority; see that file for why). Each module ships in the order given there;
+later ones build on the
+modules before them.
+
+## Licence and provenance
+
+`mwg` is MPL-2.0. Its dependencies are permissive and compatible: PixiJS is MIT, rot.js is
+BSD-3-Clause.
+
+`tools/vendored/rgssad-wasm` is a build of the `rgssad-wasm` crate from
+<https://github.com/nathaniel-daniel/rgssad-rs>, used under its MIT licence
+option (© 2022 Nathaniel Daniel) — see `tools/vendored/rgssad-wasm/README.md`.
+It is a developer-side archive tool only, not part of the framework or any game.
+
+Shattered Pixel Dungeon (GPL-3, © Oleg Dolya and Evan Debenham), The Battle for Wesnoth
+(GPL-2.0-or-later, © the Battle for Wesnoth contributors), Flare's Empyrean Campaign
+(GPL-3, © the Flare project), and Dungeon Crawl Stone Soup (GPL-2.0, © the Dungeon Crawl
+Stone Soup development team) are referenced only as design studies — a list of what a
+finished roguelike, a finished hex-based tactical game, a finished isometric one, and a
+finished branching dungeon each have to do. None of their code, assets, maps, unit
+definitions or text is included here, and `mwg` is not a derivative work of any of them.
+
+ADOM, RPG Maker, Pokémon, Ren'Py and Twine are likewise references for a *shape of game*, not
+sources of anything. `mwg` implements none of their file formats, reads none of their projects or save
+data, and includes none of their runtimes, assets, text or data tables — no type chart, no
+species list, no stat formula. Those are each game's own design work. Where a file format
+is needed, `mwg` uses Tiled's, which is open and documented.
+
+Game mechanics are not themselves protected, which is why a framework may offer "a turn
+queue ordered by speed" or "an effectiveness matrix". Particular numbers, names and
+artwork are another matter, and none appear here.
+
+The assets under `examples/assets` are generated by `tools/make-example-assets.mjs` and
+carry the project's own licence. Nothing else in this repository was downloaded from
+anywhere, with the sole exception of `tools/vendored/rgssad-wasm` above.

package/dist/actors/Advancement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Tiered specialization: level-gated tiers that grant points, offer a
+ * mutually-exclusive branch choice, or offer a capstone choice.
+ *
+ * The shape a subclass system and an armor-ability slot share: most tiers just add
+ * points a game spends elsewhere (through `SkillPoints`, typically), one tier asks the
+ * player to commit to exactly one of several branches for the rest of the run, and a
+ * late tier grants exactly one capstone. `mwg` names none of the options itself - a
+ * game's own track definition does, the same way `QuestLog` takes quest definitions.
+ *
+ * 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.
+ */
+export type AdvancementTierKind = 'points' | 'branch' | 'capstone';
+export interface AdvancementOption {
+    id: string;
+    /** shown in a choice UI; `mwg` never reads this itself */
+    description?: string;
+}
+export interface AdvancementTier {
+    /** the level at which this tier opens */
+    threshold: number;
+    kind: AdvancementTierKind;
+    /** points tiers: how many ledger points opening this tier grants in total */
+    points?: number;
+    /** branch/capstone tiers: the mutually exclusive options, exactly one may be taken */
+    options?: readonly AdvancementOption[];
+}
+export interface AdvancementTrack {
+    tiers: readonly AdvancementTier[];
+}
+export declare class Advancement {
+    private track;
+    /** how many tiers have had their points granted so far */
+    private grantedTiers;
+    private balance;
+    private choices;
+    constructor(track: AdvancementTrack);
+    /** unspent ledger points */
+    get points(): number;
+    /** tier indices whose threshold the given level has reached, in order */
+    openTiers(level: number): number[];
+    /**
+     * Opens every tier up to `level`, granting each newly opened points tier's points.
+     *
+     * @returns how many points were granted - 0 when nothing new opened, so a game can
+     * tell "level up with no new tier" from a real unlock
+     */
+    grant(level: number): number;
+    /** spends ledger points; false, spending nothing, when the balance is short */
+    spend(points: number): boolean;
+    /**
+     * Takes one option of an open branch/capstone tier - permanently. Throws for a points
+     * tier, a tier that has not opened yet, an unknown option, or a tier already decided,
+     * so a game cannot accidentally offer a choice twice.
+     */
+    choose(tierIndex: number, optionId: string, level: number): void;
+    /** the option taken at a branch/capstone tier, or null when undecided */
+    choice(tierIndex: number): string | null;
+    toJSON(): {
+        grantedTiers: number;
+        balance: number;
+        choices: [number, string][];
+    };
+    /** rebuilds advancement from save data - the track itself is supplied fresh, the same as `QuestLog` definitions */
+    static fromJSON(track: AdvancementTrack, data: {
+        grantedTiers: number;
+        balance: number;
+        choices: [number, string][];
+    }): Advancement;
+}
+//# sourceMappingURL=Advancement.d.ts.map

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

@@ -0,0 +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"}

package/dist/actors/Advancement.js

@@ -0,0 +1,98 @@
+/**
+ * Tiered specialization: level-gated tiers that grant points, offer a
+ * mutually-exclusive branch choice, or offer a capstone choice.
+ *
+ * The shape a subclass system and an armor-ability slot share: most tiers just add
+ * points a game spends elsewhere (through `SkillPoints`, typically), one tier asks the
+ * player to commit to exactly one of several branches for the rest of the run, and a
+ * late tier grants exactly one capstone. `mwg` names none of the options itself - a
+ * game's own track definition does, the same way `QuestLog` takes quest definitions.
+ *
+ * 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.
+ */
+export class Advancement {
+    constructor(track) {
+        /** how many tiers have had their points granted so far */
+        this.grantedTiers = 0;
+        this.balance = 0;
+        this.choices = new Map();
+        this.track = track;
+    }
+    /** unspent ledger points */
+    get points() {
+        return this.balance;
+    }
+    /** tier indices whose threshold the given level has reached, in order */
+    openTiers(level) {
+        const out = [];
+        this.track.tiers.forEach((tier, index) => {
+            if (level >= tier.threshold)
+                out.push(index);
+        });
+        return out;
+    }
+    /**
+     * Opens every tier up to `level`, granting each newly opened points tier's points.
+     *
+     * @returns how many points were granted - 0 when nothing new opened, so a game can
+     * tell "level up with no new tier" from a real unlock
+     */
+    grant(level) {
+        let granted = 0;
+        while (this.grantedTiers < this.track.tiers.length && level >= this.track.tiers[this.grantedTiers].threshold) {
+            const tier = this.track.tiers[this.grantedTiers];
+            if (tier.kind === 'points') {
+                this.balance += tier.points ?? 0;
+                granted += tier.points ?? 0;
+            }
+            this.grantedTiers++;
+        }
+        return granted;
+    }
+    /** spends ledger points; false, spending nothing, when the balance is short */
+    spend(points) {
+        if (this.balance < points)
+            return false;
+        this.balance -= points;
+        return true;
+    }
+    /**
+     * Takes one option of an open branch/capstone tier - permanently. Throws for a points
+     * tier, a tier that has not opened yet, an unknown option, or a tier already decided,
+     * so a game cannot accidentally offer a choice twice.
+     */
+    choose(tierIndex, optionId, level) {
+        const tier = this.track.tiers[tierIndex];
+        if (!tier)
+            throw new Error(`no such advancement tier: ${tierIndex}`);
+        if (tier.kind === 'points')
+            throw new Error(`tier ${tierIndex} grants points, it has no choice`);
+        if (level < tier.threshold)
+            throw new Error(`tier ${tierIndex} has not opened yet`);
+        if (this.choices.has(tierIndex))
+            throw new Error(`tier ${tierIndex} is already decided`);
+        if (!(tier.options ?? []).some((option) => option.id === optionId)) {
+            throw new Error(`tier ${tierIndex} has no option "${optionId}"`);
+        }
+        this.choices.set(tierIndex, optionId);
+    }
+    /** the option taken at a branch/capstone tier, or null when undecided */
+    choice(tierIndex) {
+        return this.choices.get(tierIndex) ?? null;
+    }
+    toJSON() {
+        return { grantedTiers: this.grantedTiers, balance: this.balance, choices: [...this.choices] };
+    }
+    /** rebuilds advancement from save data - the track itself is supplied fresh, the same as `QuestLog` definitions */
+    static fromJSON(track, data) {
+        const advancement = new Advancement(track);
+        advancement.grantedTiers = data.grantedTiers;
+        advancement.balance = data.balance;
+        for (const [tier, option] of data.choices)
+            advancement.choices.set(tier, option);
+        return advancement;
+    }
+}
+//# sourceMappingURL=Advancement.js.map

package/dist/actors/Advancement.js.map

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

package/dist/actors/Affix.d.ts

@@ -0,0 +1,44 @@
+import type { InventoryItem } from './Inventory.ts';
+/**
+ * Named item affixes: enchantments, glyphs, augments, curses - whatever a game's items
+ * can carry beyond their upgrade `level`.
+ *
+ * `mwg` draws the line `ItemState` already drew: `level` is a number any item can have,
+ * but what "+1 blazing" *means* is a game's own design. An affix definition therefore
+ * carries only the routing information every such system shares - which trigger it
+ * 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.
+ */
+export type AffixTrigger = 'strike' | 'defend' | 'passive';
+export interface AffixDef {
+    id: string;
+    trigger: AffixTrigger;
+    /** relative likelihood within its own table; 0 never rolls */
+    weight: number;
+    /** a curse locks the item (see `EquipmentSlots`' lock option) once identified */
+    curse?: boolean;
+    /** shown in an item description; `mwg` never reads this itself */
+    description?: string;
+}
+export interface AffixTable {
+    entries: readonly AffixDef[];
+}
+/**
+ * Weight-picks one affix from a table - the same "roll whether, then weight-pick which"
+ * shape `rollLoot` already is, with a single entry reading as "always this one".
+ *
+ * @returns null when the table is empty or every entry has weight 0
+ */
+export declare function rollAffix(table: AffixTable): AffixDef | null;
+/** the affix an item carries, if any - stored on the item next to its upgrade `level` */
+export declare function affixOf(item: InventoryItem): string | undefined;
+/**
+ * Sets an item's affix, replacing any it already had. A curse affix also marks the item
+ * `cursed`, so identification and equipment-lock behaviour follow without the game
+ * wiring them separately.
+ */
+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;
+//# sourceMappingURL=Affix.d.ts.map

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

@@ -0,0 +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"}

package/dist/actors/Affix.js

@@ -0,0 +1,35 @@
+import * as Random from '../core/Random.js';
+/**
+ * Weight-picks one affix from a table - the same "roll whether, then weight-pick which"
+ * shape `rollLoot` already is, with a single entry reading as "always this one".
+ *
+ * @returns null when the table is empty or every entry has weight 0
+ */
+export function rollAffix(table) {
+    const live = table.entries.filter((entry) => entry.weight > 0);
+    if (live.length === 0)
+        return null;
+    const index = Random.weighted(live.map((entry) => entry.weight));
+    return index === -1 ? null : live[index];
+}
+/** the affix an item carries, if any - stored on the item next to its upgrade `level` */
+export function affixOf(item) {
+    return item.affix;
+}
+/**
+ * Sets an item's affix, replacing any it already had. A curse affix also marks the item
+ * `cursed`, so identification and equipment-lock behaviour follow without the game
+ * wiring them separately.
+ */
+export function applyAffix(item, affix) {
+    item.affix = affix.id;
+    if (affix.curse)
+        item.cursed = true;
+}
+/** removes an item's affix (and its curse mark, if the affix was a curse) */
+export function removeAffix(item) {
+    if (item.affix !== undefined)
+        item.cursed = false;
+    delete item.affix;
+}
+//# sourceMappingURL=Affix.js.map

package/dist/actors/Affix.js.map

@@ -0,0 +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"}

package/dist/actors/Appearances.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-run appearance shuffling for unidentified items: which look each kind wears.
+ *
+ * A game with identification needs this the moment it has more than one unidentified
+ * kind in a category - without it, every run's "red potion" would always be the same
+ * kind, and identifying one would identify them all forever. The mapping is drawn once
+ * per run (a seeded shuffle, so a run's seed fully determines it) and stays fixed until
+ * the run ends; revealing a kind's true nature stays the game's own `identify()` call,
+ * which keeps reading the mapping for the *unidentified* label only.
+ */
+export interface AppearanceTable {
+    /** the item kinds sharing one pool of looks, e.g. every potion kind */
+    kinds: readonly string[];
+    /** the distinct looks to deal out; must cover every kind, extras stay unused */
+    labels: readonly string[];
+}
+/**
+ * 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`.
+ */
+export declare function assignAppearances(table: AppearanceTable): Map<string, string>;
+export declare class Appearances {
+    private tables;
+    private assigned;
+    constructor(tables: Record<string, AppearanceTable>);
+    /** the look `kind` wears this run in `category`, drawing the shuffle on first ask */
+    appearanceOf(category: string, kind: string): string;
+    toJSON(): {
+        assigned: [string, [string, string][]][];
+    };
+    /** rebuilds appearances from save data - the tables themselves are supplied fresh, the same as `QuestLog` definitions */
+    static fromJSON(tables: Record<string, AppearanceTable>, data: {
+        assigned: [string, [string, string][]][];
+    }): Appearances;
+}
+//# sourceMappingURL=Appearances.d.ts.map

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

@@ -0,0 +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"}