@jgengine/core 0.18.0 → 0.19.0

package/dist/world/cityKind.js

@@ -18,8 +18,10 @@
  * (`cityContent`) — setback tower tiers, gabled houses, gambrel barns, domed silos. Blocks left
  * unbuilt become plazas/greens/meadows by band, or crop-row farm fields; slivers and block
  * interiors classify as buffers and courtyards, never leftover rectangles. Street
- * furniture (lights, species-mixed trees, estate hedges, driveways, parking lots) resolves as
- * bounded, seeded data hooked to the network. Child `cityzone` volumes override the band/mix
+ * furniture (lights, species-mixed trees, estate hedges, driveways, parking lots, parked vehicles,
+ * junction signals and sign posts) resolves as bounded, seeded data hooked to the network. Turn `race` on and the district also hands back a
+ * {@link ResolvedRace}: a closed lap lifted out of its OWN streets with every side street leaving it
+ * sealed off — the Monaco / open-world street-race model, not a separate track. Child `cityzone` volumes override the band/mix
  * locally, so hand-placed intent wins over the profile. Named presets (Manhattan, Los Angeles,
  * Beverly Hills, rural Ohio…) ship as plain slider bundles on the schema. Pure config + resolver
  * here; the instanced renderer lives in the `shell`. Everything is deterministic per seed and
@@ -31,7 +33,8 @@ import { seededStreams } from "../random/rng.js";
 import { parseParams, registerSceneKind, } from "../scene/sceneKinds.js";
 import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_STYLE } from "./buildings.js";
 import { buildLotPieces, pickClass, pickSpecies, rollClassPlacement, zoneBand, zoneMetric, } from "./cityContent.js";
-import { furnitureSpots } from "./streets.js";
+import { circuitKerbs, extractCircuitRoute, } from "./raceCircuit.js";
+import { furnitureSpots, parkingSpots } from "./streets.js";
 import { CITY_BUILDING_BUDGET, budgetWarning, placedCoverage } from "./scatterCoverage.js";
 import { generateStreets, streetNetworkMode, } from "./streetGenerator.js";
 import { buildablePolygon, carveCorridors, conformPolygonToRing, cutParcel, extractBlocks, isSliverBlock, pointsInPolygon, RingWalker, } from "./cityBlocks.js";
@@ -51,6 +54,11 @@ export const CITY_DEFAULTS = {
     minCurveRadius: 24,
     minTurnAngle: 0,
     maxTurnAngle: 150,
+    outline: 0,
+    residentialBranches: 0,
+    elevation: 0,
+    maxGrade: 0.07,
+    compactness: 0,
     fabric: true,
     tunnels: true,
     blockSize: 48,
@@ -92,6 +100,8 @@ export const CITY_DEFAULTS = {
         { item: "conifer", weight: 1 },
     ],
     lightDensity: 0.5,
+    parkedCars: 0.55,
+    signals: 0.7,
     hedges: true,
     driveways: true,
     parking: true,
@@ -102,6 +112,14 @@ export const CITY_DEFAULTS = {
     bridgeStyle: "arch",
     sidewalks: true,
     sidewalkWidth: 1.9,
+    race: false,
+    raceLapLength: 1200,
+    raceArterial: 0.7,
+    raceCheckpoints: 12,
+    raceLaps: 3,
+    raceSeals: true,
+    raceGridSlots: 12,
+    raceCornerRadius: 9,
     style: DEFAULT_BUILDING_STYLE,
     buildingKit: "",
     seed: "",
@@ -110,6 +128,7 @@ export const CITY_DEFAULTS = {
 export const CITY_SCHEMA = {
     groups: [
         { id: "layout", label: "Layout" },
+        { id: "race", label: "Race" },
         { id: "placement", label: "Placement" },
         { id: "zoning", label: "Zoning" },
         { id: "buildings", label: "Buildings" },
@@ -125,6 +144,11 @@ export const CITY_SCHEMA = {
         { type: "range", key: "minCurveRadius", label: "min curve radius", group: "layout", min: 6, max: 120, step: 1, default: CITY_DEFAULTS.minCurveRadius, unit: "m" },
         { type: "range", key: "minTurnAngle", label: "min turn angle", group: "layout", min: 0, max: 60, step: 1, default: CITY_DEFAULTS.minTurnAngle, unit: "°" },
         { type: "range", key: "maxTurnAngle", label: "max turn angle", group: "layout", min: 30, max: 180, step: 1, default: CITY_DEFAULTS.maxTurnAngle, unit: "°" },
+        { type: "range", key: "outline", label: "outline", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.outline },
+        { type: "range", key: "residentialBranches", label: "residential branches", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.residentialBranches },
+        { type: "range", key: "elevation", label: "road elevation", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.elevation },
+        { type: "range", key: "maxGrade", label: "max grade", group: "layout", min: 0.01, max: 0.3, step: 0.005, default: CITY_DEFAULTS.maxGrade },
+        { type: "range", key: "compactness", label: "circuit compactness", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.compactness },
         { type: "range", key: "blockSize", label: "block size", group: "layout", min: 20, max: 140, step: 1, default: CITY_DEFAULTS.blockSize, unit: "m" },
         { type: "range", key: "blockAspect", label: "block aspect", group: "layout", min: 1, max: 3, step: 0.05, default: CITY_DEFAULTS.blockAspect },
         { type: "range", key: "openSpace", label: "open space", group: "layout", min: 0, max: 0.9, step: 0.01, default: CITY_DEFAULTS.openSpace },
@@ -140,6 +164,7 @@ export const CITY_SCHEMA = {
             options: [{ value: "auto" }, { value: "gravel" }],
         },
         { type: "bool", key: "fabric", label: "buildings & parcels", group: "layout", default: CITY_DEFAULTS.fabric },
+        { type: "bool", key: "solid", label: "solid buildings", group: "layout", default: true },
         { type: "bool", key: "bridges", label: "bridges over water", group: "layout", default: CITY_DEFAULTS.bridges },
         { type: "bool", key: "tunnels", label: "tunnels through ridges", group: "layout", default: CITY_DEFAULTS.tunnels },
         {
@@ -153,6 +178,14 @@ export const CITY_SCHEMA = {
         { type: "bool", key: "sidewalks", label: "sidewalks", group: "layout", default: CITY_DEFAULTS.sidewalks },
         { type: "range", key: "sidewalkWidth", label: "sidewalk width", group: "layout", min: 1, max: 4, step: 0.1, default: CITY_DEFAULTS.sidewalkWidth, unit: "m" },
         { type: "action", key: "layoutRandomize", label: "randomize layout", group: "layout", action: "randomize" },
+        { type: "bool", key: "race", label: "street race", group: "race", default: CITY_DEFAULTS.race },
+        { type: "range", key: "raceLapLength", label: "lap length", group: "race", min: 200, max: 6000, step: 50, default: CITY_DEFAULTS.raceLapLength, unit: "m" },
+        { type: "range", key: "raceArterial", label: "arterial bias", group: "race", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.raceArterial },
+        { type: "range", key: "raceCheckpoints", label: "checkpoints", group: "race", min: 2, max: 48, step: 1, default: CITY_DEFAULTS.raceCheckpoints },
+        { type: "range", key: "raceLaps", label: "laps", group: "race", min: 1, max: 20, step: 1, default: CITY_DEFAULTS.raceLaps },
+        { type: "bool", key: "raceSeals", label: "seal side streets", group: "race", default: CITY_DEFAULTS.raceSeals },
+        { type: "range", key: "raceGridSlots", label: "grid slots", group: "race", min: 0, max: 40, step: 1, default: CITY_DEFAULTS.raceGridSlots },
+        { type: "range", key: "raceCornerRadius", label: "corner radius", group: "race", min: 3, max: 40, step: 1, default: CITY_DEFAULTS.raceCornerRadius, unit: "m" },
         {
             type: "select",
             key: "profile",
@@ -189,6 +222,8 @@ export const CITY_SCHEMA = {
         { type: "range", key: "treeDensity", label: "tree density", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.treeDensity },
         { type: "weightedList", key: "treeMix", label: "tree mix", group: "greenery", itemLabel: "species", default: CITY_DEFAULTS.treeMix },
         { type: "range", key: "lightDensity", label: "street lights", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.lightDensity },
+        { type: "range", key: "parkedCars", label: "parked cars", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.parkedCars },
+        { type: "range", key: "signals", label: "traffic signals", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.signals },
         { type: "bool", key: "hedges", label: "estate hedges", group: "greenery", default: CITY_DEFAULTS.hedges },
         { type: "bool", key: "driveways", label: "driveways", group: "greenery", default: CITY_DEFAULTS.driveways },
         { type: "bool", key: "parking", label: "parking lots", group: "greenery", default: CITY_DEFAULTS.parking },
@@ -208,8 +243,8 @@ export const CITY_SCHEMA = {
                 openSpace: 0.05,
                 roadsideOccupancy: 0.97,
                 blockDensity: 0.85,
-                buildingRoadSetback: 0.8,
-                buildingSpacing: 0.8,
+                buildingRoadSetback: 0.55,
+                buildingSpacing: 0.55,
                 clusterStrength: 0.25,
                 streetWidth: 9,
                 boulevards: 0.5,
@@ -235,6 +270,8 @@ export const CITY_SCHEMA = {
                 treeDensity: 0.3,
                 treeMix: [{ item: "broadleaf", weight: 1 }],
                 lightDensity: 0.8,
+                parkedCars: 0.95,
+                signals: 1,
                 hedges: false,
                 driveways: false,
                 parking: false,
@@ -288,6 +325,8 @@ export const CITY_SCHEMA = {
                     { item: "cypress", weight: 1 },
                 ],
                 lightDensity: 0.6,
+                parkedCars: 0.7,
+                signals: 0.8,
                 hedges: false,
                 driveways: true,
                 parking: true,
@@ -339,6 +378,8 @@ export const CITY_SCHEMA = {
                     { item: "broadleaf", weight: 2 },
                 ],
                 lightDensity: 0.35,
+                parkedCars: 0.2,
+                signals: 0.12,
                 hedges: true,
                 driveways: true,
                 parking: false,
@@ -392,6 +433,8 @@ export const CITY_SCHEMA = {
                     { item: "conifer", weight: 2 },
                 ],
                 lightDensity: 0.1,
+                parkedCars: 0.04,
+                signals: 0,
                 hedges: false,
                 driveways: true,
                 parking: false,
@@ -413,6 +456,9 @@ export const CITY_SCHEMA = {
                 minCurveRadius: 34,
                 minTurnAngle: 0,
                 maxTurnAngle: 95,
+                compactness: 0.5,
+                elevation: 0.3,
+                maxGrade: 0.06,
                 blockSize: 95,
                 blockAspect: 1,
                 openSpace: 0,
@@ -426,6 +472,8 @@ export const CITY_SCHEMA = {
                 sidewalks: false,
                 treeDensity: 0.2,
                 lightDensity: 0.25,
+                parkedCars: 0,
+                signals: 0,
                 hedges: false,
                 driveways: false,
                 parking: false,
@@ -446,6 +494,9 @@ export const CITY_SCHEMA = {
                 minCurveRadius: 12,
                 minTurnAngle: 0,
                 maxTurnAngle: 150,
+                outline: 0.5,
+                elevation: 0.8,
+                maxGrade: 0.14,
                 blockSize: 72,
                 blockAspect: 1,
                 openSpace: 0,
@@ -459,6 +510,8 @@ export const CITY_SCHEMA = {
                 sidewalks: false,
                 treeDensity: 0.65,
                 lightDensity: 0.05,
+                parkedCars: 0,
+                signals: 0,
                 hedges: false,
                 driveways: false,
                 parking: false,
@@ -490,6 +543,8 @@ export const CITY_SCHEMA = {
                 floorsMax: 34,
                 treeDensity: 0.55,
                 lightDensity: 0.6,
+                parkedCars: 0.85,
+                signals: 0.9,
                 style: "generic",
             },
         },
@@ -527,6 +582,11 @@ export function readCityRules(meta) {
         minCurveRadius: params["minCurveRadius"],
         minTurnAngle: params["minTurnAngle"],
         maxTurnAngle: params["maxTurnAngle"],
+        outline: params["outline"],
+        residentialBranches: params["residentialBranches"],
+        elevation: params["elevation"],
+        maxGrade: params["maxGrade"],
+        compactness: params["compactness"],
         fabric: params["fabric"],
         tunnels: params["tunnels"],
         blockSize: params["blockSize"],
@@ -554,6 +614,8 @@ export function readCityRules(meta) {
         treeDensity: params["treeDensity"],
         treeMix: params["treeMix"],
         lightDensity: params["lightDensity"],
+        parkedCars: params["parkedCars"],
+        signals: params["signals"],
         hedges: params["hedges"],
         driveways: params["driveways"],
         parking: params["parking"],
@@ -564,11 +626,68 @@ export function readCityRules(meta) {
         bridgeStyle: params["bridgeStyle"],
         sidewalks: params["sidewalks"],
         sidewalkWidth: params["sidewalkWidth"],
+        race: params["race"],
+        raceLapLength: params["raceLapLength"],
+        raceArterial: params["raceArterial"],
+        raceCheckpoints: params["raceCheckpoints"],
+        raceLaps: params["raceLaps"],
+        raceSeals: params["raceSeals"],
+        raceGridSlots: params["raceGridSlots"],
+        raceCornerRadius: params["raceCornerRadius"],
         style: params["style"],
         buildingKit: params["buildingKit"] ?? CITY_DEFAULTS.buildingKit,
         seed: params["seed"],
     };
 }
+/** Lot pieces that block: walls and roofs. Trim and accents (cornices, awnings) stay passable. */
+const SOLID_PIECE_ROLES = new Set(["wall", "roof"]);
+/**
+ * One solid per wall and roof piece of every lot, grounded the way the city renderer grounds it:
+ * grade at the highest lot corner, foundations down to half a metre under the lowest.
+ * @capability city-district editor-authorable procedural city district (streets, zoning, buildings, furniture)
+ */
+export function citySolids(city, sampleHeight = () => 0) {
+    const solids = [];
+    for (const lot of city.lots) {
+        const c = Math.cos(lot.rotationY);
+        const s = Math.sin(lot.rotationY);
+        const hw = lot.size[0] / 2;
+        const hd = lot.size[1] / 2;
+        let minY = Infinity;
+        let maxY = -Infinity;
+        for (const [dx, dz] of [
+            [hw, hd],
+            [hw, -hd],
+            [-hw, hd],
+            [-hw, -hd],
+        ]) {
+            const y = sampleHeight(lot.center[0] + dx * c + dz * s, lot.center[1] - dx * s + dz * c);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+        }
+        const grade = maxY;
+        const foundationBase = minY - 0.5;
+        for (const piece of lot.pieces) {
+            if (!SOLID_PIECE_ROLES.has(piece.role))
+                continue;
+            const bottom = piece.grounded ? foundationBase : grade + piece.offset[1];
+            const top = piece.grounded ? grade + piece.size[1] : grade + piece.offset[1] + piece.size[1];
+            if (top - bottom <= 0 || piece.size[0] <= 0 || piece.size[2] <= 0)
+                continue;
+            const yaw = lot.rotationY + piece.rotationY;
+            solids.push({
+                center: [
+                    lot.center[0] + piece.offset[0] * c + piece.offset[2] * s,
+                    (bottom + top) / 2,
+                    lot.center[1] - piece.offset[0] * s + piece.offset[2] * c,
+                ],
+                halfExtents: [piece.size[0] / 2, (top - bottom) / 2, piece.size[2] / 2],
+                ...(yaw === 0 ? {} : { rotationY: yaw }),
+            });
+        }
+    }
+    return solids;
+}
 /** Bounded-work caps so a huge volume can never generate unbounded content. */
 const MAX_STREETS = 320;
 /** Building budget — the shared scatterable cap so the inspector's "capped at N (budget)" note is truthful. */
@@ -578,7 +697,19 @@ const MAX_TREES = 3200;
 const MAX_LIGHTS = 1200;
 const MAX_FIELD_ROWS = 2400;
 const MAX_PARKING = 380;
+const MAX_VEHICLES = 900;
+const MAX_SIGNALS = 640;
+const MAX_RACE_SEALS = 400;
+const MAX_RACE_KERBS = 320;
 const TAU = Math.PI * 2;
+/** Body footprint per silhouette as `[half width across, half length along the heading]`. */
+const VEHICLE_HALF_EXTENTS = {
+    car: [0.95, 2.25],
+    van: [1.05, 2.65],
+    truck: [1.2, 3.5],
+};
+/** Paint slots the resolver spreads vehicles across; the renderer owns the actual colors. */
+const VEHICLE_PAINT_COUNT = 8;
 function axisValue(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -818,7 +949,8 @@ function buildFabric(rules, streams, streets, index, hx, hz, slopeAt, heightAt,
             if (prevClass !== null && stickRoll < 0.45 + rules.clusterStrength * 0.4 && mix.some((entry) => entry.item === prevClass && entry.weight > 0)) {
                 cls = prevClass;
             }
-            const placement = rollClassPlacement(cls, lotRng, rules.lotScale, rules.floorsMin, rules.floorsMax, rules.buildingRoadSetback, rules.buildingSpacing);
+            const stretchCommercial = rules.blockDensity > 0.75 && (cls === "tower" || cls === "slab" || cls === "shop" || cls === "rowhouse");
+            const placement = rollClassPlacement(cls, lotRng, rules.lotScale, rules.floorsMin, rules.floorsMax, rules.buildingRoadSetback, rules.buildingSpacing, stretchCommercial ? 1 + rules.blockDensity * 0.35 : 1);
             const frontW = placement.width + placement.gap;
             if (cursor + frontW > walker.total - 0.5)
                 break;
@@ -904,18 +1036,21 @@ function buildFabric(rules, streams, streets, index, hx, hz, slopeAt, heightAt,
                 prevClass = null;
                 continue;
             }
-            const sideGap = Math.max(0.3, placement.gap / 2);
-            const buildable = buildablePolygon(poly, A, B, placement.setback, sideGap, 1.2, usedDepth);
+            const commercial = cls === "tower" || cls === "slab" || cls === "shop" || cls === "rowhouse";
+            const dense = rules.blockDensity > 0.75 && commercial;
+            const sideGap = Math.max(dense ? (cls === "shop" || cls === "rowhouse" ? 0.08 : 0.15) : 0.3, (placement.gap / 2) * (dense ? 0.45 : 1));
+            const frontSetback = Math.max(0.05, placement.setback * (dense ? 0.35 : 1));
+            const buildable = buildablePolygon(poly, A, B, frontSetback, sideGap, 1.2, usedDepth);
             parcel.buildable = buildable;
             let placedLot = false;
             if (buildable.length >= 3) {
                 const outDir = [-midS.normal[0], -midS.normal[1]];
                 const rotationY = Math.atan2(outDir[0], outDir[1]);
-                const maxW = Math.max(3, Math.min(placement.width, frontW - placement.gap));
-                const availDepth = usedDepth - placement.setback - 1.2;
-                const maxD = Math.max(3, Math.min(placement.depth, availDepth));
-                const cx0 = midS.p[0] + midS.normal[0] * (placement.setback + maxD / 2);
-                const cz0 = midS.p[1] + midS.normal[1] * (placement.setback + maxD / 2);
+                const maxW = Math.max(3, Math.min(dense ? Math.max(placement.width, frontW * 0.9) : placement.width, frontW - Math.max(0.15, placement.gap * (dense ? 0.35 : 1))));
+                const availDepth = usedDepth - frontSetback - 1.2;
+                const maxD = Math.max(3, Math.min(dense ? Math.max(placement.depth, availDepth * 0.85) : placement.depth, availDepth));
+                const cx0 = midS.p[0] + midS.normal[0] * (frontSetback + maxD / 2);
+                const cz0 = midS.p[1] + midS.normal[1] * (frontSetback + maxD / 2);
                 const fit = fitRectInPolygon(buildable, cx0, cz0, maxW, maxD, rotationY, 0.45);
                 if (fit !== null && fit.w >= 3 && fit.d >= 2.6) {
                     const slopeRoll = rng();
@@ -1022,8 +1157,8 @@ function buildFabric(rules, streams, streets, index, hx, hz, slopeAt, heightAt,
         // elsewhere) when it is big enough to read as a place rather than back yards.
         if (maxDepthUsed > 0) {
             const core = insetRingUniform(land, maxDepthUsed + 0.5);
-            if (core.length >= 3 && polygonArea(core) > 240) {
-                const type = band === "core" ? "courtyard" : band === "mid" ? (parkJitter < 0.5 ? "courtyard" : "green") : "meadow";
+            if (core.length >= 3 && polygonArea(core) > 120) {
+                const type = band === "core" ? "courtyard" : band === "mid" ? (parkJitter < 0.55 ? "courtyard" : "green") : "meadow";
                 result.parks.push(parkFromRing(`court:${bi}`, type, core, parkJitter));
             }
         }
@@ -1071,6 +1206,89 @@ function buildFieldRows(parks, placed, streams) {
             park.rows = rows;
     }
 }
+/** Ids of the through-streets carrying a lap's graph edges, in lap order and without repeats. */
+function lapStreetIds(network, edges, streetCount) {
+    const pairKey = (a, b) => (a < b ? `${a}:${b}` : `${b}:${a}`);
+    const owner = new Map();
+    for (let index = 0; index < Math.min(network.streets.length, streetCount); index += 1) {
+        const nodes = network.streets[index].nodes;
+        for (let i = 0; i + 1 < nodes.length; i += 1)
+            owner.set(pairKey(nodes[i], nodes[i + 1]), index);
+    }
+    const byId = new Map(network.edges.map((edge) => [edge.id, edge]));
+    const ids = [];
+    const seen = new Set();
+    for (const id of edges) {
+        const edge = byId.get(id);
+        if (edge === undefined)
+            continue;
+        const index = owner.get(pairKey(edge.a, edge.b));
+        if (index === undefined || seen.has(index))
+            continue;
+        seen.add(index);
+        ids.push(`street:${index}`);
+    }
+    return ids;
+}
+/** Rotate and translate a volume-local circuit route into the world frame the rest of the plan uses. */
+function raceToWorld(route, streets, seals, toWorld, rotationY) {
+    // `toWorld` rotates a local direction BY `rotationY`, so a heading turns with it rather than against.
+    const heading = (local) => local + rotationY;
+    // A checkpoint is an AABB with no yaw of its own; grow it to the bounds of the rotated gate.
+    const gateX = Math.abs(Math.cos(rotationY));
+    const gateZ = Math.abs(Math.sin(rotationY));
+    const [sx, sz] = toWorld(route.start.x, route.start.z);
+    return {
+        centerline: route.centerline.map(([x, z]) => toWorld(x, z)),
+        widths: [...route.widths],
+        ...(route.heights === undefined ? {} : { heights: [...route.heights] }),
+        length: route.length,
+        streets,
+        seals: seals
+            ? route.seals.slice(0, MAX_RACE_SEALS).map((seal) => {
+                const [x, z] = toWorld(seal.x, seal.z);
+                return { x, z, heading: heading(seal.heading), width: seal.width, kind: seal.kind };
+            })
+            : [],
+        corners: route.corners.map((corner) => ({ ...corner })),
+        kerbs: circuitKerbs(route)
+            .slice(0, MAX_RACE_KERBS)
+            .map((kerb) => ({
+            points: kerb.points.map(([x, z]) => toWorld(x, z)),
+            width: kerb.width,
+            side: kerb.side,
+            stripe: kerb.stripe,
+            corner: kerb.corner,
+        })),
+        checkpoints: route.checkpoints.map((gate) => {
+            const [x, z] = toWorld(gate.center[0], gate.center[2]);
+            return {
+                id: gate.id,
+                center: [x, gate.center[1], z],
+                half: [
+                    gate.half[0] * gateX + gate.half[2] * gateZ,
+                    gate.half[1],
+                    gate.half[0] * gateZ + gate.half[2] * gateX,
+                ],
+            };
+        }),
+        laps: route.laps,
+        start: {
+            x: sx,
+            z: sz,
+            heading: heading(route.start.heading),
+            line: [toWorld(route.start.line[0][0], route.start.line[0][1]), toWorld(route.start.line[1][0], route.start.line[1][1])],
+            distance: route.start.distance,
+            width: route.start.width,
+        },
+        grid: route.grid.map((slot) => {
+            const [x, z] = toWorld(slot.x, slot.z);
+            return { x, z, heading: heading(slot.heading) };
+        }),
+        sectors: [...route.sectors],
+        tightestRadius: route.tightestRadius,
+    };
+}
 /**
  * Synthesize the deterministic city plan for one `city` volume: streets → bridges → parks → zoned
  * frontage lots with massing pieces → furniture, all in the volume's local frame and then
@@ -1109,6 +1327,8 @@ export function resolveCityObject(object, context) {
         hedges: [],
         driveways: [],
         parkingLots: [],
+        vehicles: [],
+        signals: [],
     };
     if (hx < rules.blockSize * 0.75 || hz < rules.blockSize * 0.75)
         return empty;
@@ -1132,7 +1352,7 @@ export function resolveCityObject(object, context) {
             return Math.hypot(dx, dz) / (2 * d);
         };
     // Child `cityzone` volumes override the band (and optionally the class mix) for lots inside them.
-    const overrides = (context?.zoneOverrides ?? []).filter((volume) => volume.kind === CITY_ZONE_KIND);
+    const overrides = (context?.zoneOverrides ?? context?.objects ?? []).filter((volume) => volume.kind === CITY_ZONE_KIND);
     const overrideAt = overrides.length === 0
         ? null
         : (x, z) => {
@@ -1163,10 +1383,12 @@ export function resolveCityObject(object, context) {
     // net and a closed race circuit are the SAME generator at opposite slider extremes.
     const netRules = {
         seed: rules.seed.length > 0 ? rules.seed : object.id,
+        outline: rules.outline,
         gridness: rules.gridness,
         loopiness: rules.loopiness,
         connectivity: rules.connectivity,
         branching: rules.branching,
+        residentialBranches: rules.residentialBranches,
         deadEnds: rules.deadEnds,
         segmentLength: rules.blockSize,
         aspect: rules.blockAspect,
@@ -1176,6 +1398,10 @@ export function resolveCityObject(object, context) {
         maxTurnAngle: rules.maxTurnAngle,
         width: rules.streetWidth,
         boulevards: rules.boulevards,
+        sidewalkWidth: rules.sidewalkWidth,
+        elevation: rules.elevation,
+        maxGrade: rules.maxGrade,
+        compactness: rules.compactness,
     };
     const network = generateStreets(netRules, hx, hz, {
         heightAt: heightAt ?? undefined,
@@ -1193,6 +1419,7 @@ export function resolveCityObject(object, context) {
             level: street.level,
             surface,
             sidewalk: rules.sidewalks && surface === "asphalt",
+            ...(street.heights === undefined ? {} : { heights: [...street.heights] }),
             ...(street.bulb === undefined ? {} : { bulb: [street.bulb[0], street.bulb[1]] }),
             ...(street.features.length === 0 ? {} : { features: street.features }),
         };
@@ -1212,6 +1439,19 @@ export function resolveCityObject(object, context) {
         width: t.width,
         bankHeight: t.bankHeight,
     }));
+    // The race is a SECTION OF THIS CITY blocked off: the same streets the district already grew,
+    // with a closed lap lifted out of them. A district with no drivable cycle simply has no race.
+    const route = rules.race
+        ? extractCircuitRoute(network, {
+            seed: netRules.seed,
+            lapLength: rules.raceLapLength,
+            arterialBias: rules.raceArterial,
+            minCornerRadius: rules.raceCornerRadius,
+            checkpoints: rules.raceCheckpoints,
+            laps: rules.raceLaps,
+            gridSlots: rules.raceGridSlots,
+        })
+        : null;
     // Fabric (block/parcel/building subdivision) is optional: a bare road or race track leaves it off,
     // so a circuit never carries forced-on plots — parcels and buildings appear only when you want it.
     const emptyFabric = { blocks: [], parcels: [], parks: [], lots: [], placed: new LotIndex(), hedges: [], driveways: [] };
@@ -1372,6 +1612,99 @@ export function resolveCityObject(object, context) {
             parking.push({ center: [x, z], size: [lot.size[0] * 1.05, depth], rotationY: lot.rotationY });
         }
     }
+    // Parked vehicles: curbside anchors come from the shared street helper, pad stalls from the
+    // pads laid above. Every candidate clears other streets, footprints, and the cars already parked.
+    const vehicles = [];
+    if (rules.parkedCars > 0) {
+        const carRng = streams("vehicles");
+        const carIndex = new LotIndex();
+        const park = (x, z, heading, mix, stall, street) => {
+            const kind = mix < 0.68 ? "car" : mix < 0.9 ? "van" : "truck";
+            const half = VEHICLE_HALF_EXTENTS[kind];
+            const rect = { x, z, hw: half[0], hd: half[1], angle: heading };
+            if (!insideBounds(x, z))
+                return;
+            if (index.clearance(x, z, stall === "curb" ? 0.6 : 0.5, street) < 0)
+                return;
+            if (lotResult.placed.overlapsAny(rect, 0.4))
+                return;
+            if (carIndex.overlapsAny(rect, 0.35))
+                return;
+            carIndex.add(rect);
+            vehicles.push({ x, z, rotationY: heading, kind, paint: Math.floor(mix * 9973) % VEHICLE_PAINT_COUNT, stall });
+        };
+        const spacing = Math.max(7, 26 - 19 * rules.parkedCars);
+        for (let si = 0; si < local.length && vehicles.length < MAX_VEHICLES; si += 1) {
+            const street = local[si];
+            // Gravel shoulders and narrow lanes have no curb lane: `parkingSpots` would seat the body
+            // over the centreline of anything under ~6.5 m.
+            if (street.surface === "gravel" || street.width < 6.5)
+                continue;
+            for (const spot of parkingSpots(asDescriptor(street), { spacing })) {
+                if (vehicles.length >= MAX_VEHICLES)
+                    break;
+                const mix = carRng();
+                if (carRng() > rules.parkedCars)
+                    continue;
+                const [x, z] = spot.position;
+                if (nearIntersection(x, z, 4))
+                    continue;
+                park(x, z, spot.heading, mix, "curb", si);
+            }
+        }
+        for (const pad of parking) {
+            if (vehicles.length >= MAX_VEHICLES)
+                break;
+            const ca = Math.cos(pad.rotationY);
+            const sa = Math.sin(pad.rotationY);
+            const rows = pad.size[1] >= 11 ? 2 : 1;
+            const stalls = Math.max(1, Math.floor(pad.size[0] / 2.9));
+            for (let row = 0; row < rows; row += 1) {
+                const lz = rows === 1 ? 0 : (row === 0 ? -1 : 1) * pad.size[1] * 0.25;
+                for (let s = 0; s < stalls; s += 1) {
+                    if (vehicles.length >= MAX_VEHICLES)
+                        break;
+                    const mix = carRng();
+                    if (carRng() > rules.parkedCars * 0.92)
+                        continue;
+                    const lx = ((s + 0.5) / stalls - 0.5) * pad.size[0];
+                    // Facing rows nose in on the aisle between them.
+                    park(pad.center[0] + lx * ca + lz * sa, pad.center[1] - lx * sa + lz * ca, pad.rotationY + row * Math.PI, mix, "lot", -1);
+                }
+            }
+        }
+    }
+    // Junction control, one device per approach arm: arterial crossings get a signal on a mast arm,
+    // everything above lane level gets a sign post instead.
+    const signals = [];
+    if (rules.signals > 0) {
+        const signalRng = streams("signals");
+        for (const cross of intersections) {
+            if (signals.length >= MAX_SIGNALS)
+                break;
+            if (cross.arms.length < 3 || cross.level === "lane")
+                continue;
+            const arterial = LEVEL_RANK[cross.level] >= LEVEL_RANK.avenue;
+            if (signalRng() > rules.signals * (arterial ? 1 : 0.75))
+                continue;
+            for (const arm of cross.arms) {
+                if (signals.length >= MAX_SIGNALS)
+                    break;
+                const dir = [Math.sin(arm.angle), Math.cos(arm.angle)];
+                // Right-hand traffic: the pole stands on the near-right corner of the approach.
+                const perp = [-dir[1], dir[0]];
+                const out = cross.radius + 1.8;
+                const side = arm.width / 2 + 1;
+                const x = cross.x + dir[0] * out + perp[0] * side;
+                const z = cross.z + dir[1] * out + perp[1] * side;
+                if (!insideBounds(x, z))
+                    continue;
+                if (index.clearance(x, z, 0.3) < 0)
+                    continue;
+                signals.push({ x, z, heading: arm.angle, kind: arterial ? "signal" : "sign", reach: arm.width / 2 + 0.6 });
+            }
+        }
+    }
     return {
         center: [center.x, center.y, center.z],
         size: [hx * 2, hz * 2],
@@ -1384,6 +1717,7 @@ export function resolveCityObject(object, context) {
             level: street.level,
             surface: street.surface,
             sidewalk: street.sidewalk,
+            ...(street.heights === undefined ? {} : { heights: [...street.heights] }),
             ...(street.bulb === undefined ? {} : { bulb: toWorld(street.bulb[0], street.bulb[1]) }),
             ...(street.features === undefined ? {} : { features: street.features.map((f) => ({ ...f })) }),
         })),
@@ -1481,6 +1815,17 @@ export function resolveCityObject(object, context) {
             const [x, z] = toWorld(pad.center[0], pad.center[1]);
             return { center: [x, z], size: pad.size, rotationY: pad.rotationY - rotationY };
         }),
+        vehicles: vehicles.map((vehicle) => {
+            const [x, z] = toWorld(vehicle.x, vehicle.z);
+            return { x, z, rotationY: vehicle.rotationY + rotationY, kind: vehicle.kind, paint: vehicle.paint, stall: vehicle.stall };
+        }),
+        signals: signals.map((signal) => {
+            const [x, z] = toWorld(signal.x, signal.z);
+            return { x, z, heading: signal.heading + rotationY, kind: signal.kind, reach: signal.reach };
+        }),
+        ...(route === null
+            ? {}
+            : { race: raceToWorld(route, lapStreetIds(network, route.edges, local.length), rules.raceSeals, toWorld, rotationY) }),
     };
 }
 /** Registers the `city` + `cityzone` scene kinds (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
@@ -1494,6 +1839,7 @@ export function registerCityKind() {
         schema: CITY_SCHEMA,
         coverage: { spec: "city", densityKey: "roadsideOccupancy" },
         resolve: (object, _params, context) => resolveCityObject(object, context),
+        solids: (resolved, _object, params, context) => resolved === null || params["solid"] === false ? [] : citySolids(resolved, context.sampleHeight),
         note: (object) => {
             const resolved = resolveCityObject(object);
             if (resolved === null)
@@ -1519,6 +1865,11 @@ export function registerCityKind() {
             const feats = [
                 resolved.bridges.length > 0 ? `${resolved.bridges.length} bridges` : "",
                 resolved.tunnels.length > 0 ? `${resolved.tunnels.length} tunnels` : "",
+                resolved.rules.race
+                    ? resolved.race === undefined
+                        ? "no raceable lap in these streets"
+                        : `${Math.round(resolved.race.length)} m lap · ${resolved.race.seals.length} seals`
+                    : "",
             ].filter((s) => s.length > 0);
             const head = mode === "circuit" ? `circuit · ${resolved.streets.length} streets` : `${resolved.streets.length} streets`;
             // Shared clamp-and-warn: when the block/parcel pipeline hits the building budget, surface it in