diff --git a/decisions/architecture.md b/decisions/architecture.md index 1c1f8a34d..f04be03d3 100644 --- a/decisions/architecture.md +++ b/decisions/architecture.md @@ -714,6 +714,7 @@ Technical foundation decisions that constrain implementation: engine, client-ser - Maps to D-181 signal visibility ladder **8. Settlement Data Model** + - **Amendment (2026-05-22, [D-223](#d-223)):** superseded — markers.json is reduced to **names only** (a flavored name pool); it no longer carries position arrays or topographic-feature geometry. River/mountain positions derive from the heightmap + drainage (D-208); settlement positions from the economic sim + placement (D-211). The 6 hand-authored templates and their `reserved` pinning are removed (bodies stay as ordinary named bodies). The pixel-space schema below is retained as historical reference only. - **Amendment (2026-04-15):** The original §8 (below) described marker positions as lat/lon objects and city records keyed by `population_tier`/`primary_function`/`gate_terminal`/`continent_id`. That shape was aspirational — neither the generator nor the hand-authored templates ever emitted it. Both ended up writing pixel-space row/col arrays against a `512 × 256` storage grid, and PR #129 canonizes that shape so the code and the decision stop drifting. The original prose is preserved immediately below; the current shape follows. - **Original (2026-04-10, superseded):** markers.json schema per body: `cities` (name, lat/lon, population_tier, primary_function, gate_terminal, continent_id), `roads` (path polylines, connects), `railroads` (path polylines, connects), `pois` (name, kind, position), plus existing rivers/oceans/mountains with names filled. Population tier → city count: `floor(log10(pop/1M))`, modified by `settlement_pattern`. Gate terminal POI at largest population center, sometimes scattered to a smaller one. Moons: same depth as planets, scale with population. - **Current canonical format:** markers.json is stored in heightmap pixel space. Every marker file declares a `grid: { w, h }` header — the generator, the 6 hand-authored templates (Lendel, Edict, Vuurkloof, Røros, Cairnside, Estrade), and all 2394 procedural seed files ship `{"w": 512, "h": 256}`. Every position is a two-element **array** `[row, col]` of integer pixels into that grid, where `row ∈ [0, h)` and `col ∈ [0, w)` (row is the first axis to match NumPy convention and the flood-fill / A* / cost-grid code that `tooling/planet-gen/` already runs in). Polyline geometry (`roads[*].path`, `railroads[*].path`, `rivers[*].path`) is `[[row, col], [row, col], ...]`. @@ -1009,6 +1010,7 @@ Technical foundation decisions that constrain implementation: engine, client-ser ### D-207: Fully Generative Placement — markers.json Stripped to Topographic Features - **Date:** 2026-05-01 +- **Amendment (2026-05-22, [D-223](#d-223)):** superseded in part. markers.json no longer retains topographic-feature *geometry* — it is reduced to **names only** (a flavored name pool). River/mountain positions are derived from the heightmap + drainage (D-208); settlement positions come from the economic sim + placement (D-211). The `reserved=1` pinning and the 6 hand-authored templates (Lendel, Edict, Vuurkloof, Røros, Cairnside, Estrade) are removed — their bodies remain as ordinary named bodies, only the authored machinery is gone. See D-223. - **Decision:** The `atlas_city_names` table replaces the authored city positions in `markers.json`. Going forward, `markers.json` files contain only topographic features (rivers, oceans, mountain ranges — per D-191 §8 canonical format). City positions, road networks, and rail networks are NOT authored in `markers.json`; they are generated from the terrain data and stored in `atlas_city_names` and derived tables. ```sql CREATE TABLE atlas_city_names ( @@ -1411,4 +1413,27 @@ Technical foundation decisions that constrain implementation: engine, client-ser --- -*82 decisions (D-001 through D-222, excluding gaps). Last updated: 2026-05-22 (D-222 — Spatial hierarchy and naming)* +### D-223: Authored content as a flavored name pool — markers names-only, hand-authored templates removed +- **Date:** 2026-05-22 +- **Decision:** Per-planet authored content feeds the deterministic generator as a **flavored name pool only** — never as authored geometry or pinned positions. This supersedes the topographic-geometry retention and the `reserved=1` pinning of [D-207](#d-207-fully-generative-placement--markersjson-stripped-to-topographic-features), and the hand-authored-template references in [D-191](#d-191) §8. + + **markers.json → names only.** A body's `markers.json` carries a flavored pool of names (river names, mountain names, settlement names) and **no positions or geometry**. Positions are not authored anywhere; they are derived or generated: + - **Rivers** — courses come from the deterministic D8 drainage (D-208) on the fixed heightmap; the **largest rivers take names from the pool**. + - **Mountains** — positions are a given from the **fixed heightmap**; they take names from the pool. + - **Settlements** — the economic sim runs, the **largest population areas** are found, the capital and cities are picked by the placement pipeline (D-211), and they **take names from the pool**. + + **The 6 hand-authored templates are removed.** Lendel, Edict, Vuurkloof, Røros, Cairnside, Estrade were a superseded hand-authored-showcase direction that kept resurfacing and complicated the landscape. Their hand-authored marker positioning, the `reserved=1` pinning, and the "6 templates" framing/special-casing are all removed. **The bodies themselves remain real places** — their wiki pages, lore, corporations (e.g. comptoir-lendel), and names stay and feed the name pool; deleting them would only force regenerating equivalent content. Only the authored *machinery* is tossed. **After this there is no distinguishable category of "template" left** — the six are processed by the exact same pipeline and data model (fixed heightmap + names-only markers) as every other body, with no special code path, schema flag, or pinning. They differ only in *content richness* (more developed lore/names/economic profile), which is a difference of degree shared by any notable body, not a difference of kind. The concept dissolves; that is why it can be removed wholesale rather than carefully migrated. + + **No pinned positions anywhere.** Determinism comes from fixed heightmaps + deterministic drainage + deterministic economic sim + seeded placement — not from authored anchors. The lore-vs-code split (D-222) governs how pool names attach to generated features: names are free-form labels on generated geometry, not bound to grid cells. + + Sub-city authored set-pieces (e.g. D-093 Sova Transit District, station interiors) follow the same principle when Phase 4 reaches that scale — generated geometry, lore names/roles attached, nothing pinned — to be applied (and prior authored layouts superseded) at that point. + +- **Rationale:** Authored positions created a hand/procedural split that (per D-207's own rationale) was impossible to query, diff, or validate. Reducing authored content to a name pool removes that split entirely while preserving the flavor that makes places feel hand-made — names follow culture and region, geometry follows terrain and economics. The templates were leftover scaffolding from before fully-generative placement; removing them simplifies the pipeline without losing any canonical place. +- **Implementation:** tracked under Phase 4 (epic #750) — strip markers to names, remove template machinery + `reserved` pinning, update the atlas pipeline/schema, regen. Historical archives (sprints, workshops, audits, CHANGELOG, atlas proposals) are left untouched. +- **Raised by:** Jeroen, 2026-05-22 — resolving the open question on merging preconfigured content into the deterministic cascade. +- **Cross-reference:** [D-207](#d-207-fully-generative-placement--markersjson-stripped-to-topographic-features) (superseded — names-only, no reserved pinning), [D-191](#d-191) §8 (markers format — names-only), [D-208](#d-208) (drainage → river courses), [D-211](#d-211) (settlement placement), [D-199](#d-199) (economic read set), [D-222](#d-222) (lore≠code names on generated geometry) +- **Dissent:** None + +--- + +*83 decisions (D-001 through D-223, excluding gaps). Last updated: 2026-05-22 (D-223 — Authored content as a flavored name pool)*