A solo tabletop RPG engine. Dice, oracles, decks, random tables and map tiles, built so that an AI game master can run a game without inventing the dice.
Nothing here calls a language model. It is all deterministic generation that an agent — or an app, or a person at a terminal — uses. That is the point: a roll that came from a tool can be logged, cited and audited, and a roll that did not can be spotted.
Status: early. The library is being extracted from a working pi extension. Dice, map tiles, dungeon generation, visibility, decks, tables and the oracle have landed. Character sheets and campaign state are next, then the pi extension and the CLI.
| Package | Directory | What it is |
|---|---|---|
@portents/core |
packages/core/ |
The engine. Runs in Node and the browser. |
@portents/content |
packages/content/ |
Batteries included: generic plus common systems. |
@portents/content-generic |
packages/content-generic/ |
The generic fallback every other pack overrides. |
@portents/cli |
packages/cli/ |
portents roll, portents map, and friends. |
@portents/pi |
packages/pi/ |
Runs a game inside the pi coding agent. |
@portents/content-dnd |
packages/content-dnd/ |
Fifth edition, both printings. SRD material under CC-BY-4.0. |
@portents/content-pf |
packages/content-pf/ |
Pathfinder-style systems, three printings. Original writing. |
@portents/setting-greywater |
packages/setting-greywater/ |
Small original setting proving Markdown resources and raster maps with pins. |
@portents/web |
packages/web/ |
Browser/edge session facade. Storage injected. No UI. |
@portents/room |
packages/room/ |
Experimental in-process response coordination. Not a multiplayer server. |
Content is a separate package from the engine because content is the part people will want to fork, extend and version independently. The engine knows how to parse, validate and render tiles; it ships none of them.
Honest dice. Every random result comes from a seeded or crypto-backed source
and can be recorded with an id. A game master that must cite r-3f9a for a
number cannot quietly invent one, and an id absent from the ledger is evidence.
One tile, two projections. A map tile is authored as ASCII art. That art is parsed once into a grid, and both the text and the vector renderings read that same grid — so they cannot describe different tiles. The equivalence is checked, not promised:
###+### the same tile, rendered as SVG, is verified cell by cell
#.....# against this text: same coordinates, same kinds, and each
#.O.O.# cell drawing the symbol its kind is supposed to use
+.....+
#.O.O.#
#.....#
###+###
Adding a cell kind is one row in the registry plus one shape. Forgetting the shape is a compile error, a duplicate glyph throws on import, and exits are derived from the art so a tile cannot claim a door it does not draw.
Tiles are 7×7, doors always centred. One size, one connector position per
edge, enforced by standardTileProblems. That is what lets tiles be laid on a
lattice and simply fit, with no edge-matching logic:
const map = composeTiles([[hall, corridor, room], [corridor, null, stair]]);
renderAscii(map); // the whole dungeon as text
renderSvg(map); // the same dungeon as vectorsA composed map is itself a Tile, so both projections work on a dungeon
unchanged and the equivalence guarantee comes with them. Where one tile has a
door and its neighbour has wall, the seam is sealed — an assembled map never
shows an exit into solid rock.
Dungeons are generated connectivity-first. A randomised depth-first walk carves a spanning tree over the lattice, so every cell is reachable before any tile is chosen; each cell then has a required shape and a tile is picked to match. Most tile generators place a tile and then hunt for neighbours that fit, which paints itself into corners and leaves disconnected fragments.
const { map, entrances } = generateDungeon(tiles, { cols: 5, rows: 4, seed: "grimhold" });A connection shape is four bits, so there are sixteen. With rotation, one authored tile per shape class — dead end, straight, bend, T, cross — covers all of them, so a small hand-written set generates every layout.
Sight is modelled properly. Recursive shadowcasting over eight octants, so you can see past a pillar on both sides but not through it, and from a doorway you see the room beyond but not along the wall you stand in. Opacity is separate from passability, because a chasm blocks movement but not sight and a closed door does the reverse.
let view = withActors(createView(map, { sightRadius: 8 }), party);
view = moveActor(view, "brannoc", { x: 5, y: 12 });
renderSvg(map, {
visibility: { visible: view.visible, explored: view.explored },
tokens: view.actors,
viewport: { x: 0, y: 0, width: 13, height: 7 },
});Three states: unknown is not drawn at all, so the players' map cannot leak the shape of a room they have never entered; explored is dimmed; visible is drawn with tokens. Terrain is remembered, creatures are not — a goblin does not stay where you last saw it.
pnpm install
pnpm check # typecheck, test, and bundle for the browser
pnpm manual # build the manual-check page, then open manual/index.htmlimport { roll, formatRoll, parseTileSet, renderAscii, renderSvg, exitsOf } from "@portents/core";
import { dungeonTiles } from "@portents/content";
formatRoll(roll("2d20kh1+5")); // advantage
formatRoll(roll("6#4d6kh3")); // six ability scores in one call
formatRoll(roll("floor((2d6+3)/2)")); // real arithmetic
const [tile] = parseTileSet(dungeonTiles);
renderAscii(tile); // the text
renderSvg(tile); // "<svg …>" — the same tile
exitsOf(tile); // derived from the art, never declaredDice notation follows Foundry VTT: 4d6kh3, 2d20kl1, 1d6x, 4d6r1,
1d20min10, 5d10cs>=7, d%, 4dF, floor((2d6+3)/2)*2, 8d6 # fireball,
and a leading 6# to repeat. Full table in packages/core/README.md.
import { createRegistry, rollTableById, yesNo, sceneCheck, createPile, drawFromPile } from "@portents/core";
import { genericContent } from "@portents/content";
const registry = createRegistry([genericContent]);
sceneCheck({ registry }); // as expected, skewed, or interrupted
rollTableById("encounters-dungeon", { registry });
yesNo("Is the portcullis still up?", "unlikely", { registry });
let pile = createPile(registry.requireDeck("crit-hits"));
const { cards, pile: next } = drawFromPile(deck, pile); // the pile is yours to persistTable entries compose, so one roll can do a lot of work:
{{table:names-dwarf}}, {{roll:2d6}}, {{pick:north|south}}, {{deck:npc-sparks}}.
The oracle is the part that makes solo play work. At a table the GM is surprised too; alone, the temptation is to decide whatever suits the story, and then nobody is playing. The likelihood ladder and the doubles-mean-a-twist rule are original arithmetic, not a reproduction of any published solo system.
portents roll 2d20kh1+5 --dc 15
portents map --rooms 9 --seed grimhold --png map.png
portents oracle "is the gate still guarded?" --likelihood unlikelyEvery command takes --json for scripting and --seed for reproducibility. See
packages/cli/README.md.
$PORTENTS_HOME, or ~/.portents by default. Campaign files, character sheets and
maps are markdown you can read, edit and put in git.
Character sheets keep their machine-readable values in frontmatter and their prose generated from it, so the file serves a parser and a person without the two drifting apart. Generated sections are marked, and a hand-edit that puts them out of sync is reported rather than silently resolved.
Setting context and campaign memory use the same human-first rule at a smaller scale:
one Markdown file per NPC, place, faction, thread, ruling, or other topic under
world/<kind>/<slug>.md. A versioned frontmatter envelope supplies stable ids, aliases,
tags, links, and visibility. portents_recall loads only the relevant topics;
portents_remember writes one back. The older monolithic world.md remains readable.
The engine is synchronous and depends on nothing but interfaces in
packages/core/src/ports. Persistence is the one asynchronous seam, because IndexedDB
cannot be synchronous:
@portents/core pure engine + port interfaces, no platform code
@portents/core/memory in-memory Storage (reference implementation)
@portents/core/node filesystem Storage, the only file importing node:*
@portents/core/browser IndexedDB Storage
@portents/core/testing the Storage conformance suite, so your adapter can prove itself
Three mechanisms keep that honest rather than aspirational:
packages/core/src/isomorphism.test.tsscans every source file and fails on anode:import,process,Buffer, or a DOM global outside the two platform adapters. The rule is symmetrical —documentbreaks Node exactly asnode:fsbreaks the browser.pnpm check:browserbundles every browser-facing entry point with esbuild, no polyfills and no aliases, and exits non-zero if anything Node-only leaks in.- Both bundled Storage adapters run the same published conformance suite, so they cannot drift apart.
The IndexedDB adapter is now covered. It used to be a known gap, because Node
has no IndexedDB. packages/web supplies one with fake-indexeddb and runs the
same published conformance suite against BrowserStorage that the Node and
memory adapters pass -- all 22 cases, plus checks that a fresh handle to the same
database sees the earlier writes. The polyfill is a dev dependency of web, not
of core, so nothing ships to make a test possible.
One gap remains: the browser PNG rasteriser. svgToPngBlob needs a canvas,
which Node does not have, so it is exercised only by the manual page. Treat it as
unproven. The CLI rasterises through @resvg/resvg-js instead and is tested.
Some things a test suite cannot judge. The automated tests prove the SVG and the ASCII describe the same grid, cell for cell; they cannot tell you whether a door looks like a door.
pnpm manual # bundles lib + content, no build of either needed
open manual/index.htmlSeven sections, each checking something a test cannot judge:
- A generated dungeon as SVG beside fixed-width ASCII, with seed, size, loop and gap controls. It re-derives both projections in the browser and reports whether they agree.
- Fog of war — click a cell to move the party there. This is the best way to check the field of view: stand beside a pillar, stand in a doorway, walk into a room and back out.
- PNG, rasterised in the browser, which should be indistinguishable from the SVG above it.
- A range of tiles, cropped, for handing a player one room at a time.
- Every cell kind with its glyph, shape, and movement/sight properties.
- Every tile in the pack in both projections, with its connection shape.
- Dice formatting.
If a picture and its text ever disagree there, that is a real bug — the test suite believes they match.
Bundled content — tiles, and the decks and tables to come — is original writing, CC0, with provenance metadata on every pack. Nothing is reproduced from a published solo system, crit deck or rulebook.
Portents supports D&D 5E and Pathfinder 2E. It is not affiliated with, endorsed by, or derived from Wizards of the Coast or Paizo, and it contains no rules text from either.
Code is MIT. See LICENSE.
There is no contribution process yet; the API is still moving. If you want to
add a tile set or a content pack, the formats are documented in
packages/core/README.md and the tests will tell you what you got wrong.