RPG world

The pack

rpgWorld

function rpgWorld(): Pack<{ rpgWorld: typeof api }>

Install the rpg-world API (game.rpgWorld): the world document, its cleaner and its map generators.

Helpers

BIOME_RULES

const BIOME_RULES: Readonly<Record<string, BiomeRule>>

The built-in biomes' rules.

BIOMES

const BIOMES: readonly ["grassland", "forest", "mountain", "desert", "swamp", "tundra", "volcanic", "coast"]

The built-in biomes; a biome sets the terrain of its part of the overworld (see worldMaps' biome rules).

cleanStats

const cleanStats = (v: unknown, base: Stats): Stats=> …

Stats from anything stat-shaped: each field rounded and clamped to its range, with base filling any that are missing or not numbers.

cleanWorld

function cleanWorld(raw: unknown, options: WorldOptions | WorldVocabulary = {}): World

Anything world-shaped in, a valid world out. References are cut when they point at nothing; unknown names fall to defaults; every list is capped. options sets the caps and the vocabularies (see WorldOptions).

DIFFICULTIES

const DIFFICULTIES: readonly ["gentle", "fair", "cruel"]

The built-in difficulty settings (a rules pack scales monsters by them: turn-battle's gentle x0.8, cruel x1.25).

DT

const DT: { readonly wall: 0; readonly floor: 1; readonly door: 2; readonly stairsUp: 3; readonly stairsDown: 4; readonly chest: 5; }

Dungeon tile ids by name.

DUNGEON_TERRAIN

const DUNGEON_TERRAIN: readonly DungeonTerrainDef[]

The dungeon tile table, indexed by id.

DUNGEON_THEMES

const DUNGEON_THEMES: readonly ["crypt", "ruin", "mine", "ice-cave", "clockwork", "manor", "temple", "volcano", "warren", "stronghold"]

The built-in dungeon themes; a theme sets how a game dresses a dungeon's floors (its colours and tiles).

ELEMENT_BEATS

const ELEMENT_BEATS: Readonly<Record<string, string | null>>

The built-in wheel: what each element BEATS (a rules pack decides what beating does; turn-battle deals 1.5x and breaks a shield point).

ELEMENTS

const ELEMENTS: readonly ["none", "fire", "ice", "lightning", "earth"]

The built-in elements: none is physical, and the wheel ELEMENT_BEATS runs fire > ice > lightning > earth > fire.

emptyRules

const emptyRules = (): Rules=> …

The default rules a world is played by.

emptyStory

const emptyStory = (acts = 3): Story=> …

A story with every text empty, acts untitled acts (default 3) and no villain monster.

emptyWorld

const emptyWorld = (): World=> …

A world with no content and the default rules; cleanWorld of nothing returns something equivalent.

HERO_BASE

const HERO_BASE: Readonly<Record<string, Stats>>

Level-1 stats for each built-in hero class, used when a hero's own stats are missing.

HERO_CLASSES

const HERO_CLASSES: readonly ["striker", "guardian", "caster", "trickster"]

The built-in hero classes; a class gives a hero base stats (HERO_BASE) when the world writes none.

ITEM_EFFECTS

const ITEM_EFFECTS: readonly ["heal", "mp", "cure", "revive", "rest"]

The built-in consumable effects: heal HP, restore MP, cure, revive a downed hero, or rest (fill HP and MP).

ITEM_KINDS

const ITEM_KINDS: readonly ["weapon", "armor", "accessory", "consumable", "key", "quest"]

The built-in item kinds: weapon, armor and accessory are worn; a consumable is used up; keys and quest items are only carried.

LENSES

const LENSES: readonly ["top-down", "first-person"]

How a dungeon is seen. The overworld and towns are always top-down.

MONSTER_BASE

const MONSTER_BASE: Stats

Stats used for a monster whose own stats are missing.

NPC_ROLES

const NPC_ROLES: readonly ["quest-giver", "merchant", "innkeeper", "companion", "rival", "gatekeeper", "victim", "villager", "villain"]

The built-in roles a non-player character can have in a town or a quest.

QUEST_SHAPES

const QUEST_SHAPES: readonly ["fetch", "kill", "escort", "deliver", "investigate", "rescue", "repair", "race", "guard", "trade", "choose", "return"]

The built-in quest shapes: a label for the story; the quest's steps decide what the player must do.

SKILL_EFFECTS

const SKILL_EFFECTS: readonly ["damage", "heal", "guard", "haste"]

The built-in skill effects: deal damage, heal, guard (defend) or haste (act sooner).

SKILL_TARGETS

const SKILL_TARGETS: readonly ["one", "all", "ally", "party", "self"]

Who a skill can aim at: one enemy, all enemies, one ally, the whole party, or the user.

startRegion

const startRegion = (w: World): Region | null=> …

Where the game starts: the first act-1 region with a town, else the first region with a town, else the first region.

STEP_KINDS

const STEP_KINDS: readonly ["talk", "kill", "fetch", "reach", "deliver"]

The built-in step kinds.

STEP_TARGETS

const STEP_TARGETS: Readonly<Record<string, StepTarget>>

The built-in step kinds and what each one's target is: talk to an npc, kill monsters, fetch items, reach a region, deliver to an npc.

T

const T: { readonly sea: 0; readonly shallows: 1; readonly grass: 2; readonly meadow: 3; readonly trees: 4; readonly glade: 5; readonly hills: 6; readonly peak: 7; readonly sand: 8; readonly dune: 9; readonly marsh: 10; readonly bog: 11; readonly snow: 12; readonly ice: 13; readonly ash: 14; readonly lava: 15; readonly rock: 16; readonly road: 17; readonly town: 18; readonly dungeon: 19; }

Terrain ids by name, for code that would rather not count.

TERRAIN

const TERRAIN: readonly TerrainDef[]

The overworld tile table, indexed by id.

terrainEncounter

const terrainEncounter = (id: number, table: readonly TerrainDef[] = TERRAIN): boolean=> …

True when the overworld terrain id has random encounters in table (default TERRAIN).

terrainWalkable

const terrainWalkable = (id: number, table: readonly TerrainDef[] = TERRAIN): boolean=> …

True when the overworld terrain id is walkable in table (default TERRAIN; pass maps.terrain for a world built with extra terrain).

TOWN_LAYOUT_RULES

const TOWN_LAYOUT_RULES: Readonly<Record<string, TownLayoutRule>>

The built-in town templates.

TOWN_LAYOUTS

const TOWN_LAYOUTS: readonly ["village", "harbor", "fort", "city", "shrine", "crossroads"]

The built-in town layouts; each is a template the town generator lays out from the town's seed.

TOWN_TERRAIN

const TOWN_TERRAIN: readonly TownTerrainDef[]

The town tile table, indexed by id.

TT

const TT: { readonly grass: 0; readonly path: 1; readonly house: 2; readonly door: 3; readonly water: 4; readonly dock: 5; readonly well: 6; readonly wall: 7; readonly plaza: 8; readonly stone: 9; readonly tree: 10; readonly fence: 11; readonly roof: 12; readonly gate: 13; }

Town tile ids by name.

WORLD_LIMITS

const WORLD_LIMITS: { readonly regions: 8; readonly heroes: 6; readonly npcs: 40; readonly monsters: 32; readonly items: 48; readonly skills: 24; readonly quests: 24; readonly steps: 6; readonly lines: 4; readonly beats: 4; ... 11 more ...; readonly name: 48; } …

The default caps cleanWorld applies: how many of each thing a world holds and how long text may be. Counts: regions, heroes, npcs, monsters, items, skills, quests; steps per quest, lines per npc, beats per act, shop items per town, floors per dungeon, dungeonMonsters kinds per dungeon, heroSkills per hero, breaks shield points per monster, count per quest step, acts in the story, party (the largest partySize) and level (the largest maxLevel). Text, in characters: line, para, name.

worldMaps

function worldMaps(world: World, options: MapOptions = {}): WorldMaps

Every map a world needs, deterministic from its seeds. Pass a CLEAN world (cleanWorld). options adds biomes, town templates and terrain, and sizes the overworld and the dungeon floors.

worldPlayable

function worldPlayable(w: World): string[]

What stops a world being played: no regions, no start, no heroes, no monsters. Empty when it can be played.

worldVocabulary

function worldVocabulary(o: WorldOptions = {}): WorldVocabulary

Fill in WorldOptions' defaults. Throws on an empty vocabulary or a wheel that names an element it does not list.

Types

Act

interface Act

One of the story's acts.

• title: string — The act's title, at most limits.name characters. Default Act 1, Act 2 and so on.
• beats: string[] — Up to limits.beats beats: what happens, in order.

Biome

type Biome = string

A region's biome: one of the options' biomes (default BIOMES).

BiomeRule

interface BiomeRule

How a biome fills its part of the overworld.

• base: number — The walkable terrain id cleared around a town or dungeon entrance.
• tile(noise: number, edge: number, rough: number): number — The terrain id of one cell: noise is smooth noise in about -1..1, edge the cell's distance from the map's edge in cells, rough a second, coarser noise in about -1..1.

Cell

interface Cell

A grid cell.

• col: number — Column.
• row: number — Row.

Difficulty

type Difficulty = string

The world's difficulty: one of the options' difficulties (default DIFFICULTIES).

Dungeon

interface Dungeon

A dungeon in a region: floors generated from its seed and dressed by its theme.

• name: string — The dungeon's name. Default Dungeon.
• theme: DungeonTheme — How its floors are dressed: one of the options' dungeonThemes.
• floors: number — Number of floors, 1 to limits.floors. Default 2.
• seed: number — Seed for the level generator, a whole number from 0 to 2^31. Default 1.
• lens: Lens — How it is seen. Default the world's rules.lens.
• monsterIds: string[] — What roams it, at most limits.dungeonMonsters kinds.
• bossId: string | null — The fight at the bottom, if any.
• findItemId: string | null — The item found only here, placed on the last floor.
• lore: string — Its history.

DungeonFloor

interface DungeonFloor

One floor of a dungeon.

• cols: number — Columns.
• rows: number — Rows.
• tiles: Uint8Array — Dungeon tile ids, row-major; look them up in DUNGEON_TERRAIN.
• rooms: DungeonRoom[] — The rooms, from the level generator.
• up: Cell — The stairs up (the entrance on floor 0).
• down: Cell | null — The stairs down, or null on the last floor.
• boss: Cell | null — The boss's cell on the last floor, or null.
• chest: Cell | null — The chest holding the dungeon's find, or null.
• monsters: MonsterPlacement[] — Every monster on the floor at the start, the boss included.

DungeonMap

interface DungeonMap

A dungeon: its floors and how it is seen.

• regionId: string — The region the dungeon belongs to.
• theme: DungeonTheme — The theme, for colours.
• lens: Lens — Top-down or first-person.
• floors: DungeonFloor[] — The floors, top first.

DungeonOptions

interface DungeonOptions

How the dungeon floors are made.

• size?: (floor: number, floors: number) => { cols: number; rows: number } — A floor's size; default 34 + 6 x floor columns by 24 + 3 x floor rows.
• maxRoom?: number — The largest room side, in cells. Default 8.
• extraConnections?: (floor: number) => number — Loops added beyond a spanning tree of corridors; default 2 + floor.
• monsters?: readonly [number, number] — How many roaming monsters a floor has, inclusive. Default [4, 8].

DungeonTerrainDef

interface DungeonTerrainDef

A tile kind inside a dungeon.

• id: number — The id stored in DungeonFloor.tiles.
• name: string — A short name.
• color: string — A CSS hex colour.
• walkable: boolean — Can the party step on it.

DungeonTheme

type DungeonTheme = string

A dungeon's theme: one of the options' dungeonThemes (default DUNGEON_THEMES).

Element

type Element = string

An element: none, or one of the options' elements (default the built-in wheel).

Entrance

interface Entrance extends Cell

A town or dungeon entrance on the overworld.

• regionId: string — The region it belongs to.
• kind: 'town' | 'dungeon' — What it opens into.

Hero

interface Hero

A playable hero.

• id: string — Unique among the heroes; what the run's party and equipment refer to.
• name: string — The hero's name.
• class: HeroClass — The class: one of the options' classes, which gives the base stats if none are written.
• look: string — How they look, one line, for the portrait and the figure.
• bio: string — Who they are, one or two lines.
• stats: Stats — Level-1 stats.
• skillIds: string[] — Ids of the skills the hero knows, at most limits.heroSkills; ids that match no skill are dropped.
• joinAt: string — start, or the region where they join.
• portraitId: string | null — Id of the hero's picture in the asset map handed to the player, or null for none.

HeroClass

type HeroClass = string

A hero's class: one of the options' classes (default HERO_BASE's).

Item

interface Item

An item: gear, a consumable, a key or a quest object.

• id: string — Unique among the items; what shops, drops, rewards and quest steps refer to.
• name: string — The item's name.
• kind: ItemKind — What it is: one of the options' itemKinds. A kind that names an equipment slot is worn there.
• tier: number — How good it is, 1 to 3.
• element: Element — For a weapon, the element of the wielder's attacks; none for physical.
• bonus: Partial<Stats> — Stat changes while it is worn, each -99 to 999; a stat left out is unchanged.
• effect: ItemEffect | null — For a consumable, what it does (one of the options' itemEffects); null for anything else.
• power: number — The effect's strength: HP healed, MP restored, HP on revival. 0 to 999.
• price: number — Gold price in a shop, 0 to 99999.
• blurb: string — One line describing it.

ItemEffect

type ItemEffect = string

A consumable's effect: one of the options' itemEffects (default ITEM_EFFECTS).

ItemKind

type ItemKind = string

An item's kind: one of the options' itemKinds (default ITEM_KINDS). A game with other equipment slots names them here.

Lens

type Lens = (typeof LENSES)[number]

A dungeon's lens: one of LENSES.

MapOptions

interface MapOptions

What worldMaps may be told.

• terrain?: readonly TerrainDef[] — Overworld terrain beyond TERRAIN, with ids continuing from TERRAIN.length, for biome rules of a game's own.
• biomes?: Readonly<Record<string, BiomeRule>> — Biome rules, over BIOME_RULES. A biome the world names with no rule fills as grassland.
• townLayouts?: Readonly<Record<string, TownLayoutRule>> — Town templates, over TOWN_LAYOUT_RULES. A layout with no template builds as a village.
• cols?: number | ((regions: number) => number) — The overworld's columns, or a function of the region count. Default 72 + 8 per region, held to 96..128.
• aspect?: number — The overworld's rows as a fraction of its columns. Default 2/3.
• dungeon?: DungeonOptions — The dungeon floors.

Monster

interface Monster

A kind of monster, met in battle.

• id: string — Unique among the monsters; what dungeons, quests and the villain refer to.
• name: string — The monster's name.
• element: Element — The element it attacks with and defends as; the wheel makes some elements weak against it.
• stats: Stats — Its stats, before the world's difficulty scales them.
• boss: boolean — Whether it is a boss: it always leaves its drop and, by default, has more shield points.
• breaks: number — Shield points, 0 to limits.breaks; each weakness hit removes one, 0 = broken. Default 4 for a boss, 2 otherwise.
• attack: string — The attack's name, shown as the telegraph.
• look: string — How it looks, one line, for the portrait and the figure.
• xp: number — Experience points granted for beating it, 0 to 9999.
• gold: number — Gold granted for beating it, 0 to 9999.
• dropItemId: string | null — Id of the item it may leave, or null; a boss always leaves it, others sometimes.
• portraitId: string | null — Id of the monster's picture in the asset map handed to the player, or null for none.

MonsterPlacement

interface MonsterPlacement extends Cell

A monster standing in a dungeon floor at the start.

• monsterId: string — The monster id.
• room: number — The room it roams, as an index into the floor's rooms; -1 for a corridor.
• boss: boolean — True for the floor's boss.

Npc

interface Npc

A non-player character who lives in a region.

• id: string — Unique among the npcs; what quest givers and steps refer to.
• name: string — The npc's name.
• role: NpcRole — What they do in town and in quests: one of the options' npcRoles.
• regionId: string — Id of the region they live in; the first region if theirs does not exist.
• want: string — What they want, one line.
• fear: string — What they fear, one line.
• secret: string — What they are hiding, one line.
• voice: string — A verbal habit or stance: "brusque", "quotes scripture".
• lines: string[] — Up to limits.lines lines they say when spoken to, in turn.
• look: string — How they look, one line, for the portrait and the figure.
• portraitId: string | null — Id of the npc's picture in the asset map handed to the player, or null for none.

NpcRole

type NpcRole = string

An npc's role: one of the options' npcRoles (default NPC_ROLES).

Overworld

interface Overworld

The overworld: one terrain id per cell, the region each cell belongs to, the entrances and the start.

• cols: number — Columns.
• rows: number — Rows.
• tiles: Uint8Array — Terrain ids, row-major, cols × rows; look them up in WorldMaps.terrain.
• region: Int8Array — Index into World.regions per cell, row-major; every cell belongs to a region.
• entrances: Entrance[] — Every town and dungeon entrance.
• start: Cell — Where the party stands when it first steps out of the start town.
• centres: Record<string, Cell> — The centre cell of each region, by region id, where its name would be drawn.

Quest

interface Quest

A quest: steps to do for a reward.

• id: string — Unique among the quests.
• title: string — The quest's title.
• shape: QuestShape — The kind of story it tells (one of the options' questShapes); the steps decide the work.
• main: boolean — Whether it belongs to the main story rather than being a side quest: an act ends when its main quests are done.
• act: number — The act it belongs to, 1 to the story's act count.
• giverId: string — Id of the npc who gives it; empty if that npc does not exist.
• regionId: string — Id of the region it belongs to; the giver's region if that does not exist.
• complication: string — The twist on the shape.
• steps: QuestStep[] — The steps in order, at most limits.steps.
• rewardGold: number — Gold paid on completion, 0 to 99999.
• rewardItemId: string | null — Id of the item given on completion, or null.
• consequence: string — What changes in the world afterwards.

QuestShape

type QuestShape = string

A quest's shape: one of the options' questShapes (default QUEST_SHAPES).

QuestStep

interface QuestStep

One step of a quest.

• text: string — What the player is told to do.
• kind: StepKind — What counts as doing it: one of the options' stepKinds.
• targetId: string — What the step's kind names: an npc (talk, deliver), monster (kill), item (fetch) or region (reach); '' when it names nothing that exists.
• count: number — How many times it must be done (kills or items), 1 to limits.count. Default 1.

Region

interface Region

A region of the world map: a biome, and perhaps a town and a dungeon.

• id: string — Unique among the regions; what npcs, heroes' joinAt and quests refer to.
• name: string — The region's name.
• biome: Biome — The terrain of its part of the overworld: one of the options' biomes.
• mood: string — One line: the mood of the place.
• identity: string — One line: what it lives on, who runs it.
• x: number — Where it sits on the world map, 0 at the left to 1 at the right. Default 0.5.
• y: number — Where it sits on the world map, 0 at the top to 1 at the bottom. Default 0.5.
• size: number — Footprint, 1 to 3.
• act: number — Which act it belongs to, 1 to the story's act count.
• town: Town | null — The region's town, or null if it has none.
• dungeon: Dungeon | null — The region's dungeon, or null if it has none.

Rules

interface Rules

The rules a world is played by.

• partySize: number — Heroes who fight in a battle, 1 to limits.party. Default 3.
• maxLevel: number — The highest level a hero can reach, 2 to limits.level. Default 10.
• difficulty: Difficulty — How hard the monsters are: one of the options' difficulties. Default fair.
• encounterRate: number — Chance per step in the wilds, 0 to 0.3. Default 0.08.
• lens: Lens — Lens for every dungeon that does not say otherwise. Default top-down.

Skill

interface Skill

A skill a hero can use in battle by spending MP.

• id: string — Unique among the skills; what a hero's skillIds refer to.
• name: string — The skill's name.
• element: Element — The element of its damage; none for physical.
• mp: number — MP the skill costs, 0 to 99. Default 4.
• power: number — For damage, added to the user's attack; for a heal, the amount restored (plus half the user's attack). 0 to 999. Default 12.
• target: SkillTarget — Who it can be aimed at.
• effect: SkillEffect — What it does: one of the options' skillEffects.

SkillEffect

type SkillEffect = string

A skill's effect: one of the options' skillEffects (default SKILL_EFFECTS).

SkillTarget

type SkillTarget = (typeof SKILL_TARGETS)[number]

A skill's target: one of SKILL_TARGETS.

Stats

interface Stats

A set of six stats, for a hero, a monster or an item's bonus.

• hp: number — Hit points: the most health. Cleaned to 1 to 9999.
• mp: number — Magic points: what skills spend. Cleaned to 0 to 999.
• atk: number — Attack strength, added to a skill's power and set against the target's defence. Cleaned to 0 to 999.
• def: number — Defence, which cuts the damage taken. Cleaned to 0 to 999.
• spd: number — Speed, which sets who acts first in a battle. Cleaned to 0 to 99.
• lck: number — Luck, which raises the chance of a critical hit. Cleaned to 0 to 99.

StepKind

type StepKind = string

A quest step's kind: one of the options' stepKinds (default STEP_TARGETS' keys).

StepTarget

type StepTarget = 'npc' | 'monster' | 'item' | 'region' | 'none'

What a quest step's targetId names: an npc, a monster, an item, a region, or nothing.

Story

interface Story

The story: the premise, the villain, the acts and the ending.

• premise: string — One line: what the game is about.
• hook: string — The first sixty seconds: what is taken, sealed, sick or missing.
• villain: Villain — Who stands against the heroes.
• acts: Act[] — The acts, 1 to limits.acts of them (default 3; a world that writes none gets three). Regions and quests belong to one by number.
• ending: string — How the story ends, at most limits.para characters.

TerrainDef

interface TerrainDef

One overworld tile kind: what it is called, how a tool paints it, whether a party walks it and whether wandering monsters live on it.

• id: number — The tile id stored in Overworld.tiles.
• name: string — A short name.
• color: string — A CSS hex colour a tool can paint the cell with.
• walkable: boolean — Can the party step on it.
• encounter: boolean — Do random encounters happen on it.

Town

interface Town

A town in a region: where the shop and the inn are, laid out by the town generator.

• name: string — The town's name. Default Town.
• blurb: string — One line about the town.
• layout: TownLayout — The template its map is generated from: one of the options' townLayouts.
• seed: number — Seed for the town map generator, a whole number from 0 to 2^31. Default 1.
• shopItemIds: string[] — Items the shop stocks, at most limits.shop. Empty = no shop.
• innPrice: number — Gold per night; 0 = no inn.

TownBuilder

interface TownBuilder

What a town template draws with: the grid, the town's seeded random numbers and the drawing verbs.

• readonly cols: number — Columns.
• readonly rows: number — Rows.
• rng(): number — The town's seeded random number in [0, 1).
• put(c: number, r: number, v: number): void — Set one cell to a town tile id (TT); off the grid is ignored.
• get(c: number, r: number): number — The tile id of a cell; a wall off the grid.
• rect(c: number, r: number, w: number, h: number, v: number): void — Fill a rectangle.
• hline(c0: number, c1: number, r: number, v: number): void — A horizontal line from column c0 to c1, inclusive.
• vline(c: number, r0: number, r1: number, v: number): void — A vertical line from row r0 to r1, inclusive.
• building(c: number, r: number, w: number, h: number, role: TownBuilding['role']): TownBuilding — A building: a roof row, walls, a door in the middle of the bottom edge. A shop or inn gets its spot at the door.
• scatter(count: number, w: number, h: number, role: TownBuilding['role'], ok: (v: number) => boolean, tries?: number): void — Up to count buildings at random places where every cell around them passes ok.
• trees(chance: number, ok: (v: number) => boolean): void — Trees along the two outer rings of cells, each with chance, where ok.

TownBuilding

interface TownBuilding

A building footprint in a town.

• col: number — Left column.
• row: number — Top row.
• w: number — Width in tiles.
• h: number — Height in tiles.
• door: Cell — The door cell, on the bottom edge.
• role: 'shop' | 'inn' | 'house' | 'hall' | 'hut' — What the building is.

TownLayout

type TownLayout = string

A town's layout: one of the options' townLayouts (default TOWN_LAYOUTS).

TownLayoutRule

interface TownLayoutRule

A town template.

• cols: number — Columns.
• rows: number — Rows.
• fill: number — The town tile id every cell starts as.
• build(b: TownBuilder, want: { shop: boolean; inn: boolean }): void — Draw the town; want says whether it has a shop and an inn to place.

TownMap

interface TownMap

A town map: tiles, buildings and the spots the game needs.

• regionId: string — The region the town belongs to.
• layout: TownLayout — The layout it was built from.
• cols: number — Columns.
• rows: number — Rows.
• tiles: Uint8Array — Town tile ids, row-major; look them up in TOWN_TERRAIN.
• buildings: TownBuilding[] — The buildings.
• spots: TownSpot[] — Exit, start, shop, inn and one spot per npc of the region.

TownSpot

interface TownSpot extends Cell

A named place in a town where something happens.

• kind: 'exit' | 'start' | 'shop' | 'inn' | 'npc' — What the spot is.
• id?: string — The npc id, for npc spots.

TownTerrainDef

interface TownTerrainDef

A tile kind inside a town.

• id: number — The id stored in TownMap.tiles.
• name: string — A short name.
• color: string — A CSS hex colour.
• walkable: boolean — Can the party step on it.

Villain

interface Villain

The story's villain.

• name: string — The villain's name, at most limits.name characters.
• want: string — What they are trying to get.
• wound: string — What was done to them.
• line: string — The thing they will not do.
• monsterId: string | null — The monster fought at the end, when the villain is one.

World

interface World

A whole world document: intent that the engine generates and plays.

• v: 1 — The format version; always 1.
• title: string — The game's title.
• look: string — One line of art direction, for every picture.
• seed: number — Seed for the world's own random choices, a whole number from 0 to 2^31. Default 1.
• story: Story — The story.
• regions: Region[] — The regions of the map, at most limits.regions.
• heroes: Hero[] — The playable heroes, at most limits.heroes.
• npcs: Npc[] — The non-player characters, at most limits.npcs.
• monsters: Monster[] — The monsters, at most limits.monsters.
• items: Item[] — The items, at most limits.items.
• skills: Skill[] — The skills, at most limits.skills.
• quests: Quest[] — The quests, at most limits.quests.
• rules: Rules — The rules the world is played by.

WorldLimits

type WorldLimits = { -readonly [K in keyof typeof WORLD_LIMITS]: number }

A full set of caps, as WORLD_LIMITS.

WorldMaps

interface WorldMaps

Everything worldMaps builds.

• overworld: Overworld — The overworld.
• terrain: readonly TerrainDef[] — The overworld terrain table the maps use: TERRAIN and any extra terrain.
• towns: Record<string, TownMap> — A town per region that has one, by region id.
• dungeons: Record<string, DungeonMap> — A dungeon per region that has one, by region id.

WorldOptions

interface WorldOptions

What a world may contain: the caps and every vocabulary. Each defaults to the built-in list; a list replaces the built-in one (spread the default to extend it). When a value is not in its list it falls to the built-in default if the list has it, else to the list's first entry.

• limits?: Partial<WorldLimits> — Caps over WORLD_LIMITS.
• biomes?: readonly string[] — Region biomes. Default BIOMES. A map generator needs a rule for each (worldMaps' biomes).
• dungeonThemes?: readonly string[] — Dungeon themes. Default DUNGEON_THEMES.
• townLayouts?: readonly string[] — Town layouts. Default TOWN_LAYOUTS. A map generator needs a template for each (worldMaps' townLayouts).
• classes?: Readonly<Record<string, Stats>> — Hero classes and their level-1 stats. Default HERO_BASE.
• elements?: Readonly<Record<string, string | null>> — The element wheel: every element but none, and the one it beats (or null). Default ELEMENT_BEATS.
• itemKinds?: readonly string[] — Item kinds. Default ITEM_KINDS.
• itemEffects?: readonly string[] — Consumable effects. Default ITEM_EFFECTS.
• skillEffects?: readonly string[] — Skill effects. Default SKILL_EFFECTS.
• stepKinds?: Readonly<Record<string, StepTarget>> — Quest step kinds and what each one's target names. Default STEP_TARGETS.
• difficulties?: readonly string[] — Difficulty settings. Default DIFFICULTIES.
• npcRoles?: readonly string[] — Npc roles. Default NPC_ROLES.
• questShapes?: readonly string[] — Quest shapes. Default QUEST_SHAPES.

WorldVocabulary

interface WorldVocabulary

WorldOptions with every default filled in.

• limits: WorldLimits — The caps.
• biomes: readonly string[] — Region biomes.
• dungeonThemes: readonly string[] — Dungeon themes.
• townLayouts: readonly string[] — Town layouts.
• classes: Readonly<Record<string, Stats>> — Hero classes and their level-1 stats.
• elements: readonly string[] — Every element, none first.
• beats: Readonly<Record<string, string | null>> — What each element beats, or null.
• itemKinds: readonly string[] — Item kinds.
• itemEffects: readonly string[] — Consumable effects.
• skillEffects: readonly string[] — Skill effects.
• stepKinds: Readonly<Record<string, StepTarget>> — Step kinds and their targets.
• difficulties: readonly string[] — Difficulty settings.
• npcRoles: readonly string[] — Npc roles.
• questShapes: readonly string[] — Quest shapes.