@datamoc/mw_games 0.44.2 → 0.45.0

package/README.md

@@ -1,738 +1,11 @@
-# 🟦🟨mwg
+# @datamoc/mw_games
 
-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.
-
-The canonical npm package is `@datamoc/mw_games`; use that name for installation, imports,
-tools and bundled data such as `data/microgm-opt.sf2`. `@datamoc/mwg` remains a compatible
-re-export package for existing projects. The recipes here consistently use the canonical name.
-
-**[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.
-
-**[AI project prompt](https://datamoc.github.io/mwg/ai-prompt/)**: a copy-ready prompt for
-planning or porting a demanding game with mwg, with links to the [mwg reference](https://github.com/datamoc/mwg/blob/main/REFERENCE.md)
-and the [mwg Pixel Dungeon study](https://datamoc.github.io/mwg-pixel-dungeon/).
-
-> **Status: pre-alpha.** Every module in the shared floor below, plus optional
-> 3D, mobile (Capacitor) and desktop (WebView2) packaging, is built and tested - see
-> [ROADMAP.md](https://github.com/datamoc/mwg/blob/main/ROADMAP.md) for open work, and
-> [CLOSED.md](https://github.com/datamoc/mwg/blob/main/CLOSED.md) for the full, numbered shipped history.
-> The packaging scaffolding is part of this repository rather than the published package, so a
-> game that installs `@datamoc/mw_games` supplies its own native shell:
-> [tools.md](https://github.com/datamoc/mwg/blob/main/tools.md#packaging-as-a-native-app)
-> carries the recipe.
->
-> 0.4.0 was 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 was 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.
->
-> **Versioning:** `0.y.z` until 1.0, so the public API can still change between minor versions.
-> Each future major version is meant to carry a name, one per letter of the alphabet: 1.0 takes
-> a name beginning with A, 2.0 one beginning with B, and so on. None of the names are chosen
-> yet, and nothing depends on them until they are.
->
-> **API stability:** everything documented in [REFERENCE.md](https://github.com/datamoc/mwg/blob/main/REFERENCE.md) and
-> [API_REPORT.md](https://github.com/datamoc/mwg/blob/main/API_REPORT.md) is meant to be stable from 1.0 on. Anything that is not carries
-> an `@experimental` tag in its own doc comment, and is called out as experimental in the release
-> notes that introduce it, so it can still change or disappear without a major version. A rename
-> or a removal is deprecated first: the old name keeps working, its doc comment carries
-> `@deprecated` naming the replacement, and the release notes list it. 1.0 is the last release
-> where either can move silently.
-
-## 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:
+The former name of [`@datamoc/mwg`](https://www.npmjs.com/package/@datamoc/mwg).
 
 ```
-npm install @datamoc/mw_games pixi.js
+npm install @datamoc/mwg
 ```
-```ts
-import { Game, Scene } from '@datamoc/mw_games/core';
-import { Sprite } from '@datamoc/mw_games/two-d/render';
-```
-
-`pixi.js` is the 2D renderer, and it is an optional peer dependency rather than an installed
-one: a game that only uses `mwg/core`, `mwg/roguelike`, `mwg/actors`, `mwg/i18n` or the other
-logic modules never downloads it. Name it on the install line when a game draws, exactly as
-`@babylonjs/core` is named for 3D.
-
-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-<version>.tgz pixi.js
-```
-
-**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. The developer-side scripts behind this
-and the other workflows (translation editing, benchmarks, packaging) are listed in
-[tools.md](https://github.com/datamoc/mwg/blob/main/tools.md).
-
-A game built with its own bundler (Vite, say, rather than this repo's own `vite.lib.config.ts`
-IIFE) hits the same ES-module block on its own entry tag - a bundler's default output is
-`<script type="module" crossorigin src="...">`, which `file://` refuses the same way. Rather
-than every such game reinventing that one rewrite (item 306),
-`tools/classic-html.mjs`'s `toClassicScript(html)` does it: given the built page's HTML, it
-returns the same HTML with that tag rewritten to `<script defer src="...">`, or `null` when it
-finds no such tag - the guard against running it against an unbuilt dev template by mistake.
-The bundle itself still has to already be a classic script (an IIFE or UMD build, not further
-ES module output); this only rewrites the tag pointing at it.
-
-With Vite, none of that is by hand: `@datamoc/mw_games/tools/vite`'s `mwgPage()` plugin sets
-the classic-script configuration and, when `vite build` finishes, compiles `assets/`, rewrites
-the tag and precompresses the output (item 381). The same finishing step is `emitPage` from
-`@datamoc/mw_games/tools/emit-page`, or the `mwg-emit` command, for another bundler.
-`mwgPage({ singleFile: true })` (or `{ singleFile: { compress: true } }`) additionally writes one
-self-contained `standalone.html`. Plain `.ts` tests under `node --test` need a Node with type
-stripping (22.18 or later, or any build with `--experimental-strip-types`); otherwise run them
-through `tsx`.
-
-The finished page also carries a Content-Security-Policy, with nothing to configure (item 374):
-scripts only from its own folder and its own hashed inline scripts, no network request except to
-origins the game declares (`mwgPage({ csp: { connect: ['https://news.example'] } })`), and no
-image, font or media URL but `data:`/`blob:`. A compromised dependency can run, but cannot send
-a save or anything else off the machine. `'unsafe-eval'` stays allowed because Pixi 8 refuses
-to start without it unless a game imports `pixi.js/unsafe-eval` (then pass `csp: { eval: false }`).
-
-One consequence of `file://` a game has to design around: **Chromium gives every local page one
-shared `localStorage`**. Any other HTML file opened on the same machine can read a game's saves
-and settings, and rewrite them. mwg treats that storage as outside input (`SaveSystem.load`
-rejects a tampered slot rather than loading it, item 372), but no checksum can make it
-private or trustworthy, since the page that rewrites a save can recompute any checksum too. So
-never put a secret in a save or in settings (an account token, a password, a licence key), and
-treat a save as the player's own editable file, which it is.
-
-## Loading assets and input
-
-`await load(['vehicles/car.svg'], { resolution: 2 })` rasterizes SVG assets at twice
-their logical resolution, keeping them sharp when a camera zooms in. Import `load` from
-`@datamoc/mw_games/assets`. `loadSvgParts(path, { resolution: 2 })` loads top-level SVG
-groups as textures in their authored stacking order.
-
-Input events live under the `Input` namespace: import `{ Input }` from
-`@datamoc/mw_games/core` and subscribe with `Input.onAction.add(...)`. `onAction` is not a
-direct core export. `Input.attachPointer` supplies pointer and drag events for mouse and touch.
-
-## Audio
-
-Use `AudioBus` for one playback API across ordinary audio and MIDI assets. Its default
-loader reads embedded assets, detects MIDI by its header and renders it on a worker.
-`playBgm`/`playBgs` loop, while `playMe`/`playSe` play once; all take the same
-`{ name, volume, pitch, pan }` fields (volume 0-100, pitch 100 unchanged, pan -100 to 100).
-Pass `load: createAudioLoader(context, { midi: { soundFontBytes, missingProgram: 'synth' } })`
-to use a SoundFont. `Sound` remains useful for pooled HTML audio effects and `MusicPlayer`
-for a seekable jukebox.
-
-`Sound` pools short effects. `sound.play(0.7, 1.1)` sets gain and pitch for that play;
-`synthesizeSound({ waveform: 'sawtooth', frequency: 110, duration: 0.2 })` makes a pooled
-effect without an asset file. `Sound.plays` counts started playback attempts for browser tests.
-
-For MIDI music, copy the supplied `data/microgm-opt.sf2` from the installed package into
-your assets folder alongside the `.mid` files. `mwgPage({ assets: 'assets' })` automatically
-reduces the embedded SoundFont to the programs those MIDI files use. Load both through
-`loadBinary`, then render once on a worker and play the resulting buffer:
-
-For a smaller starting bank, `data/microgm-essential.sf2` supplies piano, guitar, violin,
-trumpet, flute and standard drums in 314 KB. Use it instead of the full bank below, with
-`missingProgram: 'synth'` for the remaining instruments. Both banks retain their WTFPL licence.
-
-```ts
-import { loadBinary, getBinary } from '@datamoc/mw_games/assets';
-import { MusicPlayer, renderMidiToBufferAsync } from '@datamoc/mw_games/audio';
-
-const player = new MusicPlayer(new AudioContext(), { volume: 0.7 });
-await loadBinary(['music/theme.mid', 'soundfonts/microgm-opt.sf2']);
-player.load(await renderMidiToBufferAsync(getBinary('music/theme.mid'), {
-  soundFontBytes: getBinary('soundfonts/microgm-opt.sf2'),
-  missingProgram: 'synth',
-}));
-player.play({ repeat: true });
-```
-
-Start playback from a player gesture. Call `player.update()` each frame to dispatch
-`onEnded` for a nonrepeating track; that signal lets the game choose its next track.
-`pause()`, `resume()`, `position()` and `seek(seconds)` share the same playhead.
-`toAudioBuffer(context, rendered)` also converts a render for direct `Channel` use.
-`missingProgram: 'synth'` voices instruments absent from the font with the built-in synth.
-
-To catch page growth, set `mwgPage({ maxPageBytes: 1_500_000 })`. Its build report lists
-embedded paths not found literally in the generated game script as potentially unused;
-paths assembled at runtime need manual review. `assetFiles` selects exact asset paths to embed.
-
-### Retro audio
-
-A retro-instrument package (an MT-32, OPL or chip synth of its own) plugs into mwg through
-contracts mwg owns, so the core never depends on the package. It registers a `MidiSynth`
-under a name with `registerMidiSynth('retro:mt32', factory)`; content then asks for that
-name and `resolveMidiSynth` walks the request, the SoundFont and the built-in synth in
-order, firing `onMidiSynthFallback` whenever a different engine ends up voicing the file.
-Endless or machine-code formats (NSF, SID, SPC) play through the streaming `Playable`
-contract (`StreamPlayable`, `StreamChannel`) under named decoder guards
-(`decoderLimits`, `DecodeBudgetError`): input ceilings, an instruction budget per second
-of sound, and bounded inflation, so untrusted files fail by name instead of hanging.
-Rendered tracks are budgeted (`TrackCache`, `createBudgetedLoader`): a five-minute stereo
-render is about 100 MB, so the bus caps decoded megabytes rather than keeping every track
-forever. Synthesised effects are data, not files: `SfxBank` builds them from definitions
-with a fixed seed, so audio never disturbs a lockstep simulation (its triggers are
-deterministic; the audio itself is not in the lockstep state, and A/V sync follows the
-game frame counter, not the wall clock). The `mwg-audio` tool inspects, converts, renders,
-budgets and compares these formats from the command line, and `spectralDistance` gives a
-first automated check between two renders. What no automation settles is whether a render
-sounds right: the A/B listening protocol in `docs/listening-protocol.md` is the place to
-record those verdicts.
-
-## 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** | frame loop (variable `dt`, clamped; `FixedStepper` for fixed simulation steps), 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` |
-| | declarative reactions to any state crossing a condition, in place of an `if` cascade | `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, markdown labels | `mwg/two-d/ui` |
-| | text and fonts, including non-latin fallback | PixiJS |
-| | modal single-line text entry, with validation and an on-screen keyboard for touch | `mwg/two-d/ui` |
-| | pointer, keyboard and gamepad input with rebinding | `mwg/core` |
-| **text** | message tables per language, compiled at build time | `mwg/i18n` |
-| | plurals, gendered forms, interpolation, and Python f-string-style format specs | `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` |
-| | per-message sound cues as an `audio` channel, plus inline `{sound:path}` markers for timed dialogue cues | `mwg/i18n` + `mwg/two-d/ui` |
-| **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.
-
-### Objects for behavior, data for content
-
-Content is data (above), but a game's *behavior* belongs in classes. A monster kept as
-loose scene fields works for one tutorial room and collapses for a dungeon: give it a
-class holding its state and the methods that change it, built on the framework's own
-bricks (`core.Scene` scenes, `actors.StatBlock` stats, `battle.Creature` opponents,
-`roguelike.Level` maps, `rpg.GridMover` movement, `core.EntityRegistry` identity).
-Subclass the brick that already owns the concern instead of reimplementing it beside an
-interface; no new base class is needed for ordinary actors.
-
-The boundary is where serialization starts. `simulation` commands survive
-`structuredClone`, `core.SaveSystem` stores JSON-serialisable state, and MWL rows are
-records by design, so classes stop where those begin: flatten at the boundary the way
-`rpg.GameState` does, and rebuild objects on load rather than storing them.
-
-### 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`.
-
-## Neural policies and UI-free training
-
-`ai.NeuralPolicy` runs small dense models without a runtime dependency. Policies
-share weights across agents, mask illegal actions and integrate with `JavaScriptAI`.
-`simulation.TrainingEnvironment` exposes seeded `reset`/`step` episodes over the same
-rules a game uses during play. Training runs at simulation speed in Node, with no
-canvas, DOM, audio or frame loop. `runRolloutsAsync` batches whole episodes across
-workers; model files bundle into the playable `file://` output.
-
-Try the generated courier task, whose optimizer belongs to the example:
-
-```sh
-npm run train:neural                         # train without any UI, export model and checkpoint
-npm run train:neural -- --resume --iterations 40
-npm run benchmark:neural                     # serial/parallel throughput and inference overhead
-npm run example:neural:build                 # open examples/neural/dist/index.html directly
-npm run neural:browser:check                 # workers, input latency and reset cancellation
-```
-
-Training checkpoints include environment state and randomness, model/schema
-versions and trainer state. Use small predictions directly when they fit the frame
-budget; worker startup and transfer costs pay off on larger simulation batches.
-
-## Maze chase AI example
-
-`examples/pacman` is a playable Pac-Man-style game with an original maze and drawn
-shapes. Switch the player between keyboard control, random turns, a path-and-risk
-heuristic and a trained neural policy. Ghosts independently select random turns,
-direct chase rules (`JavaScriptAI`), path heuristics (`HeuristicAI`) or `NeuralPolicy`.
-Selections take effect during the current game, preserving score and lives.
-
-Arrows or WASD steer; P and G cycle the player and ghost controllers; Space pauses;
-R starts a new game. Large dots make ghosts edible. The neural model uses UI-free
-imitation training from the heuristic, sharing the playable simulation rules.
-
-```sh
-npm run example:pacman                       # development server
-npm run example:pacman:build                 # open examples/pacman/dist/index.html directly
-npm run train:pacman                         # retrain and export weights without rendering
-npm run pacman:browser:check                 # selectors, WebGL, frame time and responsive layouts
-```
-
-## Roadmap
-
-See [ROADMAP.md](https://github.com/datamoc/mwg/blob/main/ROADMAP.md) for open work and
-[CLOSED.md](https://github.com/datamoc/mwg/blob/main/CLOSED.md) for the full, numbered build order and implementation notes.
-The optional 3D group is now implemented without changing the existing 2D entry point.
-
-## MWL
-
-MWL is the framework's declarative, WML-inspired authoring layer. Content files
-are JSON5: a top-level array of `{ tag, ...attributes, children }` nodes, with
-real numbers and booleans for scalar values and `_("...")` marking translatable
-strings. It describes game data and commands while `mwg` remains responsible for
-execution, rendering, input, audio, and saves. MWL is a new language, not a WML
-compatibility layer.
-Optional scene and UI composition is available through `@datamoc/mw_games/mwl/presentation`
-(build-time compiler) and `@datamoc/mw_games/two-d/presentation` (Pixi runtime). Compile
-reusable widgets, responsive layouts, keyed lists, semantic palettes and context overrides
-against a TypeScript binding manifest. The game supplies actions, physics and procedural
-adapters. See [the presentation contract](REFERENCE.md#mwl-presentation) and
-`examples/mwl-presentation`; `npm run visual:smoke:presentation` verifies the compiled
-`file://` page, keyboard/pointer input, modal windows, cleanup and update cost.
-The Wesnoth port can nevertheless use its native `.cfg` files as build inputs:
-the port-owned WML front end parses them, the adapter converts the supported
-nodes to MWL, and the normal MWL compiler emits the runtime module.
-
-The framework exposes the parser, validator, compiler, runtime, i18n extraction,
-and the hook contract through `@datamoc/mw_games/mwl`. Compile source at build
-time with:
-
-```sh
-npm run mwl -- validate game.mwl
-npm run mwl -- diagnostics game.mwl
-npm run mwl -- ci game.mwl
-npm run mwl -- format game.mwl -o generated/game.mwl
-npm run mwl -- migrate game.mwl --to 1.0 -o generated/game-1.0.mwl
-npm run mwl -- build game.mwl -o generated/
-npm run mwl -- compile game.mwl -o generated/game-data.ts
-npm run mwl -- extract-i18n game.mwl -o generated/i18n.json
-npm run mwl -- hooks game.mwl --manifest hooks.json -o generated/hooks.mjs
-```
-
-The input may also be a content directory. `mwl build content/ -o generated/`
-reads every `.mwl` file recursively in stable path order and emits one merged,
-validated catalog. Diagnostics retain each source file and line, so a game can
-organize campaigns, assets, units, items, scenarios, dialogue, and AI data as separate files.
-
-`mwl build` is the normal game command: it produces `game-data.ts`, `i18n.json`,
-and `assets.json` in one build-time step. The game imports the generated module;
-it never calls `Mwl.compile()` at runtime. MWG also provides generic helpers for
-turning item effects into `actors` modifiers and for versioned, migratable MWL
-saves. Asset attributes such as `image`, `image_icon`, `profile`, `icon`, `file`,
-`sound`, and `*_sound` are collected into the manifest, including comma-separated
-sound lists, Wesnoth sound ranges such as `human-hit-[1~5].ogg`, and image
-modifiers. Nested transform arguments are not mistaken for separate assets.
-Item slots, formulas, hooks, and business rules remain defined by the game.
-`[item]` itself carries `image`/`icon` (item 307), so an inventory item can author its own
-sprite or icon the same way `[monster]`/`[unit_type]`/`[object]`/`[story]` already could; the
-manifest scanner recognised these names on any node before the schema let `[item]` use them,
-so this only closes that one gate rather than adding new asset-collection behaviour.
-
-A game needing more than `mwl build`'s three standard files - its own extra generated module,
-or a cross-table check this CLI has no flag for - should not look for a flag to add: every
-function that command calls (`compileSources`, `emitArtifacts`, `validateCatalog`,
-`contentReport`) is public from `@datamoc/mw_games/mwl`, so that game's own small Node build
-script, written against the same library API `tools/mwl.mjs` itself uses, is the extension
-point (item 305).
-
-Campaign metadata can be authored with a `[campaign]` tag inside `[game]`. It requires an
-`id` and accepts `name`, `title`, `description`, and `start_scene`; scenario and extension
-children remain game-owned and are preserved by the compiler. The compiled metadata is
-available as `contentCatalog(game).campaigns`.
-
-For a large self-contained HTML page, `npm run extract:html -- page.html -o extracted/`
-writes a rewritten `index.html`, an `assets/` directory, and a deterministic
-`manifest.json`. Inline scripts, styles, and supported `data:` URLs are extracted in
-source order. The original page is never overwritten, and unsupported data forms are
-reported as warnings. The output directory is safe to regenerate: its extracted
-`assets/` directory is replaced, while unrelated files are kept.
-CSS `url(data:...)` values and HTML `srcset` candidates are handled too, including
-their density descriptors.
-
-Translation messages are the values marked `_("...")` in the source; the
-extracted catalog matches `@datamoc/mw_games/i18n`. Hooks are referenced as
-`type:name`, declared in a manifest, and bundled with esbuild, which a game
-project installs itself (`npm install --save-dev esbuild`). The framework does
-not depend on esbuild, so a game without hooks pays nothing for the feature.
-
-`MwlRuntime` runs compiled content: it loads the map, sides, units, and leaders
-(leaders spawn on their keep with stats from `[unit_type]`), runs `on=` events
-with filters and conditions, tracks movement points, advances the `[schedule]`
-on `[end_turn]`, evaluates `[objectives]`, hosts command and predicate hooks,
-and saves and restores the world. Pathfinding and combat formulas stay in a
-game's engine adapter, because they need that game's real data. A command hook
-receives the `[hook]` attributes as its context; a `condition=hook` objective
-receives its other attributes, so content can parameterize an engine predicate
-(`value` is the generic integer parameter).
-
-Events trigger on `start`, `turn`, and `moveto`. A `moveto` event fires when a
-unit arrives on a hex, filtered by `x`, `y`, `unit` and `side`, once by default
-(and a spent one-shot stays spent across save/restore). A game whose own engine
-resolves movement writes the new position into the world and calls
-`runtime.fireMoveto(unitId)`, so the trigger works either way. A `[message]`
-becomes an `MwlMessage` with its `text`, and its `speaker`, `portrait` and `side`
-when the content gives them, which is enough for a real dialogue box instead of a
-log line.
-
-Dialogue choices are exposed through `MwlMessage.choices` and answered with
-`runtime.answerDialogue(dialogueId, choiceIndex)`. Pending choices are part of the
-saved world. Commands after a dialogue in the same event run immediately, before
-the player answers, so deferred follow-up commands belong in the event named by
-the selected choice. Events can also be invoked directly with `runtime.fireEvent(id)`;
-moveto coordinates accept comma lists and inclusive ranges such as `1,3-5`.
-
-The generated data is plain TypeScript and works with the same local-file build
-pipeline as the rest of the framework. Wesnoth-specific MWL source belongs in
-the Wesnoth port, not in this framework package.
-
-## Powered by mwg
-
-Games built with mwg are welcome to carry the badge on their login screen:
-
-[![powered by mwg](webpage/assets/powered-by-mwg.svg)](https://datamoc.github.io/mwg/)
-
-Copy `webpage/assets/powered-by-mwg.svg` into your own project (a shipped game
-cannot fetch it from here; local-file pages only load their own assets) and link
-it to the framework site. In plain HTML that is:
-
-```html
-<a href="https://datamoc.github.io/mwg/">
-  <img src="./powered-by-mwg.svg" alt="powered by mwg" width="196" height="38">
-</a>
-```
-
-A canvas-drawn login screen loads the same file through the asset pipeline and
-opens the URL on click with `window.open('https://datamoc.github.io/mwg/', '_blank')`.
-
-## 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.
+New projects install the main name above; this package only forwards to it.
 
-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.
+`import { Game } from '@datamoc/mw_games/two-d'` is the same module as `import { Game } from '@datamoc/mwg/two-d'`. The `mwg-*` command line tools are installed by `@datamoc/mwg`; run them with `npx -p @datamoc/mwg mwg-emit`. Documentation: https://datamoc.github.io/mwg/