🟦🟨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: 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/mwg; 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: every example below,
playable in the browser with no download, plus the generated API reference.
AI project prompt: a copy-ready prompt for
planning or porting a demanding game with mwg, with links to the mwg reference
and the mwg Pixel Dungeon study.
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 for open work, and
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/mwg supplies its own native shell:
tools.md
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 and
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 | generated dungeons, field of view, energy-cost turn scheduling, permadeath, dense inventory UI |
| ADOM | many persistent maps joined by a world map, hunger and long-running effects, skills and attributes, quests inside a roguelike |
| RPG Maker projects | hand-authored maps, events on tiles, dialogue and cutscenes, a party, menu combat, save slots |
| Pokémon, 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, 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 | hexagonal tactical maps, movement cost and defense by terrain, zone of control, turn-based unit combat with recruiting and upkeep |
| Flare's Empyrean Campaign | isometric tile maps, loaded straight from Tiled's own isometric export |
| Dungeon Crawl Stone Soup (Tiles) | a branching dungeon of many interconnected levels, and autoexplore pathing to the nearest unseen tile |
| Twine | 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 for rendering and rot.js
for the classic roguelike algorithms. Optional 3D scenes use Babylon.js. See
Capability spec.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
