sindicate 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 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.15.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/world/design.js

@@ -0,0 +1,72 @@
+// THE DESIGN STAMPER (designer v3) — renders a World Designer layout (designs/<name>.json,
+// authored in /designer.html by hand or by an MCP-driven session) into the live world.
+// MACHINE-WRITTEN LAYOUTS ARE JSON: { name, prefabs: [{ file, dir, x, y?, z, ry?, s?, tex? }],
+// roads: [[{x,z}, ...], ...] }.
+//
+// Same shape as the kit stamper's prop path: prefabs batch per (file|tex) into ONE
+// InstancedMesh each, on the shared townMaterial pipeline (one material per atlas,
+// lamp-lit). Placement seats on the game's ground through the heightAt option unless the
+// entry pins its own y.
+//
+// COLLISION IS THE BAKE'S BUSINESS: batches are named `scatter:` (solid — the world BVH
+// bake picks them up by name) or `scatterDeco:` (walk-through) via opts.solid. Stamping
+// AFTER world.build's bake gives no collision until the next bake — fine for a dev-flag
+// preview; the production path stamps designs before the bake, exactly like the towns.
+//
+// ROADS: not rendered here. A designer road is a ROUTE, and routes belong to the game's
+// terrain survey (road networks bench the ground, paint the surface and re-cook) — the
+// designer's road polylines feed that pipeline game-side; a painted-on decal would lie
+// about where the carriageway really is.
+import * as THREE from 'three/webgpu';
+import { loadModel } from '../core/assets.js';
+import { flattenToGeometry } from './scatter.js';
+import { townMaterial } from './kit.js';
+
+export async function buildDesign(scene, design, { heightAt = () => 0, solid = true, defaultTex = null } = {}) {
+  const byFile = new Map();   // `${dir}/${file}|${tex}` -> { url, tex, mats: [] }
+  const _p = new THREE.Vector3(), _q = new THREE.Quaternion(), _s = new THREE.Vector3();
+  const _up = new THREE.Vector3(0, 1, 0);
+  for (const e of design.prefabs ?? []) {
+    const bare = e.file.replace(/\.(fbx|glb)$/i, '');
+    const ext = e.ext ?? (/\.glb$/i.test(e.file) ? 'glb' : 'fbx');
+    const url = `${e.dir}/${bare}`;
+    e._url = `${url}.${ext}`;
+    const tex = e.tex ?? defaultTex;
+    const key = `${e._url}|${tex}`;
+    if (!byFile.has(key)) byFile.set(key, { url: e._url, tex, mats: [] });
+    byFile.get(key).mats.push(new THREE.Matrix4().compose(
+      _p.set(e.x, e.y ?? heightAt(e.x, e.z), e.z),
+      _q.setFromAxisAngle(_up, e.ry ?? 0),
+      _s.setScalar(e.s ?? 1),
+    ));
+  }
+  const meshes = [];
+  let count = 0, failed = 0;
+  for (const { url, tex, mats } of byFile.values()) {
+    try {
+      const master = await loadModel(url, tex ? { texture: tex } : {});
+      const flat = flattenToGeometry(master);
+      if (!flat) { failed++; continue; }
+      // textured prefabs ride the shared town pipeline (one material per atlas, lamp-lit);
+      // an untextured one gets a plain slate rather than crashing the whole batch pass
+      const mat = tex ? await townMaterial(tex, url) : new THREE.MeshStandardMaterial({ color: 0x9a938a, roughness: 0.9 });
+      const mesh = new THREE.InstancedMesh(flat.geometry, mat, mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = mats.length < 12;
+      mesh.receiveShadow = true;
+      const file = url.split('/').pop();
+      mesh.name = `${solid ? 'scatter' : 'scatterDeco'}:${file}`;
+      mesh.matrixAutoUpdate = false;
+      mesh.updateMatrix();
+      scene.add(mesh);
+      meshes.push(mesh);
+      count += mats.length;
+    } catch (e) {
+      failed++;
+      console.warn(`[design] prefab batch ${url} failed`, e?.message ?? e);
+    }
+  }
+  console.log(`[design] '${design.name ?? 'unnamed'}': ${count} prefabs in ${meshes.length} batches${failed ? ` (${failed} files failed)` : ''}${design.roads?.length ? ` · ${design.roads.length} road route(s) carried for the survey` : ''}`);
+  return { meshes, count, roads: design.roads ?? [] };
+}

package/src/world/heightfield.js

@@ -0,0 +1,146 @@
+// THE HEIGHTFIELD BUILDER (world splits, step 4) — the chunked terrain mesh + cook harness
+// both games carried byte-identically around their own paint and material:
+//
+//   · ONE height lattice (every vertex computed exactly once), chunk meshes aligned to it,
+//     normals from lattice CENTRAL DIFFERENCES so chunk borders cannot seam
+//   · THE TERRAIN COOK — the lattice fill is ~1.74M heightAt calls and the paint pass as
+//     many again, all deterministic: cooked to ONE self-writing bin
+//     [u32 hlen][JSON {ver,N} pad4][H f32 N²][sand u8 N²][paint u8 4/vert rgba-as-rgbs]
+//     fetched by NAME (the game bakes its content fingerprints into cookName, so stale
+//     bins 404 and re-cook), recorded back through the dev middleware on a cold boot
+//   · the SAND LATTICE (u8 N²) — the game's paint writes it, other systems (grass blade
+//     fields) query exactly what the ground shows; returned for the game's sandAt()
+//
+// The GAME supplies: heightAt, the cook name + ver, the node material, and makePaint —
+// a factory receiving { hAt, step, N, sandLattice } and returning the per-vertex painter
+// (x, z, h, li, lj, colors, sands, k), the exact signature both counties already use.
+import * as THREE from 'three/webgpu';
+
+export async function buildHeightfield({
+  worldSize, segments, chunkTarget = 360,
+  heightAt, cookName, cookVer,
+  material, makePaint,
+  saveRoute = '/__save-cookbin', cookRoute = '/assets/cook',
+}) {
+  const CHUNKS = Math.max(1, Math.round(worldSize / chunkTarget));
+  if (segments % CHUNKS !== 0) throw new Error(`segments ${segments} not divisible by ${CHUNKS} chunks`);
+  const CSEG = segments / CHUNKS;                  // segments per chunk side
+  const CSIZE = worldSize / CHUNKS;                // metres per chunk side
+  const STEP = worldSize / segments;               // lattice spacing
+  const N = segments + 1;                          // lattice verts per side
+
+  let cook = null;
+  try {
+    const r = await fetch(`${cookRoute}/${cookName}`);
+    if (r.ok) {
+      const buf = await r.arrayBuffer();
+      const hlen = new DataView(buf).getUint32(0, true);
+      const head = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, 4, hlen)));
+      if (head.N === N) {
+        let o = 4 + hlen;
+        cook = { H: new Float32Array(buf.slice(o, o + N * N * 4)) };
+        o += N * N * 4;
+        cook.sand = new Uint8Array(buf.slice(o, o + N * N));
+        o += N * N;
+        cook.paint = new Uint8Array(buf.slice(o));
+        console.log(`[terrain] COOKED lattice+paint from ${cookName} — heightAt/paint compute skipped`);
+      }
+    }
+  } catch (e) { console.warn('[terrain] cook bin missing/unreadable — falling back to the SLOW compute path (first boot after a VER bump is expected; repeated boots are not)', e?.message ?? e); }
+
+  // ---- height lattice: every terrain vertex height, computed once ----
+  const H = cook ? cook.H : new Float32Array(N * N);
+  if (!cook) {
+    for (let j = 0; j < N; j++) {
+      const z = -worldSize / 2 + j * STEP;
+      for (let i = 0; i < N; i++) H[j * N + i] = heightAt(-worldSize / 2 + i * STEP, z);
+    }
+  }
+  const hAt = (i, j) => H[Math.min(N - 1, Math.max(0, j)) * N + Math.min(N - 1, Math.max(0, i))];
+  const sandLattice = cook ? cook.sand : new Uint8Array(N * N);
+  const paintVertex = cook ? null : makePaint({ hAt, step: STEP, N, sandLattice });
+
+  // ---- build the chunk grid ----
+  const group = new THREE.Group();
+  group.name = 'terrain';
+  let chunkIdx = 0, vertsPerChunk = 0;
+  const recChunks = cook ? null : [];
+  for (let cj = 0; cj < CHUNKS; cj++) {
+    for (let ci = 0; ci < CHUNKS; ci++) {
+      const geo = new THREE.PlaneGeometry(CSIZE, CSIZE, CSEG, CSEG);
+      geo.rotateX(-Math.PI / 2);
+      const cx = -worldSize / 2 + (ci + 0.5) * CSIZE;             // chunk centre (mesh position)
+      const cz = -worldSize / 2 + (cj + 0.5) * CSIZE;
+      const pos = geo.attributes.position;
+      const colors = new Float32Array(pos.count * 3);
+      const sands = new Float32Array(pos.count);
+      const normals = geo.attributes.normal;
+      vertsPerChunk = pos.count;
+      for (let k = 0; k < pos.count; k++) {
+        const x = pos.getX(k) + cx, z = pos.getZ(k) + cz;
+        // lattice indices — chunk grids align exactly to the global lattice
+        const li = Math.round((x + worldSize / 2) / STEP);
+        const lj = Math.round((z + worldSize / 2) / STEP);
+        const h = hAt(li, lj);
+        pos.setY(k, h);
+        // normal from lattice central differences — identical on both sides of
+        // a chunk border (computeVertexNormals would seam: edge verts lack
+        // neighbour faces from the adjacent chunk). Cheap H arithmetic — always live.
+        const nx = -(hAt(li + 1, lj) - hAt(li - 1, lj)) / (2 * STEP);
+        const nz = -(hAt(li, lj + 1) - hAt(li, lj - 1)) / (2 * STEP);
+        const inv = 1 / Math.hypot(nx, 1, nz);
+        normals.setXYZ(k, nx * inv, inv, nz * inv);
+        if (cook) {
+          // cooked paint: 4 bytes/vert (r,g,b,sand) in chunk build order
+          const po = (chunkIdx * pos.count + k) * 4;
+          colors[k * 3] = cook.paint[po] / 255;
+          colors[k * 3 + 1] = cook.paint[po + 1] / 255;
+          colors[k * 3 + 2] = cook.paint[po + 2] / 255;
+          sands[k] = cook.paint[po + 3] / 255;
+        } else {
+          paintVertex(x, z, h, li, lj, colors, sands, k);
+        }
+      }
+      geo.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+      geo.setAttribute('aSand', new THREE.BufferAttribute(sands, 1));
+      recChunks?.push({ colors, sands });
+      chunkIdx++;
+      const mesh = new THREE.Mesh(geo, material);
+      mesh.position.set(cx, 0, cz);
+      mesh.receiveShadow = true;
+      mesh.name = `terrain:${ci},${cj}`;
+      group.add(mesh);
+    }
+  }
+  console.log(`[terrain] ${CHUNKS}x${CHUNKS} chunks (${CSIZE}m, ${CSEG}x${CSEG} segs each) — frustum-culled${cook ? ' · cooked' : ''}`);
+
+  // record mode: persist lattice + paint for the next boot (dev middleware writes the file)
+  if (recChunks) {
+    try {
+      let head = JSON.stringify({ ver: cookVer, N });
+      while ((head.length + 4) % 4) head += ' '; // 4-byte-align the Float32 payload
+      const hb = new TextEncoder().encode(head);
+      const paint = new Uint8Array(chunkIdx * vertsPerChunk * 4);
+      recChunks.forEach(({ colors, sands }, cIdx) => {
+        for (let k = 0; k < sands.length; k++) {
+          const po = (cIdx * sands.length + k) * 4;
+          paint[po] = Math.min(255, Math.round(colors[k * 3] * 255));
+          paint[po + 1] = Math.min(255, Math.round(colors[k * 3 + 1] * 255));
+          paint[po + 2] = Math.min(255, Math.round(colors[k * 3 + 2] * 255));
+          paint[po + 3] = Math.min(255, Math.round(sands[k] * 255));
+        }
+      });
+      const out = new Uint8Array(4 + hb.length + H.byteLength + sandLattice.byteLength + paint.byteLength);
+      const dv = new DataView(out.buffer);
+      dv.setUint32(0, hb.length, true);
+      out.set(hb, 4);
+      let o = 4 + hb.length;
+      out.set(new Uint8Array(H.buffer), o); o += H.byteLength;
+      out.set(sandLattice, o); o += sandLattice.byteLength;
+      out.set(paint, o);
+      fetch(`${saveRoute}?name=${cookName}`, { method: 'POST', body: out });
+      console.log(`[terrain] cooked → ${cookName} (${(out.length / 1048576).toFixed(1)}MB)`);
+    } catch (e) { console.warn('[terrain] cook save failed', e); }
+  }
+  return { group, sandLattice, N, step: STEP, cooked: !!cook };
+}