sindicate 0.16.0 → 0.17.0

package/src/world/cityPlan.js

@@ -0,0 +1,500 @@
+// A CITY IS A STREET NETWORK, AND A BLOCK IS A HOLE IN IT.
+//
+// This is Kiwi's model, brought over: a settlement is a grid of streets laid on ground flat
+// enough to take them, the faces enclosed by those streets are BLOCKS, each block is zoned,
+// and buildings fill the blocks. Kiwi got as far as the blocks — its `BlockData` carries the
+// comment "For building placement later" and nothing ever filled them. `settlement.js` is
+// that later.
+//
+//   const city = planCity({ centre: { x: 0, z: 0 }, population: 12000, groundAt: ground });
+//   city.streets   // [{ a, b, width, kind }]  centrelines between junctions
+//   city.junctions // [{ x, y, z, arms, type, yaw }]  where streets meet, benched
+//   city.blocks    // [{ polygon, centre, area, zone }]  what the streets enclose
+//   const heightAt = makeRoadTerrain(ground, city.earthworks);
+//
+// WHY A GRID AND NOT NOISE. A city read from above is legible: you can see where you are
+// because the streets agree with each other. Scattered buildings on winding paths read as
+// woodland with houses in it. The grid is what makes it a town.
+//
+// TERRAIN IS A VETO, NOT A SUGGESTION (Kiwi's rule): a cell whose ground is under water or
+// steeper than a street can climb is not built on, so a city grows along its valley and stops
+// at the hillside rather than paving over it. Population then decides how many of the cells
+// that pass actually get used.
+import { lcgRng } from './permanentWay.js';
+
+export const CITY_DEFAULTS = {
+  blockSize: 50,            // Kiwi's BLOCK_SIZE — everything else derives from it
+  streetWidth: 10,          // kerb to kerb — the kit's city junctions are authored for this
+  avenueWidth: 10,          // the kit has ONE street width, so an avenue is a name, not a size
+  junctionSize: 20,         // Kiwi's JUNCTION_SIZE, and the City junction pieces' footprint
+  pavement: 5,              // the footway between the kerb and the buildings, each side
+  latticeClear: 8,          // margin beyond the section — must exceed a terrain lattice cell
+  waterLevel: 5,            // below this is water and cannot be built on
+  maxSlope: 0.16,           // a cell this steep will not hold a level block
+  maxStreetGrade: 0.08,     // 8% — what a street actually climbs, not what one can survive
+  relax: 60,                // passes of the grade relaxation below
+  peoplePerBlock: null,     // Kiwi's rate was 200 at its 50 m block — see below
+  population: 8000,
+  maxRadius: 900,           // a hard stop, whatever the population asks for
+  bench: 1.0,               // Kiwi's ROAD_BED_OFFSET. A tenth of this is what I had, and on a
+                            // terrain lattice several metres across the interpolation between
+                            // two vertices eats 12 cm of clearance without noticing.
+  fade: 5,                  // Kiwi's INDENT_WIDTH 2 + SURROUNDING_WIDTH 3
+  blockFade: 5,             // one block's bench easing into its neighbour's
+  batter: 3.5,              // metres of skirt per metre of fill — how gently it comes down
+  seed: 1,
+};
+
+const key = (i, j) => `${i},${j}`;
+
+// WHICH PIECE STANDS HERE, AND WHICH WAY ROUND. Kiwi classified a junction purely by how
+// many streets met at it, and so does this. The kit's pieces are authored with a fixed set of
+// arms — a 4-way has all four, a T is missing its north arm, an L-corner keeps east and south
+// — so the rotation is whatever best lines those up with the streets that actually arrive.
+//
+// TRY ALL FOUR AND SCORE, rather than deriving the angle. A derivation has a special case per
+// piece and gets one of them backwards; scoring cannot, and costs sixteen cosines.
+export const PIECE_ARMS = {
+  cross: [0, Math.PI / 2, Math.PI, -Math.PI / 2],   // N E S W
+  tee: [Math.PI / 2, Math.PI, -Math.PI / 2],        // E S W — the missing arm is north
+  corner: [Math.PI / 2, Math.PI],                   // E S
+};
+
+function fitPiece(arms, type) {
+  const want = PIECE_ARMS[type];
+  if (!want) return { piece: null, yaw: arms[0] ?? 0 };
+  let best = { yaw: 0, score: -Infinity };
+  for (let k = 0; k < 4; k++) {
+    const yaw = (k * Math.PI) / 2;
+    let score = 0;
+    for (const a of arms) {
+      score += Math.max(...want.map((w) => Math.cos(a - (w + yaw))));
+    }
+    if (score > best.score) best = { yaw, score };
+  }
+  return { piece: type, yaw: best.yaw };
+}
+
+// WHAT THE GROUND WILL TAKE. Sampled at the cell's corners and centre: a cell that straddles
+// a stream bank has a fine average and is still unbuildable.
+function cellSlope(cx, cz, r, groundAt, cfg) {
+  const at = [
+    [cx, cz], [cx - r, cz - r], [cx + r, cz - r], [cx - r, cz + r], [cx + r, cz + r],
+  ].map(([x, z]) => groundAt(x, z));
+  if (Math.min(...at) < cfg.waterLevel) return null;
+  const slope = (Math.max(...at) - Math.min(...at)) / (r * 2);
+  return { y: at.reduce((a, b) => a + b, 0) / at.length, slope };
+}
+
+function cellUsable(cx, cz, r, groundAt, cfg) {
+  const s = cellSlope(cx, cz, r, groundAt, cfg);
+  return s && s.slope <= cfg.maxSlope ? s.y : null;
+}
+
+// Kiwi kept two rejection registers, and the distinction is the useful part: a cell rejected
+// for SLOPE could be recovered by flattening the terrain, a cell rejected for WATER could not.
+function cellWet(cx, cz, r, groundAt, cfg) {
+  return cellSlope(cx, cz, r, groundAt, cfg) == null;
+}
+
+export function planCity({ centre = { x: 0, z: 0 }, groundAt = () => 0, ...opts } = {}) {
+  const cfg = { ...CITY_DEFAULTS, ...opts };
+  const B = cfg.blockSize;
+  // HOW MANY PEOPLE A BLOCK HOLDS SCALES WITH ITS AREA. Kiwi's figure was 200 for its own
+  // 50 m block; carried over unchanged to an 80 m block it asks for two and a half times the
+  // blocks the population needs, and the town reports itself two thirds short of a demand
+  // that was never real.
+  const perBlock = cfg.peoplePerBlock ?? 200 * (B / 50) ** 2;
+  const want = Math.max(4, Math.round(cfg.population / perBlock));
+  const reach = Math.min(cfg.maxRadius, Math.sqrt(want / Math.PI) * B * 1.6);
+  // LOOK FURTHER THAN THE TOWN WILL NEED. If the ground it wants is half hillside, a search
+  // stopping at the ideal radius hands back half a city; searching wider lets the same
+  // population spread along the flat instead, which is what a real town on a valley floor
+  // does. The frontier is nearest-first, so a town with good ground all round stays compact.
+  const span = Math.ceil(Math.min(cfg.maxRadius, reach * 2.2) / B);
+  const scan = span * B;
+
+  // 1. WHICH CELLS THE LAND ALLOWS
+  const usable = new Map();
+  for (let i = -span; i <= span; i++) {
+    for (let j = -span; j <= span; j++) {
+      const cx = centre.x + i * B, cz = centre.z + j * B;
+      if (Math.hypot(cx - centre.x, cz - centre.z) > scan) continue;
+      const y = cellUsable(cx, cz, B / 2, groundAt, cfg);
+      if (y != null) usable.set(key(i, j), { i, j, x: cx, z: cz, y });
+    }
+  }
+
+  // 2. HOW MANY OF THEM GET BUILT ON — grow outward from the middle, taking only cells that
+  //    touch what is already town, so a city is one place and not a rash of hamlets.
+  const seedCell = usable.get(key(0, 0))
+    ?? [...usable.values()].sort((a, b) => (a.i ** 2 + a.j ** 2) - (b.i ** 2 + b.j ** 2))[0];
+  const built = new Map();
+  if (seedCell) {
+    const frontier = [seedCell];
+    const queued = new Set([key(seedCell.i, seedCell.j)]);
+    while (frontier.length && built.size < want) {
+      // nearest-first, so the town fills in rather than growing a tentacle
+      frontier.sort((a, b) => Math.hypot(a.x - centre.x, a.z - centre.z) - Math.hypot(b.x - centre.x, b.z - centre.z));
+      const c = frontier.shift();
+      built.set(key(c.i, c.j), c);
+      for (const [di, dj] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+        const k = key(c.i + di, c.j + dj);
+        if (usable.has(k) && !queued.has(k)) { queued.add(k); frontier.push(usable.get(k)); }
+      }
+    }
+  }
+
+  // 3. THE STREETS ARE THE CELL EDGES, and a street too steep to climb is not built.
+  //
+  //    THIS IS KIWI'S RULE, and it is the one that matters. Kiwi benched each junction at the
+  //    average terrain height in its own box, then measured the grade BETWEEN JUNCTION
+  //    HEIGHTS — "this is the actual slope the built road will have" — and rejected the road
+  //    outright if it was too steep, recording the cell as one that terrain flattening might
+  //    recover later. Grading each block against its own patch of hillside and then joining
+  //    them up regardless is what produces a town full of ski jumps.
+  //
+  //    So: bench, measure, drop the cell, and do it again, because dropping a cell changes
+  //    the average at every corner it touched and can make a neighbour too steep in turn.
+  let corners, rejectedForSlope = 0;
+  const cornersOf = (cells) => {
+    const map = new Map();
+    const at = (i, j) => {
+      const k = key(i, j);
+      if (!map.has(k)) {
+        map.set(k, { i, j, x: centre.x + (i - 0.5) * B, z: centre.z + (j - 0.5) * B, y: 0, arms: [], n: 0 });
+      }
+      return map.get(k);
+    };
+    for (const c of cells.values()) {
+      for (const q of [at(c.i, c.j), at(c.i + 1, c.j), at(c.i, c.j + 1), at(c.i + 1, c.j + 1)]) {
+        q.y += c.y; q.n++;
+      }
+    }
+    for (const q of map.values()) if (q.n) q.y /= q.n;
+    return { map, at };
+  };
+  const edgesOf = (c, at) => {
+    const c00 = at(c.i, c.j), c10 = at(c.i + 1, c.j), c01 = at(c.i, c.j + 1), c11 = at(c.i + 1, c.j + 1);
+    return [[c00, c10], [c10, c11], [c11, c01], [c01, c00]];
+  };
+  for (let pass = 0; pass < 24; pass++) {
+    const { map, at } = cornersOf(built);
+    const drop = [];
+    for (const c of built.values()) {
+      const steep = edgesOf(c, at).some(([a, b]) =>
+        Math.abs(a.y - b.y) / (Math.hypot(b.x - a.x, b.z - a.z) || 1) > cfg.maxStreetGrade);
+      if (steep) drop.push(key(c.i, c.j));
+    }
+    corners = map;
+    if (!drop.length) break;
+    // never take the last of it: a city reduced to nothing is worse than a slightly steep one
+    if (built.size - drop.length < 4) break;
+    for (const k of drop) { built.delete(k); rejectedForSlope++; }
+  }
+
+  // 3b. ONE PLACE, NOT SEVERAL. Dropping cells can cut the town in half; Kiwi finished its
+  //     grid with a largest-connected-component filter, and so does this.
+  if (built.size) {
+    const seen = new Set();
+    let biggest = [];
+    for (const start of built.values()) {
+      const k0 = key(start.i, start.j);
+      if (seen.has(k0)) continue;
+      const group = [], queue = [start];
+      seen.add(k0);
+      while (queue.length) {
+        const c = queue.pop();
+        group.push(c);
+        for (const [di, dj] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+          const k = key(c.i + di, c.j + dj);
+          if (built.has(k) && !seen.has(k)) { seen.add(k); queue.push(built.get(k)); }
+        }
+      }
+      if (group.length > biggest.length) biggest = group;
+    }
+    const keep = new Set(biggest.map((c) => key(c.i, c.j)));
+    for (const k of [...built.keys()]) if (!keep.has(k)) built.delete(k);
+  }
+
+  // 3bb. FILL THE HOLES. A cell the slope gate refused, with town on three sides of it, is not
+  //      countryside — it is a crater, and a town with craters in it reads as bomb damage.
+  //      This is the recovery Kiwi described and never wrote: it tracked slope-rejected cells
+  //      separately from water-rejected ones precisely because "cells rejected due to slope
+  //      COULD be flattened" to make the population back up. Water still cannot be filled.
+  //      The cell takes its level from the neighbours that enclose it, so the earthworks make
+  //      up the difference and the streets around it already agree with each other.
+  let recovered = 0;
+  for (let pass = 0; pass < 8; pass++) {
+    const add = [];
+    for (const c of built.values()) {
+      for (const [di, dj] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+        const i = c.i + di, j = c.j + dj, k = key(i, j);
+        if (built.has(k) || add.some((q) => q.i === i && q.j === j)) continue;
+        const around = [[1, 0], [-1, 0], [0, 1], [0, -1]]
+          .map(([ai, aj]) => built.get(key(i + ai, j + aj))).filter(Boolean);
+        if (around.length < 3) continue;
+        const x = centre.x + i * B, z = centre.z + j * B;
+        if (cellWet(x, z, B / 2, groundAt, cfg)) continue;      // water is not recoverable
+        add.push({ i, j, x, z, y: around.reduce((a, q) => a + q.y, 0) / around.length });
+      }
+    }
+    if (!add.length) break;
+    for (const c of add) { built.set(key(c.i, c.j), c); recovered++; }
+  }
+  corners = cornersOf(built).map;
+
+  const cornerAt = (i, j) => corners.get(key(i, j)) ?? { i, j, x: centre.x + (i - 0.5) * B, z: centre.z + (j - 0.5) * B, y: 0, arms: [], n: 0 };
+  const streets = new Map();
+  for (const c of built.values()) {
+    const c00 = cornerAt(c.i, c.j), c10 = cornerAt(c.i + 1, c.j);
+    const c01 = cornerAt(c.i, c.j + 1), c11 = cornerAt(c.i + 1, c.j + 1);
+    for (const [a, b] of [[c00, c10], [c10, c11], [c11, c01], [c01, c00]]) {
+      const k = a.i < b.i || (a.i === b.i && a.j < b.j)
+        ? `${a.i},${a.j}|${b.i},${b.j}` : `${b.i},${b.j}|${a.i},${a.j}`;
+      if (!streets.has(k)) streets.set(k, { a, b });
+    }
+  }
+
+  // 3b. AND THEN FLATTEN THEM INTO A CITY. Averaging the terrain under each block
+  //     independently gives every block its own level and every street between two of them
+  //     whatever grade the hillside happened to have — which on rolling ground is a set of
+  //     ramps no street in the world climbs. A city on a slope is TERRACED: each junction
+  //     sits at a height that differs from its neighbours' by no more than a street can
+  //     climb, and the earthworks make up the difference.
+  //
+  //     Same Lipschitz envelope the railway formation uses, run over the street graph
+  //     instead of along a line: repeatedly pull the two ends of any over-steep street
+  //     toward each other until none is left. It converges because every pass strictly
+  //     reduces the worst violation, and it settles near the terrain because that is where
+  //     it started.
+  const edges = [...streets.values()].map((s) => ({
+    a: s.a, b: s.b, len: Math.hypot(s.b.x - s.a.x, s.b.z - s.a.z) || 1,
+  }));
+  for (let pass = 0; pass < cfg.relax; pass++) {
+    let worst = 0;
+    for (const e of edges) {
+      const limit = e.len * cfg.maxStreetGrade;
+      const d = e.a.y - e.b.y;
+      const over = Math.abs(d) - limit;
+      if (over <= 0) continue;
+      worst = Math.max(worst, over);
+      const shift = (over / 2) * Math.sign(d);
+      e.a.y -= shift;
+      e.b.y += shift;
+    }
+    if (worst < 0.01) break;
+  }
+
+  // 4. JUNCTIONS: what meets here decides which piece stands here (Kiwi classified purely by
+  //    connection count, and so does this).
+  for (const s of streets.values()) {
+    const ang = (from, to) => Math.atan2(to.x - from.x, to.z - from.z);
+    s.a.arms.push(ang(s.a, s.b));
+    s.b.arms.push(ang(s.b, s.a));
+  }
+  const junctions = [];
+  for (const q of corners.values()) {
+    if (!q.arms.length) continue;
+    const arms = q.arms.slice().sort((x, y) => x - y);
+    // TWO ARMS IS NOT ONE CASE. Kiwi branches on WHICH two (_CityJunctions.cs): two opposite
+    // arms are a street running straight through and get back-to-back straights, two
+    // PERPENDICULAR arms are a corner and get the L-piece. Mapping arm count straight to a
+    // name — as this did — means a corner is never produced at all, so at every turn in the
+    // grid the ribbons simply stop and nothing joins them round.
+    const opposed = arms.length === 2 && Math.cos(arms[0] - arms[1]) < -0.5;
+    const type = arms.length >= 4 ? 'cross'
+      : arms.length === 3 ? 'tee'
+      : arms.length === 2 ? (opposed ? 'through' : 'corner')
+      : arms.length === 1 ? 'end' : 'none';
+    const fit = fitPiece(arms, type);
+    q.piece = fit.piece;                          // remembered so the streets know where to stop
+    junctions.push({ x: q.x, y: q.y, z: q.z, arms, type, ...fit, size: cfg.junctionSize });
+  }
+
+  // 5. AND THE BLOCKS — for a grid the faces are the cells themselves, inset by the streets
+  //    around them. Zoned by how central they are: offices downtown, houses at the edge.
+  const rng = lcgRng(cfg.seed * 104729 + built.size);
+  const half = B / 2;
+  // zone against the town that EXISTS: a city that had to sprawl has its downtown at the
+  // middle of what got built, not at the middle of what it hoped for
+  const spread = Math.max(B, ...[...built.values()].map((c) => Math.hypot(c.x - centre.x, c.z - centre.z)));
+  const blocks = [];
+  for (const c of built.values()) {
+    // A BLOCK NEVER STANDS ABOVE THE STREETS AROUND IT. Its own terrain average would undo
+    // the relaxation; the average of its corners still leaves it proud wherever the two
+    // streets it sits between are lower than the two it does not, and then its paving stands
+    // over the carriageway with a lip you can see from the air. The LOWEST corner is the only
+    // height that cannot do that: the block tucks under every street that touches it.
+    const own = [cornerAt(c.i, c.j), cornerAt(c.i + 1, c.j), cornerAt(c.i, c.j + 1), cornerAt(c.i + 1, c.j + 1)];
+    c.y = Math.min(...own.map((q) => q.y));
+    const central = Math.hypot(c.x - centre.x, c.z - centre.z) / spread;
+    const wide = central < 0.3 ? cfg.avenueWidth : cfg.streetWidth;
+    // A BLOCK STOPS AT THE BACK OF THE PAVEMENT, not at the kerb. Inset by the carriageway
+    // alone and the buildings stand in the gutter with nowhere to walk — which is what a city
+    // with no footways looks like, and it looks wrong before you can say why.
+    const in_ = half - wide / 2 - cfg.pavement;
+    blocks.push({
+      centre: { x: c.x, y: c.y, z: c.z },
+      polygon: [[c.x - in_, c.z - in_], [c.x + in_, c.z - in_], [c.x + in_, c.z + in_], [c.x - in_, c.z + in_]],
+      area: (in_ * 2) ** 2,
+      street: wide,
+      pavement: cfg.pavement,
+      zone: central < 0.28 ? 'downtown' : central < 0.55 ? 'commercial' : central < 0.85 ? 'residential' : 'industrial',
+      rank: central,
+    });
+  }
+  // one square with nothing on it: every town has somewhere to stand
+  if (blocks.length > 6) blocks[Math.floor(rng() * Math.min(4, blocks.length))].zone = 'park';
+
+  // 6. THE EARTHWORKS, ready for makeRoadTerrain: a bench under each block and a corridor
+  //    under each street. Same machinery the inter-city roads use — a city street is a road.
+  //    A BLOCK'S BENCH MUST STOP AT ITS OWN BOUNDARY. Made the full width of the cell it
+  //    reaches to the middle of every street around it, so each half of a street is benched
+  //    to a different block's level and the carriageway has a step down its centre line —
+  //    metres of it where the town is terraced. The street belongs to its own corridor.
+  //
+  //    And a fade is for the edge of town, not for the inside of it: eased over thirty metres
+  //    every interior block would drag its neighbours' levels back toward raw hillside,
+  //    putting the ground above the pavement it was cut for. Interior blocks ease over a few
+  //    metres into the block next door; only the edge of town blends into the countryside.
+  const neighbours = (c) => [[1, 0], [-1, 0], [0, 1], [0, -1]]
+    .filter(([di, dj]) => built.has(key(c.i + di, c.j + dj))).length;
+
+  // HOW FAR THE GROUND NEEDS TO GET BACK DOWN. Kiwi's skirt is a fixed 3 m because Kiwi never
+  // fills much: it REJECTS a cell it cannot sit on. This relaxes instead, terracing the city
+  // so it keeps cells Kiwi would have thrown away — and where the land falls away from a
+  // terrace, that is an embankment several metres tall. A fixed skirt then leaves it standing
+  // as a cliff with the ground overhanging at the edge of town.
+  //
+  // So the skirt is the fill it has to lose, laid back at `batter`. A block sitting level with
+  // its own ground keeps the short skirt; one holding up six metres of fill gets the width to
+  // come down at a walkable slope.
+  const skirtFor = (c) => {
+    const fill = c.y - groundAt(c.x, c.z);
+    return Math.max(neighbours(c) === 4 ? cfg.blockFade : cfg.fade, Math.abs(fill) * cfg.batter);
+  };
+  const earthworks = {
+    pads: [...built.values()].map((c) => {
+      const b = blocks.find((q) => q.centre.x === c.x && q.centre.z === c.z);
+      const inset = (B - (b?.street ?? cfg.streetWidth)) / 2;
+      return {
+        x: c.x, z: c.z, y: c.y, yaw: 0,
+        halfX: inset, halfZ: inset, drop: cfg.bench,
+        fade: skirtFor(c),
+      };
+    }),
+    corridors: [...streets.values()].map((s) => ({
+      // the corridor uses the FULL span: the ground has to be right under the junction too,
+      // and wide enough to meet the block benches on either side with nothing left between
+      centreline: [[s.a.x, s.a.y, s.a.z], [s.b.x, s.b.y, s.b.z]],
+      // WIDER THAN THE SECTION BY MORE THAN ONE LATTICE CELL. A street is not just its
+      // carriageway — the ribbon carries a kerb, a footway and a verge either side — and
+      // clearing that by a metre or two is still not enough: the terrain is DRAWN as a
+      // lattice, and between two vertices that straddle the edge of the cut the mesh
+      // interpolates straight across, riding over the kerb even though the height function
+      // it was sampled from never does. Every analytic probe says clean and the picture
+      // still shows grass over the pavement. Clear the whole section by a good margin.
+      halfWidth: cfg.streetWidth / 2 + cfg.pavement + cfg.latticeClear,
+      drop: cfg.bench, batter: 0.6,
+    })),
+  };
+
+  // 7. WHERE A ROAD OUT OF TOWN ATTACHES. A junction on the edge of the grid has a cardinal
+  //    arm with no street on it, pointing at open country — that is a socket, in the same
+  //    shape the road kit uses, so an inter-city link can be built to it with no special case.
+  //    Kiwi never did this: its inter-city window was a manual tool you typed two points into,
+  //    so nothing ever joined a town to the road that passes it.
+  const CARDINAL = [[0, [0, 1]], [Math.PI / 2, [1, 0]], [Math.PI, [0, -1]], [-Math.PI / 2, [-1, 0]]];
+  const exits = [];
+  for (const j of junctions) {
+    if (j.arms.length >= 4) continue;
+    for (const [ang, dir] of CARDINAL) {
+      if (j.arms.some((a) => Math.cos(a - ang) > 0.99)) continue;   // a street already uses it
+      // and it must face OUT of town, or a link leaves through the middle of the place
+      if ((j.x - centre.x) * dir[0] + (j.z - centre.z) * dir[1] < spread * 0.15) continue;
+      exits.push({
+        id: `exit_${exits.length}`,
+        pos: [j.x + dir[0] * cfg.junctionSize / 2, j.y, j.z + dir[1] * cfg.junctionSize / 2],
+        dir, width: cfg.streetWidth, kind: 'road',
+        lanes: [{ side: 'L', width: cfg.streetWidth / 2 }, { side: 'R', width: cfg.streetWidth / 2 }],
+        junction: j,
+      });
+    }
+  }
+
+  return {
+    centre: { x: centre.x, z: centre.z },
+    radius: +spread.toFixed(1),
+    exits,
+    population: cfg.population,
+    blocks,
+    junctions,
+    // A STREET RUNS BETWEEN THE PIECES, NOT THROUGH THEM. The junction prefab already owns
+    // its own twenty metres of tarmac; a ribbon drawn corner to corner would lie on top of it
+    // and the two would fight for the same pixels all the way across the town.
+    streets: [...streets.values()].map((s) => {
+      const dx = s.b.x - s.a.x, dz = s.b.z - s.a.z;
+      const L = Math.hypot(dx, dz) || 1;
+      // ONLY where a piece stands. A straight-through corner has no prefab on it — Kiwi laid
+      // two back-to-back straights there and this kit has none — so the ribbon must run
+      // through it unbroken or the street has a hole in the middle of the tarmac.
+      const cut = Math.min(cfg.junctionSize / 2, L / 2 - 1);
+      const ta = s.a.piece ? cut : 0, tb = s.b.piece ? cut : 0;
+      // MEET THE JUNCTION AT THE JUNCTION'S HEIGHT. A junction piece is a flat slab seated at
+      // its corner's level, so its arm ends at that level however the street beyond it
+      // climbs. Interpolating the height along the trim starts the ribbon ten metres in at a
+      // height the piece never reaches — on an 8% street that is a 0.8 m step at every arm,
+      // which is exactly what it looks like. The grade belongs to the span BETWEEN the
+      // pieces; the ends are the pieces' own.
+      const lerp = (k, y) => [s.a.x + (dx / L) * k, y, s.a.z + (dz / L) * k];
+      return {
+        a: lerp(ta, s.a.y), b: lerp(L - tb, s.b.y),
+        full: [[s.a.x, s.a.y, s.a.z], [s.b.x, s.b.y, s.b.z]],
+        width: cfg.streetWidth,
+        kind: Math.hypot((s.a.x + s.b.x) / 2 - centre.x, (s.a.z + s.b.z) / 2 - centre.z) < spread * 0.3 ? 'avenue' : 'street',
+      };
+    }),
+    earthworks,
+    // how much of what the population asked for the land actually allowed — a city squeezed
+    // into a valley is a fact worth reporting, not a silent shortfall
+    demand: want,
+    supply: built.size,
+    rejectedForSlope,
+    recovered,
+    // the steepest street the plan ended up with, so a caller can see the relaxation worked
+    grade: +Math.max(0, ...[...streets.values()].map((s) =>
+      Math.abs(s.a.y - s.b.y) / (Math.hypot(s.b.x - s.a.x, s.b.z - s.a.z) || 1))).toFixed(4),
+  };
+}
+
+// Where a city should stand: flat, dry, and not on top of the last one.
+export function pickCitySites(groundAt, { count = 3, half = 900, step = 120, minGap = 700, ...opts } = {}) {
+  const cfg = { ...CITY_DEFAULTS, ...opts };
+  const scored = [];
+  for (let x = -half; x <= half; x += step) {
+    for (let z = -half; z <= half; z += step) {
+      const here = cellSlope(x, z, cfg.blockSize * 1.5, groundAt, cfg);
+      if (!here || here.slope > cfg.maxSlope) continue;
+      // HOW MUCH GOOD GROUND IS WITHIN A TOWN'S REACH, scored on a continuum rather than
+      // counted. A tally ties everywhere on gentle terrain and the winner is then whichever
+      // corner of the map the loop happened to visit first; flatness has to be a number.
+      let good = 0;
+      for (let a = 0; a < 8; a++) {
+        const th = (a / 8) * Math.PI * 2;
+        for (const r of [120, 260, 400]) {
+          const s = cellSlope(x + Math.cos(th) * r, z + Math.sin(th) * r, cfg.blockSize / 2, groundAt, cfg);
+          if (s && s.slope <= cfg.maxSlope) good += 1 - s.slope / cfg.maxSlope;
+        }
+      }
+      scored.push({ x, y: here.y, z, good: +good.toFixed(3), slope: +here.slope.toFixed(3) });
+    }
+  }
+  scored.sort((a, b) => b.good - a.good);
+  const out = [];
+  for (const s of scored) {
+    if (out.length >= count) break;
+    if (out.every((o) => Math.hypot(o.x - s.x, o.z - s.z) >= minGap)) out.push(s);
+  }
+  return out;
+}

package/src/world/mapWorld.js

@@ -0,0 +1,120 @@
+// A MAP: SEVERAL PLACES, AND THE ROADS BETWEEN THEM.
+//
+// `roadWorld.js` builds a road system out of junction prefabs. `cityPlan.js` builds a town.
+// This is the thing they were both for — a map that reads like a real one, with towns where
+// the land allows and roads joining them across the country in between:
+//
+//   const map = await buildMapWorld({ ground, kit, placePiece });
+//   const heightAt = map.heightAt;          // ← give THIS to buildHeightfield
+//   for (const c of map.cities) drawCity(c);
+//   for (const l of map.links) drawRoad(l);
+//
+// THE ORDER MATTERS, for the same reason it does in roadWorld:
+//   1. choose the sites               — flat, dry, far enough apart to be separate places
+//   2. plan each city                 — each one benches its own ground
+//   3. wrap the ground with the towns — so a road out of one leaves over its real level
+//   4. plan and build the links       — they read that ground
+//   5. wrap again with the corridors  — the final heightAt the world uses
+// Build the links before the towns exist in the ground and every road arrives at a town by
+// running up the hillside the town was cut into.
+//
+// Kiwi had both halves and never joined them: its inter-city window was a manual tool you
+// typed two points into, so a road never started at a town. A city's `exits` — a junction on
+// the edge of the grid with a cardinal arm facing open country — is what makes the join
+// automatic, and it is deliberately shaped like a road-kit socket so `buildRoadLink` needs
+// no special case for it.
+import { planCity, pickCitySites } from './cityPlan.js';
+import { makeRoadTerrain } from './roadTerrain.js';
+import { planEdges } from './roadNetwork.js';
+import { buildRoadLink } from './roadLink.js';
+
+export async function buildMapWorld({
+  ground,                     // the game's natural heightAt
+  cities = 3,                 // how many places
+  population = 7000,          // each
+  half = 900,                 // where they may go
+  minGap = 700,               // and how far apart they must be
+  cityOptions = {},           // passed through to planCity
+  maxGrade = 0.07,            // for the roads BETWEEN towns — a country road, not a street
+  linkStep = 3,
+  handleScale = 0.4,
+  drop = 0.12,
+  extra = 0.35,               // how many links beyond a spanning tree, so the map has loops
+} = {}) {
+  // 1. WHERE THE PLACES GO
+  const sites = pickCitySites(ground, { count: cities, half, minGap, ...cityOptions });
+  if (!sites.length) return { heightAt: ground, cities: [], links: [], sites: [] };
+
+  // 2. EACH PLACE, PLANNED ON THE RAW LAND. A town benches its own ground; it does not care
+  //    what the neighbouring town did, because they are a kilometre apart.
+  const plans = sites.map((s) => planCity({ centre: s, groundAt: ground, population, ...cityOptions }))
+    .filter((c) => c.blocks.length);
+  if (!plans.length) return { heightAt: ground, cities: [], links: [], sites };
+
+  // 3. THE GROUND WITH THE TOWNS IN IT
+  const townworks = {
+    pads: plans.flatMap((c) => c.earthworks.pads),
+    corridors: plans.flatMap((c) => c.earthworks.corridors),
+  };
+  const townGround = makeRoadTerrain(ground, townworks);
+
+  // 4. WHO JOINS WHOM, and through which gate. A town has many exits; the one a given road
+  //    uses is the one whose arm points closest to where the road is going — anything else
+  //    leaves through the back of the town and doubles round it.
+  const centres = plans.map((c) => ({ x: c.centre.x, z: c.centre.z }));
+  const pairs = planEdges(centres, { extra });
+  const used = new Set();
+  const facing = (city, tx, tz, taken) => {
+    let best = null;
+    for (const e of city.exits) {
+      const k = `${city.centre.x},${city.centre.z}:${e.id}`;
+      if (taken.has(k)) continue;
+      const vx = tx - e.pos[0], vz = tz - e.pos[2];
+      const len = Math.hypot(vx, vz) || 1;
+      // point the right way FIRST, then prefer the exit nearest the target: an exit facing
+      // north is no use to a road going south however close to it the far town happens to be
+      const aim = (e.dir[0] * vx + e.dir[1] * vz) / len;
+      if (aim < 0.2) continue;
+      const score = aim * 2 - len / 4000;
+      if (!best || score > best.score) best = { e, k, score };
+    }
+    return best;
+  };
+
+  const links = [];
+  for (const { a, b } of pairs) {
+    const A = plans[a], B = plans[b];
+    const from = facing(A, B.centre.x, B.centre.z, used);
+    const to = facing(B, A.centre.x, A.centre.z, used);
+    if (!from || !to) continue;
+    used.add(from.k); used.add(to.k);
+    links.push({
+      a, b, from: from.e, to: to.e,
+      link: buildRoadLink({
+        from: from.e, to: to.e,
+        groundAt: (x, z) => townGround(x, z) + 0.15,
+        handleScale, step: linkStep, maxGrade,
+      }),
+    });
+  }
+
+  // 5. THE GROUND THE WORLD ACTUALLY USES
+  const corridors = [
+    ...townworks.corridors,
+    ...links.map(({ link, from }) => ({
+      centreline: link.centreline, halfWidth: from.width / 2 + 5, drop, batter: 0.5,
+    })),
+  ];
+
+  return {
+    heightAt: makeRoadTerrain(ground, { pads: townworks.pads, corridors }),
+    cities: plans,
+    links,
+    sites,
+    pads: townworks.pads,
+    corridors,
+    // what the map came out as, for a caller that wants to say so
+    summary: `${plans.length} places · ${plans.reduce((n, c) => n + c.blocks.length, 0)} blocks · `
+      + `${links.length} roads between them · ${links.filter((l) => l.link.feasible === false).length} over grade`,
+  };
+}

package/src/world/roadAssert.js

@@ -95,7 +95,34 @@ export function auditRoadWorld(roads, { ground, samples = 24, tolerance = 0.06 }
   steep.length ? fail('every link is drivable at its grade', `${steep.length} link(s) needed more grade than allowed`)
                : pass('every link is drivable at its grade', `${links.length} links within grade`);
 
-  // 5. JUNCTIONS SIT ON THEIR OWN GROUND. A piece seated at the wrong level is the difference
+  // 5. NOTHING CLAIMS TARMAC IT HAS NOT GOT. A game that hides the ground under its roads —
+  //    the only cure for two surfaces a few centimetres apart fighting for the same pixels —
+  //    trusts `heightAt.deck` absolutely: wherever it answers, the terrain is thrown away.
+  //    So an answer past the end of a road does not make a small error, it makes a hole in
+  //    the world with the sky showing through it. This was reported from the driver's seat
+  //    as a black patch at the end of every road, twice.
+  let phantom = 0, phantomAt = null, n5 = 0;
+  for (const { link, from } of links) {
+    const line = link.centreline;
+    const half = from.width / 2;
+    for (const [p, q] of [[line[0], line[1]], [line[line.length - 1], line[line.length - 2]]]) {
+      if (!p || !q) continue;
+      const ax = p[0] - q[0], az = p[2] - q[2];
+      const L = Math.hypot(ax, az) || 1;                 // outward, away from the road
+      for (const past of [1.5, half, half * 2 + 4]) {
+        for (const side of [-0.8, 0, 0.8]) {
+          const x = p[0] + (ax / L) * past - (az / L) * side * half;
+          const z = p[2] + (az / L) * past + (ax / L) * side * half;
+          n5++;
+          if (heightAt.deck?.(x, z) != null) { phantom++; phantomAt ??= [Math.round(x), Math.round(z)]; }
+        }
+      }
+    }
+  }
+  phantom ? fail('no phantom tarmac past a road end', `${phantom}/${n5} probes claimed a deck, first at ${phantomAt}`)
+          : pass('no phantom tarmac past a road end', `${n5} probes beyond the ends clean`);
+
+  // 6. JUNCTIONS SIT ON THEIR OWN GROUND. A piece seated at the wrong level is the difference
   //    between a slip road and a diving board.
   let hanging = 0;
   for (const [, p] of placed) {