UnofficialWIKI
Builder
Edit / Suggest changeSuggest deletion

Realms

realms

A realm is the top-level container for your regions - the world, country, or dimension the story takes place in. Most scenarios need exactly one. Use multiple realms only for true planar or dimensional scenarios.

In the editor

"Major geographical divisions of the world"

Editor location
Files → World → Advanced → Realms
Editor type
Edit in Studio + View JSON
API endpoint
/sections/realms.json/sections/realms.md
Size limits
  • realms.*.basicInfo — 100,000
  • realms (entire section) — 100,000
Related

Schema

json
{
  "realms": {
    "<key>": {
      "name": "string",
      "basicInfo": "string",
      "initialKnown": "boolean"
    }
  }
}

Example

json
{
  "realms": {
    "The Compact": {
      "name": "The Compact",
      "basicInfo": "The Compact is the largest of several post-war successor realms, ruled from the Capital by the Merchant Council since the end of the Old War sixty years ago. Most of its population live in the Heartland between the Capital and the Coast; the Frontier to the north is contested woodland still mapped from before the war. Stable enough that ordinary people travel its roads without armed escort, brittle enough that everyone who pays attention is quietly preparing for the day the Council loses its grip.",
      "initialKnown": true
    }
  }
}

Fields

name

Display name of the realm, shown as the map title. Required, and the outer key must match it exactly: Voyage rejects a world whose key and name differ. Regions and triggers reference a realm by its outer map key.

initialKnown

Realm access: players can only access locations inside known realms. A realm starts known unless initialKnown is false. Use initialKnown: false for realms the player must discover through gameplay.

basicInfo

Player-facing description of the realm; the narrator reads it during play.

Structure

Realm reference rule

Every realm string referenced in your regions objects must have a corresponding entry here; one that doesn't raises a warning. A region's realm is also what lets travel to its locations update the party's realm.

Parallel realms

Parallel realms: regions at the same (x, y) coordinates in different realms can represent parallel locations -- a place and its shadow reflection, a city and its dream-state mirror. The grid is per-realm, so the same coordinate is reusable across realms.

Behaviour

Realm travel

Moving the party to a location, whether by travel, teleport, or a party-location trigger effect, updates the party's region and realm to match that location, so the map stays coherent. Player-chosen movement is native; relocating the party with no input on their part uses a trigger with a party-location effect (see Forced movement on the Triggers page).

Revealing or hiding a realm

A realm's visibility is controlled with the known-entity trigger effect -- set true to reveal a previously hidden realm, false to hide one. Setting the party's realm with a party-realm effect also reveals it.

json
{ "type": "known-entity", "entity": "Shadow Realm", "operator": "set", "value": true }

Per-realm AI behaviour

Note: Multi-realm worlds where AI generation needs to behave fundamentally differently per realm (different geography rules, factions, creatures) can branch on the realm inside aiInstructions tasks. See Conditional routing in the Advanced AI Techniques appendix.