191 lines
10 KiB
Markdown
191 lines
10 KiB
Markdown
# 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](https://github.com/genaray/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:
|
||
|
||
```bash
|
||
run.cmd
|
||
```
|
||
|
||
Anywhere else, or if you prefer the CLI directly:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
dotnet run --project src/TheLivingWorld.Api
|
||
```
|
||
|
||
```bash
|
||
npm --prefix src/TheLivingWorld.Web run dev
|
||
```
|
||
|
||
Tests — the backend under xUnit, the client under Vitest:
|
||
|
||
```bash
|
||
dotnet test
|
||
```
|
||
|
||
```bash
|
||
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.
|