@jgengine/core 0.17.0 → 0.18.1

package/dist/world/cityKind.d.ts

@@ -1,6 +1,7 @@
 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 { RoadPoint } from "./roads.js";
 import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
@@ -29,6 +30,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 +96,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 +120,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 +164,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 +312,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,6 +425,12 @@ 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;
 }
 /** Extended resolve context: sibling `cityzone` volumes that override the band/mix locally. */
 export interface CityResolveContext extends SceneKindResolveContext {