jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(decisions): D-191 §8 canonical markers.json format is pixel space

Browse Source 
The generator and the hand-authored templates (Edict, Vuurkloof, Røros,
Cairnside, Estrade) already store markers in heightmap pixel space with
a grid header. Update §8 to match: {x, y} integer pixels are the storage
format, and lat/lon strings become a display-time derivation in the
atlas UI (synthesized from position + grid dimensions + body radius).

Avoids double-conversion through an equirectangular projection and keeps
the hand-authored markers.json files as-is.
This commit is contained in:
jpmschweitzer
2026-04-14 17:30:37 +02:00
parent b127f63dc2
commit d6d3b51098
1 changed files with 4 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
decisions/architecture.md
+4 -2
View File
@@ -710,7 +710,9 @@ Technical foundation decisions that constrain implementation: engine, client-ser
- Maps to D-181 signal visibility ladder
**8. Settlement Data Model**
- 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
- markers.json is stored in heightmap pixel space — every marker file declares a `grid: { w, h }` header (the heightmap dimensions, typically `1024 × 512`) and every position is `{ x, y }` integer pixels into that grid. This is the canonical storage format used by both the generator and the hand-authored template files (Edict, Vuurkloof, Røros, Cairnside, Estrade). Pixel space is what the heightmap analysis (flood-fill, A* cost grid, city placement) natively operates on; it is deterministic and avoids double-conversion through a projection.
- markers.json schema per body: `grid: {w, h}`, `cities` (name, pos `{x,y}`, population_tier, primary_function, gate_terminal, continent_id), `roads` (path polylines as `[{x,y}, ...]`, connects), `railroads` (path polylines, connects), `pois` (name, kind, pos), plus existing rivers/oceans/mountains with names filled
- Lat/lon strings are a **display-time derivation**, not a storage format. The atlas UI converts `{x, y}` + `grid: {w, h}` into an equirectangular `lat°N/S, lon°E/W` string for the city data panel and hover tooltips, using the body's radius for any great-circle distances it needs. This keeps the immersive surface without paying conversion cost in the generator, the DB, or the diff churn on hand-authored files.
- 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
@@ -737,4 +739,4 @@ Technical foundation decisions that constrain implementation: engine, client-ser
---
*53 decisions. Last updated: 2026-04-10 (D-191 Atlas of the Reach — Phase 3 scope and pipeline)*
*53 decisions. Last updated: 2026-04-14 (D-191 §8 — markers.json canonical format is pixel space `{x, y}` with a `grid: {w, h}` header; lat/lon is a display-time derivation)*