the-living-world/README.md

The Living World

A web game whose map is a real place. The backend pulls a square of OpenStreetMap data once, turns it into an ECS world, and serves it to a PixiJS client that renders it as a vector map.

This is the first iteration: world generation and rendering only, no gameplay yet.

Stack

Piece	Choice
Backend	.NET 10, ASP.NET Core minimal APIs
World model	Arch ECS
Map data	OpenStreetMap via the Overpass API
Frontend	PixiJS 8 + TypeScript + Vite
Orchestration	.NET Aspire 13
Storage	Plain files under data/

Running it

On Windows, double-click run.cmd or run it from a terminal:

run.cmd

Anywhere else, or if you prefer the CLI directly:

dotnet run --project src/TheLivingWorld.AppHost

Aspire starts the API, runs npm install for the client, launches the Vite dev server, and prints a dashboard URL. Open the web endpoint from the dashboard: the main menu lists existing worlds and lets you create a new one. Enter coordinates and press Generate world, then open a ready world to explore the map.

The default coordinates are Robert Lee, Texas (31.8966010, -100.4858591) — a small town that generates in a few seconds.

To run the two halves separately instead:

dotnet run --project src/TheLivingWorld.Api

npm --prefix src/TheLivingWorld.Web run dev

Tests — the backend under xUnit, the client under Vitest:

dotnet test

npm --prefix src/TheLivingWorld.Web test

The client tests cover the pure half of the renderer: geometry helpers, camera maths, layer ordering and the palettes. Modules that hold PixiJS values are deliberately kept out of them, which is why layers.ts imports Container as a type only and the container construction lives in mapView.ts — the ordering rules stay testable without a browser.

How a world is made

1. Fetch. OverpassClient posts one bounding-box query to Overpass and streams the response into data/osm-cache/<hash>.json. The hash covers the query text, so the same box is never downloaded twice and editing the query invalidates the cache. Public mirrors are tried in order, with retries.
2. Project. LocalProjection flattens WGS84 onto a metric plane centred on the requested point: X east, Y north, both in metres. Over a 20 km square the error stays under a metre, and distances are directly usable as game units — which Web Mercator would not give.
3. Import. OsmWorldBuilder reads each element's tags, decides what it is, and creates one ECS entity per feature. Multipolygon relations are stitched into rings by RingAssembler; everything is clipped to the world square by GeometryClipper, so a highway crossing town does not drag geometry 40 km off the map. Lines are then cut again at chunk boundaries — a road that spans the map becomes one entity per chunk it crosses, which is what keeps a chunk's extent close to its own square. Neighbouring pieces overlap by a metre and a half so the seam is covered rather than left as a hairline gap.
4. Systems. ComputeBoundsSystem fills each entity's extent, AssignChunksSystem buckets it into the chunk grid.
5. Export. ChunkExporter walks the ECS world and writes one JSON file per chunk, plus an index.

The ECS shape

Geometry does not live in components. ShapeStore holds the vertex arrays and components carry an integer handle, which keeps component data blittable and archetype chunks dense.

Component	Meaning
OsmSource	Which OSM element this came from
Outline / Holes	Closed ring and the rings cut out of it
Polyline	Open centreline, for roads and streams
Bounds / InChunk	Cached extent and spatial bucket, filled in by systems
Building	Kind, height, levels
Road	Class, width, lanes, bridge/tunnel/oneway flags
AreaFeature / Water	Land cover and water classification
DisplayName	The name tag

There are no simulation systems yet — the pipeline is the two passes above. Gameplay systems slot in beside them without reworking the data model.

HTTP API

Endpoint	Purpose
POST /api/worlds	Start generating a world. Returns immediately with status: "pending"; 409 when the slot budget is full
GET /api/worlds	{ worlds, maxConcurrentWorlds } — list plus the server slot budget, with live status for anything still generating
GET /api/worlds/{id}	Status of one world
GET /api/worlds/{id}/map	Metadata plus the chunk index
GET /api/worlds/{id}/chunks/{x}/{y}	One chunk of geometry
PATCH /api/worlds/{id}/clock	Pause / resume or set speed (timeScale 1–4). Body: { paused?, timeScale? }
DELETE /api/worlds/{id}	Remove a world and its chunks

Generation takes tens of seconds — mostly waiting on Overpass — so POST returns straight away and the client polls for status. Only one generation runs at a time, to stay a good citizen on the shared Overpass mirrors. The number of worlds that may exist at once is capped by WorldStorage:MaxConcurrentWorlds (today that means folders on disk; later the same budget will limit concurrent simulation).

Geometry travels as flat [x0, y0, x1, y1, …] arrays of world metres, which is exactly what PixiJS Graphics.poly() accepts, so the client never reshapes it. Responses are compressed; chunk files are written in wire format and streamed straight from disk.

The client

The app opens on a full-screen main menu: a list of worlds with a slot counter, the create form, and theme controls. Opening a ready world switches to the map screen (back button returns to the menu). PixiJS is initialised on first open and kept alive across visits.

MapView owns one scaled container holding the layer stack from layers.ts, plus a screen-space layer for place names above it. Camera is the only place the Y flip lives; everything else thinks in map coordinates.

Layers are global, not per chunk. Every chunk paints into the same ordered set of containers rather than into a container of its own. That is what makes junctions correct: with per-chunk containers the ordering would only hold inside a chunk, so a side street loaded after a trunk road would paint straight over it wherever the two meet. Roads are sorted into importance bands — tunnel, minor, local, secondary, major, bridge — and within each band every casing goes down before any fill, so the fills merge into one continuous surface. Land cover gets the same treatment in three bands: zoning blocks, natural cover, then parks and pitches.

ChunkManager fetches chunks as the camera reaches them and drops their graphics once they are well out of view, keeping the parsed data cached so panning back is instant. When a chunk is redrawn — a zoom step or a theme switch — the new set fades in over the old one rather than replacing it outright.

Detail thins out as you zoom away: footpaths disappear first, then small buildings, and stroke widths gain a floor so hairlines stay visible. At street level the map picks up the things that only read close up:

• buildings extrude, with walls drawn down from every footprint edge to a roof lifted by the building's height
• footways, paths, steps and cycleways switch to dashed lines so they never read as pale streets
• railways become a dark bed with light sleepers dashed over it
• one-way streets grow chevrons pointing the way traffic runs
• gentle bends in roads and watercourses are rounded off by Chaikin corner cutting; corners sharper than 50° are left alone, because a gridded town is full of genuine right angles

Place names are drawn in screen space so text keeps a constant size at every zoom, and the work is split in two. labelPlacement.ts decides which names to show: candidates are ranked — water bodies first, then arterials, then land cover, then side streets — and placed greedily, dropping anything that would overlap a label already placed, or any street name too long for the road it belongs to. Because a road is split across chunks, the pieces are folded back together by OSM id so a street gets one label rather than one per chunk. That pass runs on the same slow timer as chunk bookkeeping. LabelLayer then moves the chosen labels to follow the camera every frame, which is nearly free — without that split they lag a fast pan by up to a tenth of a second and snap back when the next placement lands.

Both palettes live in theme.ts and nothing else in the renderer names a colour. Switching theme changes the render profile key, which is the same signal a zoom change uses, so every loaded chunk redraws through the usual dissolve instead of a special case. The page chrome follows via a data-theme attribute.

Configuration

src/TheLivingWorld.Api/appsettings.json:

• WorldStorage:RootDirectory — where generated worlds go (default data/worlds)
• WorldStorage:MaxConcurrentWorlds — how many worlds may exist at once (default 8)
• Osm:Endpoints — Overpass mirrors, tried in order
• Osm:CacheDirectory — raw Overpass responses (default data/osm-cache)
• Osm:QueryTimeoutSeconds / Osm:RequestTimeoutSeconds — server-side and client-side budgets

Relative paths resolve against the API's content root. Everything under data/ is reproducible from coordinates and is not committed.

Known limits

• The Overpass response is parsed in one pass rather than streamed. Fine for the small towns this targets; a dense 20 km city would want a streaming reader.
• Lines are split at chunk boundaries, but polygons are not: a large forest or landuse block still belongs whole to the chunk holding the centre of its extent and overhangs its neighbours. The exported chunk bounds are widened to match and the client culls against those. Splitting polygons too would risk hairline seams between the filled pieces.
• Building extrusion is a flat fake — walls swept in one fixed direction, no perspective and no roof shapes.
• Labels are placed along a straight line at the middle of a road, not curved along its path, so a name on a sharply bending street sits at the average angle rather than following it.