Locations

Display name of the location, shown to players. Required. Required, and the outer key must match it exactly: Voyage rejects a world whose key and name differ.

Required, and one of "simple", "complex" or "wilderness": Voyage rejects a world whose location omits it. 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.

Required, and one of "basic" or "detailed": Voyage rejects a world whose location omits it. A "basic" location of complexityType: "complex" is fleshed out by generateLocationDetails, which writes its areas and hiddenInfo; a "detailed" one is used as authored.

areas use description not basicInfo, and every area needs both description and paths. A strong area description usually runs longer than a single sentence and 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.

Use display names for area keys, not snake_case. The area key is what the game displays to the player: "Council Hall", not "council_hall". An area can also carry an optional name; paths, an NPC's currentArea and a story start's locationAreas all resolve by the area key. 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"; an area without description fails validation.

An area's own artwork takes the same images.establishingShot object, with the same crop framing, as the location's, and is generated during play the same way when it has no image.

Optional Array<string> of faction keys present at this location; a key that names no faction raises a warning. 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 use the region's band, if it has one. Both values must be positive whole numbers; Voyage rejects anything else.

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. Without one, the engine generates an image during play and saves it back, and an existing image is never regenerated. Whenever images.establishingShot is present, its crop is required.

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. Defaults to 50. Out-of-range values are clamped. Saved by the crop control rather than typed by hand.

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. Defaults to 50. Out-of-range values are clamped. Saved by the crop control rather than typed by hand.

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. Ranges from 100 to 300, default 100. Out-of-range values are clamped. Saved by the crop control rather than typed by hand.

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. Complex locations benefit from the fuller version; simple ones can be brief.

Horizontal coordinate (a finite number) 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 finite 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. Voyage rejects a world whose location omits it. An empty or unknown key is accepted but raises a warning.

Visual metadata tags for the location.

Whether players know the location from the start. Set it to true for a location they should see from the start; without it, the location starts unknown and counts as known once the party has visited it.

true hides the location. The location-hidden trigger effect sets or toggles it during play, so a trigger can reveal a hidden location or hide one as the story moves on. Optional.