@jgengine/core 0.18.0 → 0.19.0

package/dist/world/cityContent.js

@@ -13,18 +13,18 @@ export const CITY_LOT_CLASSES = [
 /** All filler classes, for validation and interior-pass allow-lists. */
 export const CITY_FILLER_CLASSES = ["garage", "depot"];
 const CLASS_PROFILES = {
-    tower: { width: [16, 24], depth: [14, 20], setbackFactor: 0.3, spacingFactor: 1, floors: [12, 34], backRow: true },
-    slab: { width: [14, 20], depth: [11, 15], setbackFactor: 0.5, spacingFactor: 1, floors: [4, 9], backRow: true },
-    shop: { width: [10, 15], depth: [8, 12], setbackFactor: 0.2, spacingFactor: 0.6, floors: [1, 2], backRow: true },
-    rowhouse: { width: [6, 8.5], depth: [9, 12], setbackFactor: 0.5, spacingFactor: 0.12, floors: [2, 3], backRow: true },
+    tower: { width: [14, 22], depth: [12, 20], setbackFactor: 0.15, spacingFactor: 0.35, floors: [12, 34], backRow: true },
+    slab: { width: [12, 20], depth: [10, 16], setbackFactor: 0.2, spacingFactor: 0.4, floors: [4, 9], backRow: true },
+    shop: { width: [8, 14], depth: [8, 12], setbackFactor: 0.05, spacingFactor: 0.15, floors: [1, 2], backRow: true },
+    rowhouse: { width: [5.5, 8], depth: [9, 13], setbackFactor: 0.2, spacingFactor: 0.05, floors: [2, 3], backRow: true },
     house: { width: [9, 12], depth: [8, 11], setbackFactor: 1, spacingFactor: 1, floors: [1, 2], backRow: true },
     mansion: { width: [18, 26], depth: [14, 20], setbackFactor: 2, spacingFactor: 1.6, floors: [2, 3], backRow: false },
     farmhouse: { width: [11, 14], depth: [9, 12], setbackFactor: 2.8, spacingFactor: 4, floors: [2, 2], backRow: false },
     barn: { width: [12, 16], depth: [9, 13], setbackFactor: 3.6, spacingFactor: 5, floors: [1, 1], backRow: false },
     silo: { width: [5, 6], depth: [5, 6], setbackFactor: 4, spacingFactor: 3, floors: [1, 1], backRow: false },
     // Interior-fill fillers: broad, plain footprints that pack the backs of dense blocks.
-    garage: { width: [18, 26], depth: [16, 22], setbackFactor: 0.3, spacingFactor: 0.4, floors: [2, 6], backRow: true },
-    depot: { width: [20, 30], depth: [18, 26], setbackFactor: 0.4, spacingFactor: 0.5, floors: [1, 2], backRow: true },
+    garage: { width: [16, 24], depth: [14, 20], setbackFactor: 0.2, spacingFactor: 0.3, floors: [2, 6], backRow: true },
+    depot: { width: [18, 28], depth: [16, 24], setbackFactor: 0.25, spacingFactor: 0.35, floors: [1, 2], backRow: true },
 };
 /**
  * Natural frontage-width range (meters) of a class's massing — what the plot-size class bias reads
@@ -131,6 +131,59 @@ function box(offset, size, role, options = {}) {
 function gable(offset, size, rotationY = 0) {
     return { shape: "gable", offset, size, rotationY, role: "roof", grounded: false, banded: false };
 }
+/**
+ * Finish a flat roof at height `top`: a recessed dark deck, a parapet upstand on all four edges,
+ * and seeded rooftop plant (mechanical units, a stair bulkhead, a tank). A city skyline is mostly
+ * roofs seen from above, so every flat-capped class runs through here instead of a bare slab.
+ */
+function flatRoofTop(pieces, width, depth, top, rng) {
+    const rail = Math.min(1.15, 0.55 + rng() * 0.55);
+    const wall = Math.min(0.55, Math.max(0.18, Math.min(width, depth) * 0.035));
+    const innerW = Math.max(0.4, width - wall * 2);
+    const innerD = Math.max(0.4, depth - wall * 2);
+    pieces.push(box([0, top, 0], [innerW, 0.14, innerD], "roof"));
+    pieces.push(box([0, top, (depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([0, top, -(depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    pieces.push(box([-(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    const deck = top + 0.14;
+    const units = innerW * innerD > 110 ? 1 + Math.floor(rng() * 3) : rng() < 0.7 ? 1 : 0;
+    for (let i = 0; i < units; i += 1) {
+        const uw = Math.min(innerW * 0.34, 1.6 + rng() * 2.4);
+        const ud = Math.min(innerD * 0.34, 1.4 + rng() * 2);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - uw), deck, (rng() - 0.5) * Math.max(0, innerD - ud)], [uw, 0.6 + rng() * 0.9, ud], "roof"));
+    }
+    if (rng() < 0.55) {
+        const bw = Math.min(innerW * 0.34, 2.2 + rng() * 1.6);
+        const bd = Math.min(innerD * 0.36, 2 + rng() * 1.4);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - bw), deck, (rng() - 0.5) * Math.max(0, innerD - bd)], [bw, 1.9 + rng() * 1.1, bd], "trim"));
+    }
+    if (rng() < 0.4) {
+        const r = Math.min(2.2, Math.min(innerW, innerD) * 0.26);
+        pieces.push({
+            shape: "cylinder",
+            offset: [(rng() - 0.5) * Math.max(0, innerW - r), deck, (rng() - 0.5) * Math.max(0, innerD - r)],
+            size: [r, 1.4 + rng() * 1.2, r],
+            rotationY: 0,
+            role: "trim",
+            grounded: false,
+            banded: false,
+        });
+    }
+}
+/**
+ * Street-level treatment for a commercial frontage: a plinth course wrapping the base, a recessed
+ * dark entrance on the street face, and a canopy over the sidewalk — so floor 1 never reads like
+ * floor 30. `overhang` is the plinth's outward step (0 keeps it flush for terraced classes).
+ */
+function streetLevel(pieces, width, depth, bandHeight, overhang, rng) {
+    pieces.push(box([0, 0, 0], [width + overhang, bandHeight, depth + overhang], "trim", { grounded: true }));
+    const doorW = Math.min(width * 0.32, 3.4);
+    const doorX = (rng() - 0.5) * Math.max(0, width - doorW * 1.6) * 0.5;
+    const face = depth / 2 + overhang / 2;
+    pieces.push(box([doorX, 0, face], [doorW, bandHeight * 0.76, 0.5], "roof", { grounded: true }));
+    pieces.push(box([doorX, bandHeight * 0.8, face + 0.6], [doorW * 1.5, 0.22, 1.3], "accent"));
+}
 /**
  * Compose the massing pieces for one lot. Deterministic per `rng` stream: the same class, size,
  * floors, and stream always yield the identical silhouette. Sizes are in meters, lot-local.
@@ -147,17 +200,22 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const h2 = H * (0.24 + rng() * 0.08);
                 const h3 = H - h1 - h2;
                 pieces.push(box([0, 0, 0], [width, h1, depth], "wall", { grounded: true, banded: true }));
+                // Occasional attached wing breaks the identical-rect streetwall without replacing the shaft.
+                if (width >= 16 && depth >= 14 && rng() < 0.42) {
+                    const wingW = width * (0.34 + rng() * 0.1);
+                    const side = rng() < 0.5 ? 1 : -1;
+                    pieces.push(box([side * (width / 2 - wingW / 2), 0, depth * 0.28], [wingW, h1 * (0.55 + rng() * 0.2), depth * 0.42], "wall", { grounded: true, banded: true }));
+                }
                 const w2 = width * (0.78 + rng() * 0.08);
                 const d2 = depth * (0.78 + rng() * 0.08);
                 pieces.push(box([0, h1, 0], [w2, h2, d2], "wall", { banded: true }));
                 const w3 = width * (0.55 + rng() * 0.1);
                 const d3 = depth * (0.55 + rng() * 0.1);
                 pieces.push(box([0, h1 + h2, 0], [w3, h3, d3], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w3 * 1.04, 0.5, d3 * 1.04], "trim"));
+                flatRoofTop(pieces, w3 * 1.04, d3 * 1.04, H, rng);
                 if (rng() < 0.35)
                     pieces.push(box([0, H + 0.5, 0], [1.2, 3 + rng() * 5, 1.2], "trim"));
-                else if (rng() < 0.5)
-                    pieces.push(box([0, H + 0.5, 0], [w3 * 0.4, 1.6, d3 * 0.4], "roof"));
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             else {
                 const h1 = H * (0.66 + rng() * 0.1);
@@ -165,32 +223,58 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const w2 = width * (0.72 + rng() * 0.1);
                 const d2 = depth * (0.72 + rng() * 0.1);
                 pieces.push(box([0, h1, 0], [w2, H - h1, d2], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w2 * 1.05, 0.45, d2 * 1.05], "trim"));
+                flatRoofTop(pieces, w2 * 1.05, d2 * 1.05, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             return pieces;
         }
         case "slab": {
-            pieces.push(box([0, 0, 0], [width, H, depth * 0.95], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.35, depth * 0.97], "trim"));
-            if (rng() < 0.6)
-                pieces.push(box([(rng() - 0.5) * width * 0.4, H + 0.35, 0], [width * 0.22, 2, depth * 0.3], "roof"));
+            // Full streetwall depth; irregular plans break the identical-cell silhouette.
+            if (width >= 14 && depth >= 12 && rng() < 0.55) {
+                const wing = width * (0.38 + rng() * 0.14);
+                const side = rng() < 0.5 ? 1 : -1;
+                const frontH = H * (0.92 + rng() * 0.12);
+                const wingH = H * (0.7 + rng() * 0.25);
+                pieces.push(box([0, 0, depth * 0.08], [width, frontH, depth * 0.62], "wall", { grounded: true, banded: true }));
+                pieces.push(box([side * (width / 2 - wing / 2), 0, -depth * 0.08], [wing, wingH, depth * 0.82], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 0.98, depth * 0.62, frontH, rng);
+                if (rng() < 0.45)
+                    flatRoofTop(pieces, wing * 1.02, depth * 0.78, wingH, rng);
+                streetLevel(pieces, width, depth * 0.62, Math.min(floorHeight * 1.05, frontH * 0.5), 0.25, rng);
+            }
+            else if (width >= 16 && depth >= 14 && rng() < 0.35) {
+                // Open mid-block court: street wall + two side wings, rear open as a service yard.
+                const wallT = Math.min(width, depth) * 0.28;
+                pieces.push(box([0, 0, (depth - wallT) / 2], [width, H, wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.75 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([-(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.7 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.01, wallT * 1.02, H, rng);
+                streetLevel(pieces, width, wallT, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
+            else {
+                pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
             return pieces;
         }
         case "shop": {
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true }));
-            pieces.push(box([0, H, 0], [width * 1.03, 0.5, depth * 1.03], "trim"));
+            flatRoofTop(pieces, width * 1.03, depth * 1.03, H, rng);
             // Front awning strip over the sidewalk face.
             pieces.push(box([0, Math.min(H - 0.4, 2.6), depth / 2 + 0.35], [width * 0.9, 0.35, 0.9], "accent"));
+            pieces.push(box([0, 0, depth / 2 - 0.05], [width * 0.82, Math.min(H * 0.62, 2.5), 0.4], "roof", { grounded: true }));
             return pieces;
         }
         case "rowhouse": {
-            pieces.push(box([0, 0, 0], [width * 0.96, H, depth * 0.85], "wall", { grounded: true, banded: true }));
+            pieces.push(box([0, 0, 0], [width * 0.98, H, depth * 0.92], "wall", { grounded: true, banded: true }));
             if (rng() < 0.55) {
-                pieces.push(gable([0, H, 0], [width * 0.96, 1.6 + rng() * 0.8, depth * 0.9]));
+                pieces.push(gable([0, H, 0], [width * 0.98, 1.6 + rng() * 0.8, depth * 0.96]));
             }
             else {
-                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.9], "trim"));
+                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.94], "trim"));
             }
+            streetLevel(pieces, width * 0.98, depth * 0.92, Math.min(floorHeight * 0.95, H * 0.5), 0.04, rng);
             return pieces;
         }
         case "house": {
@@ -273,13 +357,7 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
         case "garage": {
             // Parking structure: a plain banded box (the window bands read as deck slots) with a flat cap.
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.4, depth * 1.02], "trim"));
-            if (rng() < 0.6) {
-                // Stair/lift core poking above the roof deck.
-                const cx = (rng() - 0.5) * width * 0.5;
-                const cz = (rng() - 0.5) * depth * 0.4;
-                pieces.push(box([cx, H + 0.4, cz], [width * 0.16, 1.6 + rng() * 1.2, depth * 0.16], "accent"));
-            }
+            flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
             return pieces;
         }
         case "depot": {

package/dist/world/cityKind.d.ts

@@ -1,6 +1,8 @@
 import { type ParamSchema, type SceneKindObject, type SceneKindResolveContext, type WeightedParamEntry } from "../scene/sceneKinds.js";
 import { type BuildingStyle } from "./buildings.js";
 import { type CityLotClass, type CityLotPiece, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile } from "./cityContent.js";
+import { type CircuitCorner, type CircuitGate, type CircuitSealKind } from "./raceCircuit.js";
+import type { WorldSolid } from "./worldSolids.js";
 import type { RoadPoint } from "./roads.js";
 import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
@@ -29,6 +31,17 @@ export interface CityRules {
     minTurnAngle: number;
     /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
     maxTurnAngle: number;
+    /** Organic boundary clipping, 0..1. 0 fills the volume's rectangle; higher grows lobes and bays. */
+    outline: number;
+    /** Share of branch lanes grown as winding residential side streets, 0..1. */
+    residentialBranches: number;
+    /** Road-surface relief, 0..1. 0 is dead flat; 1 is ~22 m of rise and fall across a ~520 m district. */
+    elevation: number;
+    /** Steepest road grade (rise/run) the elevation pass allows on any street. */
+    maxGrade: number;
+    /** Circuit space-filling, 0..1. 0 is a flowing loop around an empty middle; higher folds the lap
+     * back through its own interior (switchbacks, hairpins, parallel runs). Circuit mode only. */
+    compactness: number;
     /** Lay parcels + buildings against the streets (city fabric). Off = bare roads/track, no plots. */
     fabric: boolean;
     /** Streets bore through ridges on tunnel decks instead of climbing over them. */
@@ -84,6 +97,10 @@ export interface CityRules {
     treeMix: WeightedParamEntry[];
     /** Street-light density along non-lane streets, 0..1. */
     lightDensity: number;
+    /** Parked-vehicle density along street curbs and inside parking pads, 0..1. */
+    parkedCars: number;
+    /** Junction control density, 0..1: mast-arm signals on arterial crossings, sign posts below them. */
+    signals: number;
     /** Ring estate lots (mansions) with perimeter hedges and a gated gap. */
     hedges: boolean;
     /** Connect houses/estates/farms to their street with driveways. */
@@ -104,6 +121,22 @@ export interface CityRules {
     sidewalks: boolean;
     /** Sidewalk band width in meters at "street" hierarchy (boulevards scale up, lanes down). */
     sidewalkWidth: number;
+    /** Lift an instanced street race out of the district's own streets (see {@link ResolvedRace}). */
+    race: boolean;
+    /** Target race lap length in meters — the search keeps the cycle closest to this. */
+    raceLapLength: number;
+    /** 0 races any street; 1 keeps the lap on avenues and boulevards only. */
+    raceArterial: number;
+    /** Ordered checkpoint gates placed around the lap. */
+    raceCheckpoints: number;
+    /** Laps the race runs. */
+    raceLaps: number;
+    /** Close every side street leaving the lap with barriers — what makes it an instanced event. */
+    raceSeals: boolean;
+    /** Starting grid slots behind the line (0 = no grid). */
+    raceGridSlots: number;
+    /** Radius (m) the racing line is worked toward at the lap's junction corners. */
+    raceCornerRadius: number;
     /** Building style palette id (see {@link BUILDING_STYLE_PALETTES}). */
     style: BuildingStyle;
     /**
@@ -132,6 +165,9 @@ export interface CityStreet {
     surface: "asphalt" | "gravel";
     /** Whether sidewalk ribbons flank this street. */
     sidewalk: boolean;
+    /** Grade-limited road-surface height per point, present only when `elevation` is above 0. This is
+     * ROAD relief, not the terrain the district stands on. */
+    heights?: readonly number[];
     /** Cul-de-sac turning bulb at a dangling end, when the lane never reconnected. */
     bulb?: RoadPoint;
     /** Bridge/tunnel spans along this street as `[from, to]` index windows into `points`. */
@@ -277,6 +313,97 @@ export interface CityParking {
     size: readonly [number, number];
     rotationY: number;
 }
+/** Silhouette class of a parked vehicle — sizes the body the renderer instances. */
+export type CityVehicleKind = "car" | "van" | "truck";
+/** One parked vehicle standing at a curb or nose-in inside a parking pad. */
+export interface CityVehicle {
+    x: number;
+    z: number;
+    /** Yaw the body points down (engine rotationY convention). */
+    rotationY: number;
+    kind: CityVehicleKind;
+    /** Seeded body-paint index; the renderer maps it into its own palette. */
+    paint: number;
+    /** Where it stands, so the renderer drapes it onto carriageway or pad height. */
+    stall: "curb" | "lot";
+}
+/** One junction control on an approach arm: an arterial mast-arm signal, or a plain sign post. */
+export interface CitySignal {
+    x: number;
+    z: number;
+    /** Yaw the head faces — into the traffic approaching down this arm. */
+    heading: number;
+    kind: "signal" | "sign";
+    /** How far the mast arm reaches over the carriageway, to the right of {@link CitySignal.heading}. */
+    reach: number;
+}
+/** One street closed off where it leaves the race lap: world XZ, the yaw down the sealed street, and
+ * the width the barrier run spans. */
+export interface CityRaceSeal {
+    x: number;
+    z: number;
+    heading: number;
+    width: number;
+    kind: CircuitSealKind;
+}
+/** One kerb strip hugging a corner's road edge, as a world-space polyline to stripe. */
+export interface CityRaceKerb {
+    points: readonly RoadPoint[];
+    /** Strip width across, meters. */
+    width: number;
+    /** Which side of travel the strip sits on: -1 left, 1 right. */
+    side: -1 | 1;
+    /** Alternating stripe length along the run, meters. */
+    stripe: number;
+    /** Corner this kerb belongs to (index into {@link ResolvedRace.corners}). */
+    corner: number;
+}
+/** The start/finish line: where it is, which way cars face, and the painted line across the road. */
+export interface CityRaceStart {
+    x: number;
+    z: number;
+    /** Yaw cars face on the grid (direction of travel). */
+    heading: number;
+    /** The two road-edge ends of the painted line. */
+    line: readonly [RoadPoint, RoadPoint];
+    /** Arc-length position of the line along the lap, meters. */
+    distance: number;
+    width: number;
+}
+/** One staggered spawn behind the start line. */
+export interface CityRaceGridSlot {
+    x: number;
+    z: number;
+    heading: number;
+}
+/**
+ * An instanced street race lifted out of the district's OWN streets: a closed lap through the city,
+ * with every side street leaving it sealed off. World space, like the rest of {@link ResolvedCity}.
+ */
+export interface ResolvedRace {
+    /** Closed lap centerline — the last point joins the first. */
+    centerline: readonly RoadPoint[];
+    /** Road width at each centerline point, inherited from the streets the lap follows. */
+    widths: readonly number[];
+    /** Road-surface height per point, present only when the district carries `elevation`. */
+    heights?: readonly number[];
+    /** Lap length, meters. */
+    length: number;
+    /** Ids of the district streets the lap runs on — style exactly these as track surface. */
+    streets: readonly string[];
+    seals: readonly CityRaceSeal[];
+    corners: readonly CircuitCorner[];
+    kerbs: readonly CityRaceKerb[];
+    /** Ordered gates, finish last — ready for `raceTrack({ checkpoints, laps })`. */
+    checkpoints: readonly CircuitGate[];
+    laps: number;
+    start: CityRaceStart;
+    grid: readonly CityRaceGridSlot[];
+    /** Arc-length fractions (0..1) where each timing sector begins; the first is always 0. */
+    sectors: readonly number[];
+    /** Tightest radius (m) the finished racing line actually holds. */
+    tightestRadius: number;
+}
 /** A resolved city district: world-space network, zoned lots, parks, and furniture. */
 export interface ResolvedCity {
     center: readonly [number, number, number];
@@ -299,7 +426,19 @@ export interface ResolvedCity {
     hedges: readonly CityHedge[];
     driveways: readonly CityDriveway[];
     parkingLots: readonly CityParking[];
+    /** Parked vehicles along the curbs and inside the parking pads. */
+    vehicles: readonly CityVehicle[];
+    /** Traffic signals and sign posts, one per controlled junction approach. */
+    signals: readonly CitySignal[];
+    /** The instanced street race through these streets, when `race` is on and a lap could be found. */
+    race?: ResolvedRace;
 }
+/**
+ * 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 declare function citySolids(city: ResolvedCity, sampleHeight?: (x: number, z: number) => number): WorldSolid[];
 /** Extended resolve context: sibling `cityzone` volumes that override the band/mix locally. */
 export interface CityResolveContext extends SceneKindResolveContext {
     zoneOverrides?: readonly SceneKindObject[];