locations

name	locations
description	Schema and rules for creating locations
context	fork
agent	locations

Locations

Edit tabs/locations.json.

Required Fields

Field	Requirement
name	Must match object key exactly
basicInfo	Freeform descriptive paragraph about the location
x	X coordinate - generate random value within the region
y	Y coordinate - generate random value within the region
radius	Infer from description (see radius guidelines below)
region	Must exist in tabs/regions.json
complexityType	Always "complex"
detailType	Always "detailed"
hiddenInfo	Full paragraph with location secrets - always include
imageUrl	URL for the location's image

Conditional Fields

Field	When to Include
known	Set to false to hide from map at game start. Omit or set true for visible by default
areas	Optional - include when the location has distinct internal spaces
factions	Only for major plot-relevant faction presence
npcLevelRange	{ min, max } band for NPCs generated here whose level you don't set explicitly. Use it to keep a low-level village or a high-level dungeon on-theme regardless of party level

Never Include

Omit these fields (auto-set at runtime):

• visited, lastVisitedTick, visitedAreas
• visualTags, embeddingId

areas Format

For locations with distinct internal spaces, define interconnected areas.

Each area needs:

• description: Freeform description of the area
• paths: Array of connected area names

Rules:

• Use Title Case for area names (they are display strings, not programmatic identifiers)
• All paths must be bidirectional (if A links to B, B must list A)
• Areas can be 0 or more - no minimum required

Coordinate System

• Check locationSettings.regionSize in tabs/settings.json to determine bounds
• Valid range is -regionSize/2 to regionSize/2
• The location's radius must not extend beyond bounds (x ± radius and y ± radius must stay within range)
• No two locations can overlap (distance between centers must be >= sum of radii)
• Check tabs/locations.json for existing locations and their coordinates to avoid overlap

Radius Guidelines

Infer radius from the location type:

Location Type	Radius
Single room/building	1-2
Small structure	2-4
Village/small settlement	4-8
Town	8-15
Large town/small city	15-25
Major city	25-50

Schema

interface Location {
  name: string
  basicInfo: string
  x: number
  y: number
  radius: number
  region: string
  complexityType: 'complex'
  detailType: 'detailed'
  hiddenInfo: string
  known?: boolean
  areas?: Record<string, Area>
  factions?: string[]
  npcLevelRange?: { min: number; max: number }
  imageUrl?: string
}

interface Area {
  description: string
  paths: string[]
}

Reference

For detailed documentation, see locations-reference.md.