# Town

> Kinbarrow modding reference — content tree `45d0fe274f851548`, version `0.2.0+main.c05ef2b`.

`towns/<id>.ron` — one authored settlement. `id` equals the file stem. The fields are grouped by the interpreter's build PHASES (geography, power, factions, folk, knowledge, goods, professions, production, items, seats) — the order `seed.rs` mints its nodes in, so a campaign-built world is node-for-node the fixture's (the equivalence lock).

**Note on syntax:** these files are RON, not JSON. The shapes below are exact,
but punctuation follows RON — read a real `data/*.ron` file alongside.

## Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `civic_venues` | `Venue[]` | required | Civic venues with no owner-operator (the keep, the tavern, the office). |
| `deities` | `string[]` | required | Deity names worshipped here — minted as `Deity` nodes, referenced by a character's `worships`. |
| `factions` | `Faction[]` | required | The town's factions (guild, watch, cult). |
| `folk` | `Character[]` | required | The dockside cast that owns no venue (the player, the fisherman, ...). |
| `id` | `string` | required |  |
| `items` | `ItemDef[]` | required | Free-standing items (chests, the notice board, the smoke barrel). |
| `keys` | `KeyDef[]` | required | Knowledge keys (the lock lattice), created FIRST, in this order. |
| `knowledge` | `Knowledge` | required | The gated knowledge layer (events, rumors, false beliefs). |
| `name` | `string` | required | The settlement's display name ("Greyharbor"). |
| `power` | `Power` | required | The polity that rules here — its ruler, predecessor, and laws. |
| `production` | `Venue[]` | required | Production venues, each with its owner-operator embedded. |
| `region` | `string` | required | The campaign region this settlement is `LocatedIn`. |
| `residences` | `Venue[]` | required | Residences a wage-earner keeps, created in the seats phase and owned via `owned_by`. |
| `rosters` | `Roster[]` | required | Seeded rosters: extra memberships beyond the seats. |
| `source` | `Source` | required |  |
| `terrain` | `string[]` | required | Terrain tags (data/tables/terrain_tags.ron) — the ground a venue's building type is permitted on. Carried for validation and for the realm's `set_terrain`; a bare authored coast leaves it UNSTAMPED (the fixture carries none — the equivalence lock). |
| `wards` | `Ward[]` | required | The settlement's wards (neighbourhoods), minted in this order. |
| `waters` | `Venue[]` | required | Open waters — a Location adjacent to a ward, worked by anyone. |

## Nested shapes

### BeliefDef

A false belief: a believer denies a true edge and asserts a false one.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asserts_place` | `string` | required | The place the believer wrongly thinks it occurred (a venue handle). |
| `believer` | `string` | required | The character who holds the false belief, by handle. |
| `day` | `uint64` | required | The day the belief took hold. |
| `denies` | `string` | required | The truth edge id (an `OccurredAt.id`) the believer denies. |
| `event` | `string` | required | The event whose location the believer is wrong about. |

### Carry

A carried tool stack, optionally with seeded training against it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `good` | `string` | required | The carried good, by handle (a tool). |
| `qty` | `int64` | required | The quantity carried (units). |
| `trained_days` | `number` | optional | Seeded training days against this tool — the guild fits its fixer out proficient. |

### CausedBy

The causal author of an event, behind its own key.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `gate` | `string` | required | The key gating the causal edge (the conspiracy's secret). |
| `who` | `string` | required | The causal author, by character handle (`Caused` edge). |

### Character

A character — used for folk, the ruler, venue owners, and seat-holders. Every field the fixture sets; the interpreter applies them in the phase order `seed.rs` uses, so props that must precede `derive_traits` (alignment, greed, flavour knobs) do. Only `name` is required — a campaign record is large, so absent optionals default (the soul is what's SET).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action_budget` | `integer` | optional | Active projects/actions the soul may pursue per cycle (`ACTION_BUDGET`). |
| `carries` | `Carry[]` | optional | Tool stacks carried in the pack (tackle, thieves' tools). |
| `conviviality` | `number` | optional | Conviviality dial (`CONVIVIALITY`), clamped 0.5..1.8 (1.0 = neutral). |
| `duty` | `number` | optional | Duty dial (`DUTY`), clamped 0.5..1.8 (1.0 = neutral). |
| `employed_by` | `Employment` | optional | An employment (`Employs` edge FROM the org), the wage on the edge. |
| `ethic` | `number` | optional | Ethical alignment axis (`ETHIC`), -1 (chaotic).. +1 (lawful). |
| `goal` | `string` | optional | A goal string (`GOAL`), e.g. "GOVERNS(Duchy of Greyharbor)". |
| `grants` | `string[]` | default `[]` | Key ids the character holds (a secret keeper). |
| `greed` | `number` | optional | Greed dial (`GREED`), a multiplier clamped 0.5..1.8 (1.0 = neutral). |
| `haunt` | `string` | optional | Off-shift haunt — a ward name or venue handle (see `home`). |
| `hireable` | `boolean` | default `false` | A blade for hire: stamps `vocab::HIREABLE`, so coin — not charisma — brings this soul into a player's company. |
| `home` | `string` | optional | Home/work/haunt — resolved by ward name or venue handle. |
| `industry` | `number` | optional | Industry dial (`INDUSTRY`), clamped 0.5..1.8 (1.0 = neutral). |
| `knows` | `string[]` | default `[]` | Characters this one `Knows` (a named acquaintance edge). |
| `located_at` | `string` | optional | An explicit presence (`LocatedIn`) at the campaign start — the newly arrived stranger, placed rather than drifted from a home. |
| `master` | `boolean` | default `false` | Trained as-if a life already worked: `EXPERT_AT_DAYS + 100` against the trade tool. |
| `member_of` | `string[]` | default `[]` | Faction/ward handles the character is `MemberOf` (t0, or the campaign start when they are a fresh arrival — see `located_at`). |
| `moral` | `number` | optional | Moral alignment axis (`MORAL`), -1 (evil).. +1 (good). |
| `name` | `string` | default `""` |  |
| `owes` | `Debt` | optional | A debt the character `Owes` (the innkeeper's tithe arrears). |
| `owns` | `string[]` | default `[]` | Venue/item handles the character `Owns` at creation (targets must already exist; late-created items carry their owner on the `ItemDef`). |
| `profession` | `string` | optional | A profession handle (a library field: "fisher", "innkeeper", ...). |
| `purse` | `integer` | optional | Coin held (a purse minted last — liquidity). |
| `resolve` | `number` | optional | Resolve dial (`RESOLVE`) — ruin eaten before bending; 0.5..1.8. |
| `roll_seed` | `integer` | optional | Or a deterministic roll salt (the craft quarter rolls stats). |
| `scores` | `array` | optional | A hand-cast stat block (STR, DEX, CON, INT, WIS, CHA). |
| `status` | `string` | optional | A display status label (`STATUS`). |
| `tier` | `integer` | optional | Agency tier (`TIER`): how high in the decision ladder this soul sits (1 = a scheming principal). |
| `work` | `string` | optional | Work-shift intent — a ward name or venue handle (see `home`). |
| `workplace` | `string` | optional | The workplace the profession is assigned at (a venue handle). |
| `worships` | `string` | optional | A deity this character `Worships`, by name (a town deity). |

### Debt

A debt (`Owes` edge) with its amount, due date, reason, and the law it accrues under (so fresh arrears fold into the one edge).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `int64` | required | The amount owed, in minor units. |
| `due_day` | `uint64` | required | The day the debt falls due. |
| `reason` | `string` | required | A display reason for the debt. |
| `since_day` | `uint64` | required | The day the debt was incurred. |
| `to` | `string` | required | The creditor, by handle (`Owes` edge target). |
| `under` | `string` | required | The law the debt accrues under, by handle. |

### Employment

An employment: the org that employs the character, an optional wage on the edge, and the day it began.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `by` | `string` | required | The org that employs the character, by handle (`Employs` edge source). |
| `since_day` | `uint64` | required | The day the employment began. |
| `wage` | `integer` | optional | The wage on the edge in minor units per payday; absent = unwaged. |

### EventDef

A gated event, its participants, and where it occurred.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `caused_by` | `CausedBy` | optional | Causal author (`Caused`), with a gate (Morvath's web). |
| `day` | `uint64` | required | The day the event occurred. |
| `gate` | `string` | required | The key gating the event node and its default edges. |
| `id` | `string` | required | Handle for belief cross-reference. |
| `name` | `string` | required |  |
| `occurred_at` | `OccurredAt` | optional | Where it occurred (a venue handle), with an optional gate override. |
| `participants` | `Participant[]` | required | Participants: (who handle, role, optional edge-specific gate override). |
| `succession` | `Succession` | optional | A succession this event records (`Succeeded`). |

### Faction

A faction: its kind, keys, charter goal, hostilities, the laws it enforces, its seat, and its roster wiring.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enforces` | `LawRef[]` | optional | Law handles this faction `Enforces`, each since a day. |
| `free_company` | `boolean` | default `false` | A mercenary free company: lives by the wanted poster. |
| `goal` | `Goal` | optional | The faction's charter goal (kind + handle target), if any. |
| `grants` | `string[]` | default `[]` | Confidence keys this faction holds (its inner circle). |
| `hostile_to` | `string[]` | default `[]` | Faction handles this one is `HostileTo`. |
| `id` | `string` | required | Handle for cross-reference (goal targets, memberships, hostilities). |
| `kind` | `FactionKind` | required | Whether this mints a `Faction` or a `Polity` node. |
| `located_in` | `string` | optional | The ward the faction's SEAT node LOCATED_IN (its coin's physical home). |
| `name` | `string` | required |  |
| `org_kind` | `string` | optional | The organization KIND: an `org_kinds/` id whose muster and combat archetype this faction carries (thieves, law, temple…). Absent = an untyped faction (the polity, a plain house). The twin of the seed's `orgs::install` — the equivalence the isomorphism lock demands. |
| `seat` | `Character` | optional | The seat-holder (created in the seats phase). |
| `seat_coffers` | `boolean` | default `false` | Whether the faction's home + war chest are minted in the SEATS phase (with its seat-holder) rather than the ITEMS phase — the watch keeps its captain's ward, the guild fronts the docks earlier. Item-mint order is fixture-faithful, so this rides where the coffer lands. |
| `seat_ward` | `string` | optional | The ward the faction's seat (and coin) sits in. |
| `treasury` | `integer` | optional | The faction's treasury (coin held). |

### FactionKind

Whether a faction is a `Faction` or a `Polity` node.

`Faction`, `Polity`

### Goal

A faction goal: kind (control/suppress) and a handle target.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `GoalKind` | required | Whether the org wants to Control or Suppress the target. |
| `target` | `string` | required | The goal's subject, by handle (`GOAL_TARGET`, a node the town declares). |

### GoalKind

Faction goal kind — mirrors `factions::FactionGoal`.

`Control`, `Suppress`

### ItemDef

A free-standing item (a locked chest, the notice board, the smoke barrel).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `at_day` | `integer` | optional | The day the item enters play (defaults to t0). |
| `attuned_magic` | `string` | optional | A WONDROUS magic def this item instantiates, worn ATTUNED by its `given_to` holder from genesis — the regent's warded ring. Ignored without a holder: an attunement needs someone to attune. |
| `gate` | `string` | optional | Gate the item node behind a key: a concealed thing, invisible until a keyholder — or a successful Investigate roll — earns the key. |
| `given_to` | `string` | optional | Given to a holder instead of resting (the player's sword). |
| `in_place` | `string` | default `""` | Where it rests (a venue/ward handle). |
| `is_board` | `boolean` | default `false` | Marks the town notice board. |
| `lock_dc` | `integer` | optional | A lock DC fitted. |
| `name` | `string` | default `""` |  |
| `owner` | `string` | optional | Who owns it (a character/faction handle). |
| `stocks` | `Stock[]` | optional | Contents (stored stacks) — coin in a strongbox, dried fish in a barrel. |

### KeyDef

A knowledge key: a local `id` handle plus the graph key NAME.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | required |  |
| `name` | `string` | required |  |

### Knowledge

The gated knowledge layer: events, the rumors that spread them, and the false belief overlays.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `beliefs` | `BeliefDef[]` | required | False-belief overlays a character holds. |
| `events` | `EventDef[]` | required | Gated historical events (the campaign's backstory). |
| `rumors` | `RumorDef[]` | required | Rumors spreading through the wards (diffusion). |

### Law

A law: a rate, and who is subject (wards carry the subject_to edges).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enacted_day` | `uint64` | required | The day the polity `Enacted` it. |
| `id` | `string` | required |  |
| `name` | `string` | required |  |
| `rate` | `integer` | optional | The levy the law charges (`RATE`) — a flat daily figure, or a per-mille wealth rate in minor units; absent = no monetary rate. |

### LawRef

A dated reference to a law handle.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `law` | `string` | required | The law this refers to, by handle (a `Law.id`). |
| `since_day` | `uint64` | required | The day the subjection/enforcement began. |

### OccurredAt

Where an event occurred.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `gate` | `string` | optional | Key gating this edge; absent = the event's own gate. |
| `id` | `string` | optional | Handle to reference this specific edge from a belief (the truth a believer denies). |
| `place` | `string` | required | Where the event occurred, by venue handle. |

### Participant

One participant in an event.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `gate` | `string` | optional | Gate override for this edge (defaults to the event's gate). |
| `role` | `string` | required | The role this participant played, a `ROLE` edge label ("victim"). |
| `who` | `string` | required | The participant, by character handle. |

### Placement

Where a venue sits relative to its ward.

#### Placement::In

`LocatedIn` the ward (a building).

#### Placement::Adjacent

`AdjacentTo` the ward (open water off the docks).

### Power

The polity, its ruler, the predecessor whose death opened the campaign, and the laws.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `controls` | `string` | required | The region the polity controls. |
| `goal` | `Goal` | optional | The polity's goal (`GOAL_KIND`/`GOAL_TARGET`), a handle target. |
| `id` | `string` | required | Cross-reference handle for the polity ("duchy"). |
| `laws` | `Law[]` | required | The polity's laws. |
| `polity` | `string` | required | The polity's name ("Duchy of Greyharbor"). |
| `polity_concept` | `string` | required | The `Concept` a polity IS_A (the ontology anchor: "Polity"). |
| `predecessor` | `Predecessor` | required | The dead predecessor (the assassinated duke). |
| `ruler` | `Character` | required | The regent (the living ruler) — a full character, whose `employed_by` carries the regent's stipend. |
| `seat` | `string` | required | The seat the polity's coin and household live in (a venue handle). |
| `treasury` | `integer` | optional | The polity's treasury (coin held). |

### Predecessor

The assassinated predecessor: a dead character, a closed reign, a title.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | required |  |
| `reign_from_day` | `uint64` | required | The reign's start and end days (closed on the death day). |
| `status` | `string` | required | The predecessor's status label ("Deceased"). |
| `title` | `string` | required | The title held ("Duke of Greyharbor"). |
| `title_from_day` | `uint64` | required | The day the title was assumed. |

### Roster

A seeded membership: a character joins a faction (rosters).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `faction` | `string` | required | The faction joined, by handle (`MemberOf`). |
| `who` | `string` | required | The character joining, by handle. |

### RumorDef

A spreading rumor (ADR: diffusion).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grants` | `string` | required | The key the rumor grants as it spreads. |
| `juiciness` | `double` | required | Spread appetite (`RUMOR_JUICE`): higher travels faster and farther. |
| `name` | `string` | required |  |
| `origin` | `string` | required | The ward it originates from. |
| `started_day` | `uint64` | required | The day the rumor began spreading. |
| `suppression` | `double` | required | Suppression pressure (`RUMOR_SUPP`): higher damps the spread. |

### Source

Every file's top-level value carries `source`.

#### Source::Srd51

SRD 5.1 — the System Reference Document, the shipped baseline.

#### Source::Original

Original content authored for this game (not from the SRD).

#### Source::Personal

A player's own transcription or third-party content in a mod tree — provenance stays honest without borrowing the base tree's markers. Never used by shipped files.

### Stock

A stored stack: a good handle and its opening quantity.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `good` | `string` | required | The stored good, by handle. |
| `qty` | `int64` | required | The opening quantity (units). |

### Succession

A succession recorded on an event.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `as_what` | `string` | required | The title/role succeeded to (the `as` edge prop). |
| `day` | `uint64` | required | The day the succession took effect. |
| `gate` | `string` | required | The key gating the succession edge. |
| `predecessor` | `string` | required | Who is succeeded, by character handle. |
| `successor` | `string` | required | Who succeeds, by character handle (`Succeeded` edge source). |

### Venue

A venue: a place with a name, a ward, the knobs `seed.rs` sets (ASSESSED, MARKUP, RATE_MOD), what it demands and produces, its opening stock, and an optional owner-operator.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessed` | `integer` | optional | Assessed land/structure value in minor units — the bare-walls tax base (`ASSESSED`); absent leaves it unstamped. |
| `building` | `string` | optional | The building TYPE (data/buildings/*.ron) this venue instances — used by the validator for the permit check (`requires ⊆ town terrain`). An authored venue carries its own production (the coast's economy shape), so the interpreter does NOT stamp `BUILDING_TYPE` (that marks worldgen-DERIVED venues); this is the identity/permit ref. |
| `commons` | `boolean` | default `false` | A natural COMMONS feature: sets the `vocab::COMMONS` mark, so the player work-site gate admits ANYONE to its produce (the harbor waters). Defaults false — an ordinary building is not a commons. |
| `handle` | `string` | default `""` | Cross-reference handle (a home/workplace target: "tavern", "forge"). |
| `markup` | `number` | optional | Retail price multiplier over base worth (`MARKUP`); absent = ×1.0. |
| `name` | `string` | default `""` |  |
| `owned_by` | `string` | optional | An existing owner referenced by handle/name (a wage-earner's house). |
| `owner` | `Character` | optional | An owner-operator created WITH the venue (the brewer of the mash house). |
| `placement` | `Placement` | optional | Whether the venue is `LocatedIn` the ward or `AdjacentTo` it. |
| `rate_mod` | `number` | optional | Production-rate multiplier (`RATE_MOD`, rich grounds > 1.0); absent = ×1.0. |
| `requires` | `string[]` | default `[]` | Good handles this venue demands beyond its production inputs (`Requires` edges) — the keep's issue, a tavern's larder. Production and its input demands DERIVE from the building type's recipes now. |
| `stocks` | `Stock[]` | optional | Opening stored stacks (good handle + quantity). |
| `ward` | `string` | default `""` | The ward this venue sits in, by name (placed per `placement`). |

### Ward

A ward: its adjacencies, the keys it grants (regional common knowledge), and the laws it is subject to.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `adjacent_to` | `string[]` | default `[]` | Ward names this one is `AdjacentTo` (edge minted from THIS ward). |
| `grants` | `string[]` | default `[]` | Key ids this ward HOLDS (its residents share the knowledge). |
| `name` | `string` | default `""` |  |
| `subject_to` | `LawRef[]` | optional | Laws this ward is `SubjectTo`, each since a day. |