@jgengine/core 0.17.0 → 0.18.1

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 },
@@ -153,6 +177,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 +221,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 +242,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 +269,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 +324,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 +377,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 +432,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 +455,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 +471,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 +493,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 +509,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 +542,8 @@ export const CITY_SCHEMA = {
                 floorsMax: 34,
                 treeDensity: 0.55,
                 lightDensity: 0.6,
+                parkedCars: 0.85,
+                signals: 0.9,
                 style: "generic",
             },
         },
@@ -527,6 +581,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 +613,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,6 +625,14 @@ 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"],
@@ -578,7 +647,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 +899,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 +986,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 +1107,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 +1156,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 +1277,8 @@ export function resolveCityObject(object, context) {
         hedges: [],
         driveways: [],
         parkingLots: [],
+        vehicles: [],
+        signals: [],
     };
     if (hx < rules.blockSize * 0.75 || hz < rules.blockSize * 0.75)
         return empty;
@@ -1163,10 +1333,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 +1348,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 +1369,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 +1389,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 +1562,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 +1667,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 +1765,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 */
@@ -1519,6 +1814,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

package/dist/world/features.d.ts

@@ -4,6 +4,7 @@ import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
 import type { PlaceWorldFeature } from "./place.js";
 import type { TerraformSnapshot } from "./terraform.js";
+import type { SpriteAtlas } from "../assets/spriteAtlas.js";
 import type { VolumetricCloudsConfig } from "./volumetricClouds.js";
 export interface WorldBounds {
     w: number;
@@ -48,6 +49,16 @@ export interface TerrainDetailConfig {
     roughness?: number;
     /** Overall detail intensity 0..1. Default 1. */
     strength?: number;
+    /**
+     * RGB multipliers for the two macro colour sweeps painted over the base ground. `dry` tints the
+     * sun-bleached patches, `wet` the cooler pockets between them. The defaults ([1.14, 1.05, 0.76]
+     * and [0.78, 1.0, 0.86]) suit temperate meadows; the green-leaning `wet` default paints mossy
+     * pockets onto any biome that keeps it, so arid/ashen worlds should supply warm or neutral tints.
+     */
+    sweeps?: {
+        dry?: readonly [number, number, number];
+        wet?: readonly [number, number, number];
+    };
     /** Real PBR texture maps blended over the procedural detail — the seam for `@jgengine/assets` `buildMaterialCatalog` output. Omit to keep the procedural-only look. */
     material?: TerrainDetailMaterialConfig;
 }
@@ -259,6 +270,14 @@ export interface GrassEnvironmentConfig {
     windStrength?: number;
     colors?: readonly string[];
     seed?: string;
+    /** Blade curl range (arc amount, min..max). Shell default [0.12, 0.42] — raise for wind-combed scrub, lower for stiff turf. */
+    bladeBend?: readonly [number, number];
+    /** Tuft spread radius in meters — how far a clump's blades splay from its root. Shell default 0.16; wider reads as bushy clumps rather than lone blades. */
+    tuftRadius?: number;
+    /** Per-tuft brightness jitter 0..1 (shell default 0.28) — higher breaks up the field so it never reads as one repeated blade. */
+    colorVariation?: number;
+    /** 0..1 blend of blade normals toward straight-up (shell default 0.6). Low values light each blade plane individually and go dark when side-lit; high values light the field like a soft carpet. */
+    normalLift?: number;
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
@@ -393,7 +412,7 @@ export type SnowEnvironmentDescriptor = {
 } & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
-} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift">;
 export type OceanEnvironmentDescriptor = {
     kind: "ocean";
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
@@ -519,6 +538,13 @@ export interface PlotsWorldConfig extends WorldGridConfig {
 }
 export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
+    /** Atlas-backed tile rendering; cell glyphs map to atlas frame ids. */
+    tileSet?: {
+        atlas: SpriteAtlas;
+        tiles: Record<string, string>;
+    };
+    /** Render ordering key consumed by the shell tile renderer. */
+    sortingLayer?: string;
 }
 /**
  * A declared world shape passed to `defineGame`. The preferred model is the place feature from

package/dist/world/features.js

@@ -183,7 +183,7 @@ export function snow(config = {}) {
 }
 /** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */
 export function grass(config = {}) {
-    return withOptional({
+    return {
         kind: "grass",
         area: withAreaPosition(config.area ?? { w: 128, d: 128 }, config.position),
         density: config.density ?? 4,
@@ -191,7 +191,12 @@ export function grass(config = {}) {
         bladeWidth: config.bladeWidth ?? 0.035,
         windStrength: config.windStrength ?? 0.35,
         colors: config.colors ?? ["#3f7d2d", "#66a83f"],
-    }, config.seed === undefined ? undefined : { seed: config.seed });
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.bladeBend === undefined ? {} : { bladeBend: config.bladeBend }),
+        ...(config.tuftRadius === undefined ? {} : { tuftRadius: config.tuftRadius }),
+        ...(config.colorVariation === undefined ? {} : { colorVariation: config.colorVariation }),
+        ...(config.normalLift === undefined ? {} : { normalLift: config.normalLift }),
+    };
 }
 /** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */
 export function ocean(config = {}) {