sindicate 0.13.0 → 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+## 0.16.0 — driving on it
+
+### A car (new: `vehicle/`)
+
+- `vehicle/car.js` — a wheel at each corner asking the world for its own ground, so pitch,
+  roll and hanging a wheel over an edge all fall out of it. Spring-damped suspension, a
+  power-limited engine (0–60 in 4.6 s, not 0–123 in three), brakes, and a handbrake that
+  genuinely breaks grip: the body points one way and travels another when it slides. It also
+  owns where to probe for obstacles and what to do about a hit — the game only answers a ray.
+- `vehicle/carAudio.js` — the classic four-loop engine: acceleration and deceleration at low
+  and high revs, crossfaded by revs and throttle, with tyres that protest in proportion to
+  the slide.
+
+The header of `car.js` lists the faults it exists to prevent, each found the hard way: a body
+snapped to the ground is glued to it; an airborne test against one frame of gravity flickers
+on contact noise and sags the car to a crawl; one ray down the nose lets the body pass through
+anything not hit head-on; a rail alongside must never bleed speed.
+
+### Roads as a world-build step
+
+- `world/roadWorld.js` — one call that runs the road build in the only order that works and
+  hands back a `heightAt` for `buildHeightfield`, geometry to stamp before the BVH bake, and
+  the solved network. Site, seat each piece at ITS grade, wrap the ground with pads, THEN
+  generate links over that padded ground, then wrap again with their corridors.
+- `world/roadAssert.js` — what must be true of a road world: no ground above a road, no road
+  floating over a gap, every link meeting both sockets, every link drivable at its grade,
+  every junction seated on its own ground. Cheap enough for every cold build. It found three
+  real faults on its first run.
+- `world/roadNetwork.js` — `planLoop`/`loopTangents` for closed circuits.
+- `world/roadLink.js` — `buildDeck`, and rail lines (median and shoulders) reported with the
+  pitch of the ground they sit on.
+- `world/roadTerrain.js` — the ground now guarantees it never sits above a road, pads fade
+  into the landscape rather than ending at a rim, `heightAt.road`/`heightAt.deck` answer where
+  the driveable surface is, and the whole wrapper is bucketed (25× → 10.7× over bare terrain
+  across a 1.7 M-vertex lattice).
+
+### Tools
+
+- `tools/unityPackageExtract.mjs` — pull named assets out of a `.unitypackage` without staging
+  the whole thing.
+- `tools/fbxToGlb.mjs`, `tools/roadKitAnalyze.mjs`, `tools/buildKiwiRoadsPack.mjs`.
+
+### Fixed
+
+- **Trains ran beside the track, not on it.** `train.js` still reached for a county's railway
+  data through `import.meta.glob`, which inside the engine resolves against the engine's own
+  folder and finds nothing — so the fleet silently graded its own polyline. The solved survey
+  goes in through `setTrainContent`.
+
+## 0.15.0 — the world-building release
+
+Everything between the last published version (0.13.0) and here. 0.14.0 was bumped in the
+repo but never published, so its contents ship as part of this release.
+
+### The world, split out of the games (0.14.0's work)
+
+The terrain and stamper machinery both games carried privately now belongs to the engine, and
+each game keeps only its own content:
+
+- `world/geo.js` — the noise/curve toolkit (fbm, ridged, terrace, segDist, smoothstep).
+- `world/railFormation.js` — the rail solver: max-grade Lipschitz envelopes and vertical curves.
+- `world/bridgeSplice.js`, `world/waterLevels.js`, `world/waterMeshes.js` — bridges and water.
+- `world/heightfield.js` — the chunked terrain mesh and its cook (one height lattice, central-
+  difference normals so chunk borders cannot seam, cooked to a single self-writing bin).
+- `world/kit.js` — the kit registries, doors and ladders, `setKitContent`, `buildArea`,
+  `buildTown`, `dressTownCenter`.
+- `world/placement.js` — the cook, samplers, resident kits and occupancy.
+- `world/worldBase.js` — the world facade's engine half, with eight hooks a game fills in.
+- `world/permanentWay.js` — the track-laying machinery.
+
+### The World Designer
+
+- `tools/designer.js` + `tools/devPlugin.js` — a visual editor over the game's real terrain:
+  place, move and remove prefabs, draw road polylines, fly the camera, save to JSON.
+- `tools/designer-mcp.mjs` — an MCP server so a Claude session can drive the designer while
+  you watch it.
+- `world/design.js` — `buildDesign()`, the layout-JSON → live-scene bridge.
+
+### The road system (new)
+
+Junctions are rigid prefab pieces; the roads between them are generated. Both halves, plus the
+earthworks that make the ground agree with them:
+
+- `world/roadKit.js` — reads a pack's measured kit. Lanes are stored by which side of the
+  centre line they sit on, so **left/right-hand drive is a runtime switch**, not baked data.
+  `gradeLevel`/`seatY` sink a multi-level junction until the roads that meet the outside world
+  are at ground level.
+- `world/roadLink.js` — the road between two sockets: a cubic Bezier through both arms'
+  tangents so seams are tangential, cross-sections matching each socket's measured width and
+  paint, and a vertical profile squeezed into the reachable-at-max-grade envelope then relaxed
+  into vertical curves. Connecting is non-negotiable: if two sockets cannot be joined within
+  the requested grade the road still meets both ends and reports `feasible: false`.
+- `world/roadTerrain.js` — pads under junctions, cut/fill corridors under links, both using a
+  batter slope so a road crossing a valley gets an embankment that reaches it. `pickSites` and
+  `pickManySites` put junctions on the flats.
+- `world/roadNetwork.js` — sites in, road system out: a spanning tree plus a few short extra
+  links so the map has loops, and for each site the junction piece and rotation whose arms best
+  face the neighbours it must serve.
+
+### Pack tooling
+
+- `tools/unityMeshToGlb.mjs`, `tools/unityPrefabToAssembly.mjs`, `tools/truthToAssemblies.mjs`,
+  `tools/fbxToGlb.mjs`, `tools/roadKitAnalyze.mjs`, `tools/buildKiwiRoadsPack.mjs` — recovering
+  a Unity road library into an engine pack: meshes, Unity-resolved transforms and materials,
+  per-file FBX import scale, measured sockets and cross-sections.
+- `tools/ExportKiwiRoadMaterials.cs`, `tools/ExportKiwiRoadRefs.cs` — the Unity-side exports.
+
+### Notes
+
+- `world/roadGraph.js` (A\* routing for the map) and the road piece system are different
+  things that share a word.
+- The road modules are new and may still move before 1.0.
+
+## 0.13.0
+
+World splits steps 1–3a; the package catalog and one-click install.

package/docs/plans/kiwi-road-recon.md

@@ -0,0 +1,97 @@
+# Kiwi Road System — Recon & Re-Implementation Brief (for Sindicate/three.js)
+
+> Recon of /Users/nick/Desktop/Kiwi (Unity). Kiwi runs TWO parallel road systems:
+> **A) City grid roads** — Manhattan grid of cardinal segments built from prefab junction
+> pieces + ONE repeated 2.5m straight prefab, a procedural "curved road" mesh overlay, and
+> EasyRoads3D-style terrain benching. **B) Inter-city roads** — procedural spline-extruded
+> meshes (motorway/dual carriageway/country) + generated-then-saved interchange prefabs
+> (roundabouts, overpass, dumbbell). For Sindicate, A's prefab+socket+junction logic and
+> the benching are the model; B is math to mine, not to copy.
+
+## 1. Piece taxonomy + sockets
+- Junction prefabs (TerrainGeneratorWindow_CityJunctions.cs:25-31): Junction_4Way/T/LCorner
+  (City_Simpligon + Countryside variants). City straight: RoadSegment_Simpligon (2.5m).
+- Synty source pieces referenced (POLYGON City/Town kit): Road_01/02/03, Straight_01/02/03,
+  Corner_01/02, Corner_End_03, Road_Crossing_01, Road_Flyover_01(+_Support), Road_Bare_01,
+  Road_Lines_01, Road_YellowLines_02; props Barrier_01, HighwayGuardrail, signs.
+- Interchanges are GENERATED then saved as prefabs (InterCityRoadWindow.cs:48-52, 964-1188).
+- **Kiwi has NO true smallest-cut piece set** — one straight + junction prefabs + curved
+  overlay. Turn/ramp/grade PIECES are net-new design for Sindicate.
+- Sockets, simple form (RoadConnectorPoints.cs:46-177): child anchors named Connector_*;
+  road runs along local +Z; Connector_A at minZ (back), Connector_B at maxZ (front), at
+  road-surface height (mesh maxY), x=0. Junctions: Connector_{N,S,E,W} at ±JUNCTION_RADIUS.
+- Rich form — ADOPT THIS (Runtime/Roads/JunctionConnectionPoints.cs:15-50):
+  ConnectionPoint { armId "N"/"S"/"E"/"W"/...; local position (road-width centre at arm
+  end); outward direction; RoadType {CountryRoad, SideRoad, DualCarriageway, Motorway};
+  laneCount; speedLimit }.
+
+## 2. Network data model
+- ONE constant drives everything (ManhattanGridGenerator.cs:48-65): BLOCK_SIZE=50m →
+  ROAD_PIECE_LENGTH=2.5m, JUNCTION_SIZE=20m, junction spacing 0.4–1.2×block; gates
+  WATER_LEVEL=5m, MAX_SLOPE=22.5°.
+- Serialized graph (CityData.cs): CityData { junctions[], roadSegments[], blocks[],
+  rawRoads[], seed }; JunctionData { id, position(incl terrain Y), JunctionType
+  {DeadEnd,Straight,TJunction,Crossroads,Complex}, connectedRoadIds, rotationY,
+  flattenRadius }; RoadSegmentData { start/endJunctionId, width, roadType, length,
+  heightDifference, splineWaypoints }. JSON-exported (_Cities.cs:2554).
+- Runtime graph (RoadNetworkBuilder.cs): RoadNode merged within 1m; type classified purely
+  by CONNECTION COUNT (:184-208).
+
+## 3. Placement math
+- Grid gen (ManhattanGridGenerator.Generate :412-667): population flood-fill (cells =
+  pop/200), per-cell water/slope reject, per-edge span validity sampled every ~5m,
+  dead-end → perpendicular ray → nearest road → T connector (:791-888), merge verticals,
+  largest-connected-component BFS filter (:673-778).
+- Turns: the grid is CARDINAL-ONLY (±5°); curvature comes from the procedural curved-mesh
+  overlay along a straight→quadratic-bézier→straight "blue spline" (SampleModifiedSpline,
+  _Cities.cs:1640-1682) — because Kiwi lacks turn pieces.
+- Piece fitting: numPieces = floor(dist/pieceLength), walk by pieceLength, orient by
+  LookRotation(direction), Y from terrain +0.1 (_Cities.cs:1559-1637).
+- SplinePlacer.cs VARIABLE-SIZE mode (:123-253): grow a piece until tangent deviation
+  exceeds angleDeviance (3°), then CUT and scale the piece to the chord — the template for
+  turn-aware smallest-cut placement.
+- Weld trick TO AVOID: clone each piece mesh, flatten back edge, SnapVerticesToTargets to
+  the junction's edge verts (_Cities.cs:1863-2062) — incompatible with InstancedMesh.
+- Grades: cities are BENCHED (junction at avg terrain height in its box, :248-285; steep
+  segments REJECTED not ramped). Only inter-city splines carry true 3D elevation.
+
+## 4. Terrain stamping
+- FlattenTerrainUnderCurvedRoads (…_CityTerrainFlattening.cs:35-352): ROAD_BED_OFFSET=1m,
+  INDENT_WIDTH=2m, SURROUNDING_WIDTH=3m. Extract road footprint POLYGONS (vert rings →
+  left/right edge lists with per-ring heights, :357-457) + junction polygons (72 angular
+  sectors +1m, :462-535); 50m spatial grid; per heightmap pixel: inside → per-edge
+  INTERPOLATED roadHeight − offset (grade preserved), indent → edge height − offset, skirt
+  → smoothstep back to terrain. Cut AND fill; region-partial writes; pixel-error 2.
+- TerrainStamp.cs: R-channel heightmap stamps with blend modes (cliffs/mesas, not roads).
+
+## 5. Junction resolution (_CityJunctions.cs:36-404)
+- Tally cardinal connections (±5°): 4 → 4-way rot 0°; 3 → T rotated so the MISSING arm
+  faces north (:257-260); 2 opposite → two back-to-back straight pieces (first keeps the
+  junction's load-bearing name); 2 perpendicular → L-corner rotated by present dirs
+  (:289-293); 1 → dead-end straight; 0 → marker. Junction mesh bottom seated at avg
+  terrain height. Names "City_X_Junction_Y" are parsed by road placement (load-bearing).
+
+## 6. Editor UX
+- TerrainGeneratorWindow (partial class over ~15 files): Preview Cities → Generate per
+  city: ExportCityDataToJson → PlaceJunctionsAndFlattenTerrain → ClearGrassInCity →
+  PlaceRoadsAndFlattenTerrain → RoadSplineEditor blue-lines → CurvedRoadMeshGenerator →
+  FlattenTerrainUnderCurvedRoads → diagnostics. InterCityRoadWindow: tabbed per road type,
+  straight/spline gen, per-type + batch prefab saving.
+
+## 7. Copy vs avoid for Sindicate
+COPY: centralized config; cardinal grid pipeline (flood-fill, gating, dead-end→T,
+largest-component); the RICH socket model (armId+pos+dir+roadType+laneCount) with socket
+transforms precomputed per prefab type; floor(dist/len) fitting + SplinePlacer
+angle-deviance cutting; junction resolution by connection count + 90° rotation; EasyRoads
+benching (indent+skirt, cut+fill, per-edge interpolated heights); CityData-style JSON.
+AVOID: per-instance mesh cloning/vert snapping (author pieces so sockets meet EXACTLY on a
+shared grid instead); three overlapping road systems (pick prefab pieces, add REAL
+turn/ramp pieces); bench-only grades (Sindicate wants ramps — and already owns better
+grade math: the rail formation solver); /tmp logging in loops; per-piece MeshColliders;
+RoadPieceData prefab hacks.
+
+Key files: ManhattanGridGenerator.cs, CityData.cs, RoadConnectorPoints.cs,
+JunctionConnectionPoints.cs, TerrainGeneratorWindow_{Cities,CityJunctions,
+CityTerrainFlattening,InterJunctionRoads}.cs, CurvedRoadMeshGenerator.cs,
+RoadNetworkBuilder.cs, SplinePlacer.cs, PROCEDURAL_MAP_GENERATOR_PLAN.md (Phase 8 §4729,
+postmortems §8336-8420).

package/docs/plans/road-system.md

@@ -0,0 +1,142 @@
+# SINDICATE PREFAB ROADS — design for Nick's review (NO CODE UNTIL SIGNED OFF)
+
+> Nick: "roads using prefabs too where we cut the smallest bit of them to allow drawing
+> them in in single instances etc and allow turns and uphill downhill with them etc."
+> Foundation: docs/plans/kiwi-road-recon.md (what Kiwi proved + what it never solved).
+
+## The one-system rule (Kiwi's lesson #1)
+
+Kiwi grew three overlapping road systems because its grid had no real turn pieces.
+Sindicate builds ONE: a PIECE GRAPH — typed prefab pieces joined socket-to-socket,
+rendered as InstancedMesh batches (one per piece type), never editing geometry per
+instance. Pieces are AUTHORED to mate exactly; welding-by-vertex-snap is banned.
+
+## 1. The piece library (per road kit, registered like setKitContent)
+
+A game registers a ROAD KIT — content, not engine:
+```js
+setRoadKit({
+  dir, atlas,
+  pieces: {
+    straight: [{ file, len }],            // several lengths; shortest = the CUT quantum
+    corner:   [{ file, radius, angle }],  // 90° (and 45° where the pack has one)
+    tee: { file }, cross: { file },
+    ramp: [{ file, len, rise }],          // grade variants (see §4)
+    endcap: { file },
+  },
+  width, surfaceY,                        // measured off the meshes once
+  props: { barrier, lamp, sign... },      // optional dressing hooks
+})
+```
+- GTA game: POLYGON_City kit (Kiwi's own source pieces — Road_01/Straight_01/Corner_01/
+  Road_Crossing_01/Flyover_01 family).
+- Fable: no modern roads in Fantasy Kingdom — its "roads" stay the painted/benched
+  terrain lanes we have (the survey), optionally dressed with the pack's cobble/path
+  floor pieces later. The piece system is for kits that HAVE road prefabs.
+- Western: stays on painted dirt roads (correct for 1880).
+
+Sockets are NOT hand-authored: at kit registration the engine measures each piece
+(bounds; road along local +Z; back socket at minZ, front at maxZ, surface at maxY —
+Kiwi's convention) and builds { armId, pos, dir, laneCount } tables per type.
+
+## 2. The network model (designer-facing)
+
+The DESIGNER draws what Kiwi called blue lines: polylines + junction nodes, per road
+type. The layout JSON stores INTENT, the solver output stores RESULT:
+```js
+roadsV2: {
+  nodes: [{ id, x, z }],                       // junction/endpoint nodes
+  links: [{ a, b, type, via: [{x,z}...] }],    // optional via = curve hints
+}
+// solved (cached in the cook, not hand-edited):
+// pieces: [{ type, file, x, y, z, ry, pitch, sz }...] + junction placements
+```
+
+## 3. The solver (engine — the new module, world/roadGraph.js)
+
+1. NODE RESOLUTION (Kiwi §5, copy): count links per node → cross/tee/corner/straight-
+   through/endcap piece + 90°-stepped rotation (T's missing arm rule verbatim).
+2. LINK FITTING: between the two junction sockets, walk the (optionally curved) path
+   with the SplinePlacer law: grow the current straight until tangent deviation > A°
+   (tunable, Kiwi used 3°), cut, place the LONGEST library straight that fits, repeat;
+   remainder < shortest straight → stretch the last piece via sz (the permanentWay
+   adaptive-panel trick — same batch, z-scale in the matrix). Corners consume their
+   authored arc; curve hints (via points) become corner+straight sequences.
+3. GRADES (Sindicate's advantage — Kiwi never solved this): the link's vertical profile
+   comes from solveFormation (rail solver: max-grade Lipschitz envelopes + vertical
+   curves), pieces pitch via makeChordMatrix (yaw→pitch→z-scale — sleepers stay level,
+   Kiwi had nothing like it). Ramp pieces are selected when |grade| exceeds what a
+   pitched straight reads well at; junction pads are LEVEL (yards law).
+4. OUTPUT: per-type matrix lists → panelBatch (scatterDeco road surface — walk-over law)
+   + collision stays the benched terrain; junction pieces placed like castings.
+
+## 4. Terrain: the road benches the ground (Kiwi §4 + our survey)
+
+The solved centreline + width feeds the SAME machinery our rails use: applyRail-style
+corridor blend to the piece profile (bed = surfaceY − offset), Kiwi's indent+skirt
+(2m flat, 3m smoothstep) as the cross-section, cut AND fill, into heightAt → the
+heightfield/zones cooks re-fingerprint (roadsV2 hash joins the cook names). The ground
+is the road, the pieces dress it — the lesson the railway already proved.
+
+## 5. Designer UX (v4)
+
+- ROAD MODE v2: click nodes/links instead of raw polylines; type picker; live solver
+  preview (pieces appear as you draw, junction pieces swap as links connect).
+- MCP: designer_road_node / designer_road_link / designer_road_solve.
+- Layout JSON carries roadsV2; buildDesign stamps solved pieces; graduation to a game
+  feeds the centrelines into setRoadNetwork for the benching + cook.
+
+## 6. Build order (after sign-off)
+
+1. roadGraph.js solver core (nodes→junction resolution, link fitting, chord matrices) —
+   provable headless (piece counts + junction types on synthetic networks).
+2. POLYGON_City import + road-kit registration + a test design stamped in a scratch
+   scene (this is also the GTA game's first world artifact).
+3. Benching integration (roadsV2 → survey corridor → cook re-fingerprint).
+4. Designer road mode v2 + MCP verbs.
+
+## Open questions for Nick
+- OK that fable/western keep terrain-painted roads (piece roads = City pack era)?
+- Corner radii: lock to the pack's authored radius only (simplest), or also synthesize
+  gentle curves from short straights at deviance-cut angles (Kiwi's overlay did this —
+  more flexible, more math)?
+- Junction sprawl: POLYGON_City has flyovers/supports — v1 scope flat junctions only,
+  flyovers later?
+
+## 7. Direct salvage from Kiwi (Nick: "there are bits you could take out to reuse ofc")
+
+**Algorithms — port near-verbatim (C# → JS is mechanical):**
+- SplinePlacer.cs variable-size loop (:123-253) → the link-fitting cutter in roadGraph.js.
+- ManhattanGridGenerator flood-fill + water/slope gating + dead-end→ray→T + largest-
+  component filter → the AUTO-CITY-GRID generator (a designer "generate district" verb —
+  the GTA game's city blocks for free).
+- _CityJunctions junction-count→piece+rotation table (incl. the missing-arm-north rule).
+- _CityTerrainFlattening footprint-polygon bench (rings→edge lists, indent+skirt,
+  per-edge interpolated heights) → the survey corridor cross-section.
+- SampleModifiedSpline straight→bézier→straight blend → curve hints between nodes.
+- JunctionConnectionPoints data model (armId/pos/dir/roadType/laneCount/speedLimit).
+
+**Assets — the tuned meshes themselves (need ONE Unity export pass):**
+- Junction_{4Way,T,LCorner}_City_Simpligon + RoadSegment_Simpligon are Nick's own
+  tuned pieces, stored as Unity .asset meshes (Road/Markings/Sidewalk sub-meshes per
+  junction — the sub-mesh split is EXACTLY our flattenToGeometry split convention).
+- The generated interchange prefabs (SimpleRoundabout_01, OverpassRoundabout, Dumbbell
+  variants in Prefabs/Roads/) are real saved meshes — a whole interchange library.
+- ASK NICK: open Kiwi in Unity once and export these to FBX (adapt the existing
+  Editor/ExportMyAssets.cs, or the FBX Exporter package) → we import them as a
+  "KiwiRoads" pack through the pack importer and the road kit is instantly armed with
+  proven pieces + interchanges. ~10 minutes of Unity time buys the whole piece library.
+
+**Data:** BLOCK_SIZE-derived constant table; RoadType/laneCount/speedLimit enums.
+
+## 8. The rest of AIGenerateMap (Nick: "and the other bits too ofc")
+
+Beyond roads, the Kiwi world-builder code to mine (all plain C#, no Unity needed):
+- ManhattanGridGenerator + CityData → designer "generate district" verb (city blocks).
+- TerrainStamp (blend-mode heightmap stamps) + VoronoiNoise + FalloffGenerator → port
+  into engine geo.js (Voronoi + stamps are real gaps; fbm family already ours).
+- Terrain/Vegetation/GrassDecorator (+Configs) → config-shape inspiration for our
+  placement/flora systems (machinery stays ours).
+- TerrainTextureApplicator + colormaps → heightfield paint reference.
+- InterCityRoadWindow spline/interchange generation → mined per-need for the solver.
+- NewMapConfig/GeneratedTerrainData assets → GTA-game map parameter reference.

package/docs/plans/three-cities.md

@@ -0,0 +1,43 @@
+# THE THREE CITIES RUN — Nick's founding request for the World Designer
+
+> "come up with a huge map with 3 cities 6 towns and road networks between them all
+> using the prefabs from the packs"
+
+## The pipeline (all pieces SHIPPED as of 0.14)
+
+1. **Author** — an MCP-driven Claude session drives `/designer.html` on fable (5317)
+   through the `aldenvale-designer` tools (place/move/road/camera/save) while the human
+   watches; or write the JSON directly (it is the same artifact). Layouts save to
+   `fable/designs/<name>.json`.
+2. **Preview** — boot `?autostart&design=<name>`: engine `buildDesign()` stamps the
+   layout live (visual-only, post-BVH).
+3. **Integrate** — stamp the accepted designs in `world.build()` BEFORE the BVH bake
+   (collision + grass occupancy for free), and feed the design `roads` polylines into
+   the terrain survey (`setRoadNetwork`) so the ground benches under them → re-cook.
+
+## Authoring facts
+
+- Palette: POLYGON_Fantasy_Kingdom, 2,186 models. The `SM_Bld_Preset_*_Optimized`
+  composites are WHOLE dressed buildings — cities assemble from these, not wall pieces.
+  Atlas: `PolygonFantasyKingdom_Texture_01_A.png` (every entry carries `tex`).
+- Layout entry: `{ file, dir, x, z, ry, y?, s?, tex }`; omit `y` to seat on terrain.
+- World: 4320 m square, Aldenvale relief is real — site cities on the flats
+  (designer viewport shows the relief; check `heightAt` spread before committing a site).
+- Existing settlements to respect (never overlap): Oakhollow (0,14 r~90), the castle
+  (1120,800), Bracklow, VILLAGES/CAMPS lists, Ironkeep (DWARF), Ravenspire (-1400,-1200).
+- Compass: north = −z. Roads: polylines in `roads`, ≥12 m from any building
+  (the farm-rect law), gentle bends (the survey benches them).
+
+## Suggested sites (from the relief + the existing map)
+
+- City A: the plain SE of Oakhollow (~500, 400) — river-adjacent, flat.
+- City B: the western meadows (~-900, 300).
+- City C: the north coast road (~300, -1100).
+- Six towns strung on the road net between them + the existing villages as waypoints.
+- Budget: city ≈ 40-70 presets + walls/props; town ≈ 12-20. Total ≈ 350 placements —
+  trivial for the stamper (49k placements cook in seconds).
+
+## Definition of done
+
+Every city/town saved as its own design file (composable), one master road list,
+preview screenshots of each site, Nick signs the look before integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",
@@ -29,7 +29,8 @@
     "src",
     "tools",
     "docs",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "three": "^0.184.0",

package/src/systems/train.js

@@ -38,6 +38,13 @@ export function setTrainContent(c = {}) {
   if (c.colliders) colliders = c.colliders;
   if (c.dropItemsFor) dropItemsFor = c.dropItemsFor;
   if (c.railPaths) SURVEY_PATHS = c.railPaths;
+  // THE TRACK AUTHOR'S OWN SURVEY. Without it the fleet grades its own polyline and runs
+  // beside the rails the county actually laid.
+  if (c.railLines) LINES_IN = c.railLines;
+  if (c.railLineStops) STOPS_IN = c.railLineStops;
+  if (c.levelCrossing) XING_IN = c.levelCrossing;
+  if (c.junction) JUNC_IN = c.junction;
+  if (c.railTop != null) { RAIL_TOP = c.railTop; RAIL_Y = RAIL_TOP - FLANGE; }
   if (c.railStops) SURVEY_STOPS = c.railStops;
   if (c.crossing !== undefined) SURVEY_CROSSING = c.crossing;
   if (c.halts) RAIL_HALTS = c.halts;
@@ -89,18 +96,21 @@ import { attachTrainCamera } from './trainCamera.js';
 const _mods = import.meta.glob(['../world/railway.js', '../world/data/railway.js'], { eager: true });
 const RD = _mods['../world/data/railway.js'] ?? {};
 
-const LINES_IN = RD.RAIL_LINES ?? null;         // { main: {nodes,len}, spur: {nodes,len} }
-const STOPS_IN = RD.RAIL_STOPS ?? null;         // [{ id, name, line, s, platformSide, wait }]
-const XING_IN = RD.LEVEL_CROSSING ?? null;      // { line, s, x, z }
-const JUNC_IN = RD.JUNCTION ?? null;            // { line, s, x, z }
+// ...and inside the ENGINE that glob resolves against the engine's own folder, where no
+// county's railway data lives — so these MUST be injectable. A game hands its solved survey
+// to setTrainContent; the glob remains for a game that still keeps train.js's neighbours.
+let LINES_IN = RD.RAIL_LINES ?? null;           // { main: {nodes,len}, spur: {nodes,len} }
+let STOPS_IN = RD.RAIL_STOPS ?? null;           // [{ id, name, line, s, platformSide, wait }]
+let XING_IN = RD.LEVEL_CROSSING ?? null;        // { line, s, x, z }
+let JUNC_IN = RD.JUNCTION ?? null;              // { line, s, x, z }
 
 // The railhead above the formation — his number, not mine. A car's origin sits at RAILHEAD CONTACT
 // (measured: min.y = 0 on all four models), so this is exactly how high off the ballast it rides,
 // less a flange: the wheel's lowest point is its flange, not its tread, and standing the tread ON
 // the rail is what closes the hairline of daylight under a stationary loco.
-const RAIL_TOP = RD.RAIL_TOP ?? 0.3285;
+let RAIL_TOP = RD.RAIL_TOP ?? 0.3285;
 const FLANGE = 0.06;
-const RAIL_Y = RAIL_TOP - FLANGE;
+let RAIL_Y = RAIL_TOP - FLANGE;
 
 // ── THE FALLBACK ROUTE (only if data/railway.js has not landed) ───────────────────────────────
 const FALLBACK_PATHS = [