storybook/docs/reference/16a-locations.md

Locations

Locations define places in your world -- rooms, buildings, cities, landscapes, or abstract spaces. They provide spatial context for characters, events, and narratives.

---

Syntax

<location-decl> ::= "location" <identifier> "{" <field>* <prose-block>* "}"

A location declaration consists of:

• The location keyword
• A unique name (identifier)
• A body block containing fields and optional prose blocks

Locations are one of the simpler declaration types -- they hold fields and prose blocks but do not support resource linking (uses behaviors / uses schedule) like characters or institutions.

---

Basic Location

The simplest location has a name and descriptive fields:

location BakersBakery {
    type: bakery
    capacity: 30
    address: "14 Main Street"
    open_hours: "06:00-18:00"
}

Fields can use any value type: integers, floats, strings, booleans, enums, lists, ranges, and durations.

---

Fields

Location fields describe properties of the place:

location BakerHome {
    type: residence
    bedrooms: 3
    has_garden: true
    garden_size_sqft: 450.0
    residents: ["Martha", "David", "Jane"]
    comfort_level: 0.85
}

Common Field Patterns

Field	Type	Description
type	enum/identifier	Category of the place
capacity	integer	How many can be in this place
size	enum/float	Physical size
coordinates	integer/float	Position in a world map
accessible	boolean	Whether characters can enter

These are conventions, not enforced schema. You define whatever fields are meaningful for your world.

---

Prose Blocks

Locations support prose blocks for rich narrative content. Prose blocks are delimited by ---tag markers:

location BakersBakery {
    type: bakery
    capacity: 30

    ---description
    A warm, inviting bakery on Main Street. The smell of fresh bread
    wafts out the door every morning at dawn. Martha has run the shop
    for fifteen years, and the locals consider it the heart of the
    neighborhood.
    ---

    ---atmosphere
    Flour dust catches the light from tall windows. A display case
    holds rows of golden pastries. Behind the counter, the kitchen
    hums with activity from 4 AM onward.
    ---
}

Prose block rules:

• Start with ---tag_name on its own line
• Content is free-form text (Markdown supported)
• End with --- on its own line
• The tag name becomes the key for retrieval
• Multiple prose blocks per location are allowed
• Each tag must be unique within the location

---

Ranges

Locations can use range values for procedural variation:

location MarketSquare {
    type: outdoor_market
    stalls: 10..25
    daily_visitors: 50..200
    noise_level: 0.4..0.9
}

When instantiated, values are selected from within the specified range. This is useful for locations that should vary across simulation runs.

---

Lists

Locations can hold list values:

location BakersBakery {
    type: bakery
    products: ["sourdough", "croissants", "rye bread", "cinnamon rolls"]
    equipment: ["stone oven", "mixing station", "proofing cabinet"]
}

---

Referencing Other Entities

Location fields can reference other declarations by name:

location BakersBakery {
    type: bakery
    owner: Martha
    neighborhood: MainStreet
    part_of: TownCenter
}

These are identifier references -- they are not validated as cross-references at parse time, but the resolver checks that referenced names exist in the name table.

---

Nested Structure with Fields

You can model spatial hierarchy using fields:

location BakersBakery {
    type: bakery
    parent: MainStreet

    // Zones within the bakery
    has_kitchen: true
    has_storefront: true
    has_storage_room: true

    // Dimensions
    total_sqft: 1200
    kitchen_sqft: 600
    storefront_sqft: 400
    storage_sqft: 200
}

location MainStreet {
    type: street
    parent: TownCenter
    length_meters: 500
    shops: 12
}

location TownCenter {
    type: district
    population: 2000
}

There is no built-in parent-child relationship for locations -- you model hierarchy through conventional field names like part_of, parent, or contains.

---

Location with Enum Fields

Use enums for type-safe categorization:

enum PlaceType {
    residence, shop, workshop, office,
    park, street, square, church
}

enum Accessibility {
    public, private, restricted, members_only
}

location BakersBakery {
    type: shop
    accessibility: public
    capacity: 30
}

location BakerHome {
    type: residence
    accessibility: private
    capacity: 8
}

---

Complete Example: Baker Family Locations

use schema::enums::{PlaceType, Accessibility};

location BakersBakery {
    type: shop
    accessibility: public
    owner: Martha
    address: "14 Main Street"
    capacity: 30
    employees: 4
    established: "2011"
    specialty: "artisan sourdough"
    daily_output_loaves: 80..120

    ---description
    Martha Baker's artisan bakery, known throughout town for its
    sourdough and pastries. The shop opens at 6 AM sharp, and by
    mid-morning there's usually a line out the door.
    ---

    ---history
    Originally a hardware store, Martha converted the space after
    winning a local baking competition. The stone oven was imported
    from France and is the heart of the operation.
    ---
}

location BakerHome {
    type: residence
    accessibility: private
    address: "22 Elm Lane"
    bedrooms: 4
    has_garden: true
    garden_size_sqft: 600
    residents: ["Martha", "David", "Jane", "Tom"]
    comfort_level: 0.9

    ---description
    A comfortable family home on a quiet street. The kitchen is
    oversized (Martha insisted) and there's always something
    baking, even at home.
    ---
}

location BakersGuildHall {
    type: office
    accessibility: members_only
    address: "7 Guild Row"
    capacity: 100
    meeting_room_capacity: 40
    established: "1892"

    ---description
    The historic headquarters of the Bakers Guild, where trade
    matters are discussed and apprenticeships are arranged.
    ---
}

---

Validation Rules

1. Unique names: Location names must be unique within their scope
2. Valid field values: All fields must have values that conform to value types
3. Unique field names: No duplicate field names within a location
4. Unique prose tags: No duplicate prose block tags within a location
5. Valid identifiers: Location names must follow identifier rules ([a-zA-Z_][a-zA-Z0-9_]*)

---

Locations vs. Other Declarations

Aspect	Locations	Institutions	Characters
Purpose	Physical/abstract places	Organizations/groups	Individuals
Resource linking	No	Yes	Yes
Prose blocks	Yes	Yes	Yes
Species	No	No	Yes
Templates	No	No	Yes

Locations are intentionally simple. They define where things happen. For who does things, use characters. For organizational structures, use institutions.

---

Cross-References

• Characters -- Characters can reference locations via fields
• Institutions -- Institutions can be associated with locations
• Schedules -- Schedule activities can reference locations
• Value Types -- All field value types
• Other Declarations -- Overview of all utility declarations
• Validation Rules -- Complete validation reference