Regions Reference

Complete documentation for tabs/regions.json.

Schema

interface Region {
  name: string              // ✅ Display name, must match object key
  basicInfo: string         // ✅ Geographic and atmospheric description
  x: number                 // ✅ Integer grid coordinate (horizontal position)
  y: number                 // ✅ Integer grid coordinate (vertical position)
  realm?: string            // ✅ Key from realms.json (optional)
  factions?: string[]       // ✅ Keys from factions.json with regional presence
  hiddenInfo?: string       // ✅ Unused — region secrets belong in location or NPC entries
  known?: boolean           // ✅ Defaults to true; set false to hide at game start
  npcLevelRange?: { min: number, max: number }  // ✅ Optional level band for NPCs generated in this region, used when the location has no band of its own. NPCs with no explicit level are rolled near party level, then clamped into this band. NPCs with an explicit level ignore it
  images?: { map?: SceneImage }  // ✅ Region map image with its crop. When imageUrl is absent, the engine generates a map during play and saves it back; an existing map is never regenerated
}

interface SceneImage {
  crop: { focus: { x: number, y: number }, zoom: number }  // ✅ Required whenever the image object is present. focus x/y run 0..100 (50 = centered, the default); zoom runs 100..300 (100 = no zoom, the default). Out-of-range values are clamped
  imageUrl?: string                                        // ✅ Image URL. Optional; generated during play when absent
}

Legend

• ✅ Predefine-able: Can be set in config, preserved via spread
• ❌ Always overwritten: Set by initialization regardless of what exists in config

Coordinate System

Regions occupy integer positions on a 2D grid. The grid extends infinitely in all directions.

        North (-y)
           ↑
West (-x) ← → East (+x)
           ↓
        South (+y)

Grid Layout Example

Region (0,0)  Region (1,0)  Region (2,0)
Region (0,1)  Region (1,1)  Region (2,1)
Region (0,2)  Region (1,2)  Region (2,2)

Cross-Region Travel

When players travel past region boundaries, coordinates wrap to the adjacent region:

From location (95, 50) in region (2,2)
Travel +10 in x direction
→ Arrive at (5, 50) in region (3,2)

The regionSize setting in locationSettings determines the coordinate space within each region (default: 100).

Relationship to Realms

Realms are optional thematic containers. A region can exist:

• Without a realm: For single-realm worlds, omit the realm field entirely
• Within a realm: Reference the realm key for multi-realm worlds

Players can only access locations in regions whose realm is known (or regions without a realm).

// Single-realm world (no realm field needed)
regions: {
  "northern-wastes": {
    name: "Northern Wastes",
    x: 0, y: 0
  }
}

// Multi-realm world
regions: {
  "northern-wastes": {
    name: "Northern Wastes",
    x: 0, y: 0,
    realm: "mortal-lands"
  },
  "shadow-wastes": {
    name: "Shadow Wastes",
    x: 0, y: 0,
    realm: "shadow-realm"
  }
}

Regions at the same coordinates in different realms can represent parallel locations (e.g., a place and its shadow reflection).

Relationship to Locations

Locations exist within regions. Each location references its containing region and has float coordinates within the region’s coordinate space.

// Region defines the grid cell
regions: {
  "central-plains": {
    name: "Central Plains",
    x: 1, y: 1
  }
}

// Locations exist within the region
locations: {
  "thornhaven": {
    name: "Thornhaven",
    region: "central-plains",
    x: 45.5,    // Position within region (-regionSize/2 to regionSize/2)
    y: 32.0
  }
}

Locations sit within half the region size of the center in either direction, with a positive radius.

A region typically contains 3-8 locations, though this varies by world design.

Location Cascading

When a trigger or travel action sets party-location, the system automatically updates the party’s region:

Set party-location: "Thornhaven"
        ↓
currentLocation = "Thornhaven"
currentRegion = location.region ("central-plains")
currentRealm = region.realm (if set)

Cross-References

Field	References
realm	tabs/realms.json
factions	tabs/factions.json
(referenced by) region field in locations	tabs/locations.json