@datamoc/mw_games 0.3.1 → 0.4.1

package/README.md

@@ -1,395 +1,401 @@
-# 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.
-
-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 release (v0.3.1).** 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.
-
-## 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. Optional 3D scenes use Babylon.js. 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` |
-| | 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` |
-| | 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` |
-| field of view and pathfinding over a hex grid, not just square | `mwg/roguelike` |
-| isometric (and staggered) projection, alongside orthogonal and hex | `mwg/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` |
-
-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.
-
-## Optional Babylon.js 3D
-
-`@babylonjs/core`/`@babylonjs/loaders` are peer dependencies, not installed automatically -
-a game that never imports `mwg/3d` never downloads Babylon.js. Add them yourself
-(`npm install @babylonjs/core @babylonjs/loaders`) once a game imports 3D support:
-
-```ts
-import { Engine3D, createTileGrid3D } from '@datamoc/mw_games/3d';
-import { loadModel3D } from '@datamoc/mw_games/3d/models';
-```
-
-`Engine3D` owns a WebGL scene, orbit camera, light, resize handling, and render loop.
-`createTileGrid3D` batches square or flat-top hex tiles and elevation columns with thin
-instances; `createHeightmapTerrain3D` builds continuous terrain from decoded RGBA heightmap
-pixels. `Character3D` moves imported meshes or camera-facing sprites continuously, and can
-play imported animation clips. `parseVox` and `createVoxModel3D` load one MagicaVoxel model;
-`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.
-The optional 3D group is now implemented without changing the existing 2D entry point.
-
-## Licence and provenance
-
-`mwg` is MPL-2.0. Its dependencies are permissive and compatible: PixiJS and Babylon.js are
-MIT, and 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` includes none of their runtimes, assets, text or data tables: no
-type chart, no species list, no stat formula, no map, no line of dialogue. Those are each
-game's own design work. A loader or writer for one of their file formats is a different
-matter and is not off limits on its own: a format is a container, understood the same way
-any published format is, by reading real files in it to learn its shape; what stays out is
-the media that container holds, someone else's actual assets, text or data tables. Where a
-format already exists and needs no reverse-engineering, `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.
+# mwg
+
+A framework for building tile games that run **from a local file**: no server, no install,
+no runtime to download. The game logic depends on no renderer at all, so a game draws through
+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.
+
+**[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.4.1).** 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.
+>
+> 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
+
+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. Optional 3D scenes use Babylon.js. 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/two-d/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/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/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` |
+
+### 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/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/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` |
+
+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/two-d/ui` |
+| grid movement tweened between tiles, with a walk cycle | `mwg/rpg` |
+| 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
+
+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/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
+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/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
+
+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/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
+  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.
+
+## Optional Babylon.js 3D
+
+`@babylonjs/core`/`@babylonjs/loaders` are peer dependencies, not installed automatically -
+a game that never imports `mwg/3d` never downloads Babylon.js. Add them yourself
+(`npm install @babylonjs/core @babylonjs/loaders`) once a game imports 3D support:
+
+```ts
+import { Engine3D, createTileGrid3D } from '@datamoc/mw_games/3d';
+import { loadModel3D } from '@datamoc/mw_games/3d/models';
+```
+
+`Engine3D` owns a WebGL scene, orbit camera, light, resize handling, and render loop.
+`createTileGrid3D` batches square or flat-top hex tiles and elevation columns with thin
+instances; `createHeightmapTerrain3D` builds continuous terrain from decoded RGBA heightmap
+pixels. `Character3D` moves imported meshes or camera-facing sprites continuously, and can
+play imported animation clips. `parseVox` and `createVoxModel3D` load one MagicaVoxel model;
+`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.
+The optional 3D group is now implemented without changing the existing 2D entry point.
+
+## Licence and provenance
+
+`mwg` is MPL-2.0. Its dependencies are permissive and compatible: PixiJS and Babylon.js are
+MIT, and 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` includes none of their runtimes, assets, text or data tables: no
+type chart, no species list, no stat formula, no map, no line of dialogue. Those are each
+game's own design work. A loader or writer for one of their file formats is a different
+matter and is not off limits on its own: a format is a container, understood the same way
+any published format is, by reading real files in it to learn its shape; what stays out is
+the media that container holds, someone else's actual assets, text or data tables. Where a
+format already exists and needs no reverse-engineering, `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.