Locations

Display name of the location, and must be byte-identical to the outer map key — the engine matches entries by key, so the key and name have to be exactly equal (same case, same spaces). A mismatch is a validation error. Build the map as { location["name"]: location }. (Area keys inside areas follow the same display-name rule — see areas below.)

"simple" | "complex" | "wilderness". The correct field name is complexityType, not complexity. Using the shortened form complexity is not a valid schema field and is ignored by the codec. "linear" is NOT a valid value. Use "complex" for any location with multiple areas.

"basic" or "detailed" — required field (codec-enforced). Determines whether quests use spatialRelationship or questLocation. Omitting it causes a validation error.

areas use description not basicInfo. Production area descriptions run 200–400 chars — significantly longer than a single sentence. A strong area description covers three things: (1) physical character of the space, (2) what function or activity happens here, (3) one atmospheric or sensory detail that makes the area distinct. The third element — a smell, a sound, a social rule, a visual anomaly — is what makes areas feel inhabited rather than labelled.

Area keys must be display names, not snake_case. The area key is what the game displays to the player — "Council Hall" not "council_hall". Using snake_case produces ugly output like "The Capital - Council_hall" in the location bar. The key is also referenced directly in paths, npcs.currentArea, and storyStarts.locationAreas — a rename requires updating all three, so get the names right from the start.

⚠️

Warning: Location area objects use "description", not "basicInfo". Using basicInfo in an area object causes silent failure — the area appears but with no description. The correct field is "description".

An area's own artwork takes the same images.establishingShot object, with the same crop framing, as the location's.

Optional Array<string>. Array of faction display-name strings associated with this location. Names must exactly match faction keys. Tells the narrator which factions have a presence here, influencing NPC affiliations and political framing in the scene.

Optional { min, max } integer band constraining the levels of AI-generated NPCs in this specific location. Takes priority over the parent region's npcLevelRange for NPCs generated here. Use it for outliers -- a high-tier dungeon inside a low-tier region, or a starter-friendly hub inside a high-tier region. NPCs with an explicit authored level ignore the band; only level-less generated NPCs are rolled near party level and then clamped into it. Omit to inherit the region's band (or the engine default when the region has none).

Optional string. URL of a banner or map image for this location, shown in the location view. A location image is shown two ways in play: a tall full-screen card on arrival, and a wide banner under Map → Location. Both are crops of the same file, so no single size avoids cropping — keep the subject centred and clear of the edges. Minimum 600×600. In the editor you can upload your own image or generate one from a prompt — both set this URL.

Positions the visible window over the source image along the horizontal axis, as a percentage: 0 holds the left edge, 50 centres it, 100 holds the right edge. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

Positions the visible window over the source image along the vertical axis, as a percentage: 0 holds the top edge, 50 centres it, 100 holds the bottom edge. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

Scales the image inside its frame, as a percentage of the unzoomed fit: 100 fills the frame with no magnification, 150 shows it at one and a half times, cropping to the area picked by the focus fields. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

The public-facing description of a location. It should answer: what is this place, who is here, and what is the dominant feeling of being in it? Keep it to 2–3 sentences.

The truth beneath the surface. Strong location hiddenInfo covers: a hidden faction presence or active operation, a historical or structural secret, specific character secrets attached to this place, and — most importantly — something actively happening right now that the player can discover. Static backstory is less useful than a live situation. Length: 400–1,600 chars for complex locations; shorter is fine for simple ones.

Horizontal coordinate within the parent region's cell, ranging from -regionSize/2 to +regionSize/2 (regionSize lives in Location Settings, default 100 so -50 to +50). The unit is local kilometres, and the two coordinate systems compose: a location's global position is region.x * regionSize + x, and the same for y. The Builder's Map view sets it by dragging.

Vertical coordinate within the parent region's cell, same range as x; positive y is north. The Builder's Map view sets it by dragging.

The location's size on the map, as a positive number in local kilometres. Worlds commonly author 1, 2, or 3, which is a convention rather than a limit — any positive value is accepted, and the map marker is drawn from the value itself rather than from a fixed set of size classes.

The radius is also the travel catchment. A coordinate belongs to a location when it lies within that radius of the centre, and where two locations both contain a point, the one with the smaller radius takes it. Keep circles from overlapping so arrivals resolve where you expect, and give a location that should win a contested area the tighter radius rather than the wider one.

Key of the parent region in regions; the location renders inside that region's map cell.

Visual metadata tags for the location.

Whether the location starts revealed to players; defaults to true, set false to hide it at game start.