@jgengine/core 0.11.0 → 0.13.0

package/dist/world/cityKind.d.ts

@@ -0,0 +1,314 @@
+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 { RoadPoint } from "./roads.js";
+import { type StreetFeatureKind } from "./streetGenerator.js";
+import { type CityBlockKind } from "./cityBlocks.js";
+/** The editor volume kind marking a box as a procedural city district. */
+export declare const CITY_KIND = "city";
+/** The editor volume kind that locally overrides a city's zone band/mix — a district in a district. */
+export declare const CITY_ZONE_KIND = "cityzone";
+/** Fully-defaulted city params parsed from a volume's `meta`. */
+export interface CityRules {
+    /** 1 = strict orthogonal grid (regular spacing, full through-streets); 0 = organic irregular net. */
+    gridness: number;
+    /** How much individual streets wander sideways. 0 = ruler-straight. */
+    curviness: number;
+    /** Density of branch lanes forking off the main streets, 0..1. */
+    branching: number;
+    /** How loopy the network is: 0 = a tree that dead-ends; 1 collapses to one closed circuit (a race
+     * track). High loopiness with branching/connectivity near zero is the "race circuit" corner. */
+    loopiness: number;
+    /** Extra chord edges knitting neighbors together — mesh density. 1 = a dense connected grid. */
+    connectivity: number;
+    /** Fraction of dangling ends kept as cul-de-sacs (vs reconnected into loops), 0..1. */
+    deadEnds: number;
+    /** Minimum curve radius (m): caps street wander curvature and corner tightness. */
+    minCurveRadius: number;
+    /** Shallowest corner (degrees) a street keeps — gentler bends straighten out. */
+    minTurnAngle: number;
+    /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
+    maxTurnAngle: 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. */
+    tunnels: boolean;
+    /** Target block size (street spacing) in meters. */
+    blockSize: number;
+    /** Cross-axis spacing multiplier — 2+ gives long skinny Manhattan blocks with avenue/street rhythm. */
+    blockAspect: number;
+    /** Fraction of blocks left unbuilt as intentional open space (parks/plazas/fields), 0..1. */
+    openSpace: number;
+    /** Fraction of every street's frontage that carries a building, 0..1 — the compactness dial. */
+    roadsideOccupancy: number;
+    /** Chance deep blocks fill their interior with a second row of buildings, 0..1. */
+    blockDensity: number;
+    /** Base gap from the sidewalk edge to a lot's front, in meters (class factors scale it). */
+    buildingRoadSetback: number;
+    /** Base side gap between neighboring lots, in meters (rowhouses nearly touch, farms spread). */
+    buildingSpacing: number;
+    /** How strongly development clumps: junctions grow denser, density drifts in smooth waves, and
+     * same-class runs form — 0 is uniform, 1 is strongly clustered. */
+    clusterStrength: number;
+    /** Main street width in meters (boulevards/avenues render wider, lanes narrower). */
+    streetWidth: number;
+    /** Share of avenues upgraded to median-divided boulevards, 0..1. */
+    boulevards: number;
+    /** Branch lanes render as gravel instead of asphalt (rural roads, alleys). */
+    gravelLanes: boolean;
+    /** District-wide surface: `auto` keeps asphalt mains (+ gravel lanes per `gravelLanes`); `gravel` unpaves everything. */
+    surface: "auto" | "gravel";
+    /** Zone banding: radial core-out, inverted (wealth at the rim), or spatially uniform mixing. */
+    profile: CityZoneProfile;
+    /** Fraction of the district radius covered by the core band. */
+    coreExtent: number;
+    /** Fraction of the district radius where the mid band ends and the edge begins. */
+    midExtent: number;
+    /** Weighted building-class mix of the core band. */
+    coreMix: WeightedParamEntry[];
+    /** Weighted building-class mix of the middle band. */
+    midMix: WeightedParamEntry[];
+    /** Weighted building-class mix of the edge band. */
+    edgeMix: WeightedParamEntry[];
+    /** Global lot footprint multiplier — estates want 1.5+, dense infill wants <1. */
+    lotScale: number;
+    /** Minimum building floors (district clamp over the class ranges). */
+    floorsMin: number;
+    /** Maximum building floors (district clamp over the class ranges). */
+    floorsMax: number;
+    /** Height of one floor in meters. */
+    floorHeight: number;
+    /** Street-tree planting density, 0..1. */
+    treeDensity: number;
+    /** Weighted species mix for street/park trees. */
+    treeMix: WeightedParamEntry[];
+    /** Street-light density along non-lane streets, 0..1. */
+    lightDensity: number;
+    /** Ring estate lots (mansions) with perimeter hedges and a gated gap. */
+    hedges: boolean;
+    /** Connect houses/estates/farms to their street with driveways. */
+    driveways: boolean;
+    /** Give commercial lots (shops, slabs) a parking pad behind the building. */
+    parking: boolean;
+    /** Unbuilt non-core blocks become crop-row farm fields instead of parks. */
+    fields: boolean;
+    /** Steepest ground (rise over run) a lot will build on; steeper slopes stay open cliff/canyon. */
+    maxSlope: number;
+    /** Lots below this ground height are skipped — keeps buildings out of rivers/lakes/canyons floors. */
+    minElevation: number;
+    /** Streets crossing ground below `minElevation` span it on a bridge deck instead of clipping. */
+    bridges: boolean;
+    /** Bridge silhouette: arched deck, overhead truss, or a plain beam span. */
+    bridgeStyle: "arch" | "truss" | "beam";
+    /** Render sidewalks flanking asphalt streets. */
+    sidewalks: boolean;
+    /** Sidewalk band width in meters at "street" hierarchy (boulevards scale up, lanes down). */
+    sidewalkWidth: number;
+    /** Building style palette id (see {@link BUILDING_STYLE_PALETTES}). */
+    style: BuildingStyle;
+    /** Seed string; same seed reproduces the same city. Empty falls back to the volume id. */
+    seed: string;
+}
+/** City defaults: a zoned mixed metropolis — towers downtown, slabs mid-ring, houses at the edge. */
+export declare const CITY_DEFAULTS: CityRules;
+/** The city parameter schema — drives the inspector sliders and `meta` parse via the studio seam. */
+export declare const CITY_SCHEMA: ParamSchema;
+/** Zone-override schema for `cityzone` volumes: pin a band and optionally a bespoke class mix. */
+export declare const CITY_ZONE_SCHEMA: ParamSchema;
+/** Parse a volume's `meta` into fully-defaulted city rules. @internal */
+export declare function readCityRules(meta: Record<string, unknown> | undefined): CityRules;
+/** One synthesized street: a world-space XZ polyline with width, hierarchy level, and surface. */
+export interface CityStreet {
+    id: string;
+    points: readonly RoadPoint[];
+    width: number;
+    level: "boulevard" | "avenue" | "street" | "lane";
+    surface: "asphalt" | "gravel";
+    /** Whether sidewalk ribbons flank this street. */
+    sidewalk: boolean;
+    /** 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`. */
+    features?: readonly {
+        kind: StreetFeatureKind;
+        from: number;
+        to: number;
+        bankHeight: number;
+    }[];
+}
+/** One crossing of two through streets: patch center/radius plus crosswalk arm directions. */
+export interface CityIntersection {
+    id: string;
+    x: number;
+    z: number;
+    /** Patch radius covering the crossing so the two ribbons never z-fight. */
+    radius: number;
+    level: CityStreet["level"];
+    /** Outgoing arm directions (radians) with the crossing road width, for crosswalk stripes. */
+    arms: readonly {
+        angle: number;
+        width: number;
+    }[];
+}
+/** One building lot: footprint, zone band, class, seeded floors, massing pieces, street anchor. */
+export interface CityLot {
+    id: string;
+    center: RoadPoint;
+    size: readonly [number, number];
+    rotationY: number;
+    floors: number;
+    jitter: number;
+    /** Building class the zone mix picked. */
+    class: CityLotClass;
+    /** Zone band the lot fell in (after overrides). */
+    zone: CityZoneBand;
+    /** Frontage point on the street centerline the lot faces. */
+    anchor: RoadPoint;
+    /** Deterministic massing pieces in lot-local space (see {@link CityLotPiece}). */
+    pieces: readonly CityLotPiece[];
+    /** Id of the parcel this building stands on. */
+    parcel?: string;
+}
+/** One closed city block: a face of the road graph, inset to curb and land boundaries. */
+export interface CityBlock {
+    id: string;
+    /** How the block is used: buildable, a park/plaza/field open space, or a landscaped buffer sliver. */
+    kind: CityBlockKind;
+    /** Land polygon behind the sidewalk band (world XZ, closed ring). */
+    polygon: readonly RoadPoint[];
+    /** Pavement-edge polygon (curb line). The sidewalk band lies between `curb` and `polygon`. */
+    curb: readonly RoadPoint[];
+    /** Land area in m². */
+    area: number;
+}
+/** One street-frontage edge of a parcel. */
+export interface CityParcelFrontageOut {
+    /** Street id (`street:N`) the frontage faces. */
+    road: string;
+    edgeStart: RoadPoint;
+    edgeEnd: RoadPoint;
+    /** Unit tangent along the frontage chord. */
+    tangent: RoadPoint;
+}
+/** One polygonal parcel subdivided from a block's street frontage. */
+export interface CityParcel {
+    id: string;
+    /** Owning block id. */
+    block: string;
+    polygon: readonly RoadPoint[];
+    /** Buildable polygon after front/side/rear setbacks ([] when setbacks consume the parcel). */
+    buildable: readonly RoadPoint[];
+    frontage: readonly CityParcelFrontageOut[];
+    area: number;
+    /** Usable depth from the frontage chord to the parcel rear, meters. */
+    depth: number;
+    isCorner: boolean;
+    /** built = carries a lot; vacant = intentionally unbuilt gap; yard = leftover strip kept green. */
+    kind: "built" | "vacant" | "yard";
+}
+/** One bridge deck spanning water: bank-to-bank polyline plus the silhouette style. */
+export interface CityBridge {
+    id: string;
+    points: readonly RoadPoint[];
+    width: number;
+    style: CityRules["bridgeStyle"];
+    /** Ground height at the banks — the deck reference the renderer drapes to. */
+    bankHeight: number;
+}
+/** One tunnel bore piercing a ridge: portal-to-portal polyline held at bank height. */
+export interface CityTunnel {
+    id: string;
+    points: readonly RoadPoint[];
+    width: number;
+    /** Ground height at the portals — the road floor stays flat at this height through the ridge. */
+    bankHeight: number;
+}
+/** One intentional open space: an unbuilt block, a block-interior courtyard, or a buffer sliver. */
+export interface CityPark {
+    id: string;
+    center: RoadPoint;
+    size: readonly [number, number];
+    rotationY: number;
+    type: "plaza" | "green" | "meadow" | "field" | "courtyard" | "buffer";
+    jitter: number;
+    /** Road-derived polygon (world XZ). Present on every block-pipeline park; the rect fields above
+     * are its bounding proxy for coarse consumers. */
+    polygon?: readonly RoadPoint[];
+    /** Crop-row polylines for `field` parks, clipped around farm lots. */
+    rows?: readonly (readonly RoadPoint[])[];
+}
+/** One placed tree: world XZ, species, and seeded scale/color jitter. */
+export interface CityTree {
+    x: number;
+    z: number;
+    species: CityTreeSpecies;
+    scale: number;
+    jitter: number;
+}
+/** One street light: curb position plus the yaw its arm faces (over the road). */
+export interface CityLight {
+    x: number;
+    z: number;
+    /** Yaw facing the road (engine rotationY convention). */
+    heading: number;
+}
+/** One hedge run: a thin box strip (estate perimeter). */
+export interface CityHedge {
+    center: RoadPoint;
+    /** Length along the run and thickness across it. */
+    size: readonly [number, number];
+    rotationY: number;
+}
+/** One driveway ribbon from a street to a lot. */
+export interface CityDriveway {
+    points: readonly RoadPoint[];
+    width: number;
+    surface: "gravel" | "pavement";
+}
+/** One parking pad behind a commercial lot. */
+export interface CityParking {
+    center: RoadPoint;
+    size: readonly [number, number];
+    rotationY: number;
+}
+/** A resolved city district: world-space network, zoned lots, parks, and furniture. */
+export interface ResolvedCity {
+    center: readonly [number, number, number];
+    size: readonly [number, number];
+    rotationY: number;
+    rules: CityRules;
+    streets: readonly CityStreet[];
+    intersections: readonly CityIntersection[];
+    bridges: readonly CityBridge[];
+    /** Tunnel bores piercing ridges — path features on continuous streets. */
+    tunnels: readonly CityTunnel[];
+    /** Closed road-derived block polygons — the land the street network encloses. */
+    blocks: readonly CityBlock[];
+    /** Polygonal parcels subdivided from block frontage. */
+    parcels: readonly CityParcel[];
+    lots: readonly CityLot[];
+    parks: readonly CityPark[];
+    trees: readonly CityTree[];
+    lights: readonly CityLight[];
+    hedges: readonly CityHedge[];
+    driveways: readonly CityDriveway[];
+    parkingLots: readonly CityParking[];
+}
+/** Extended resolve context: sibling `cityzone` volumes that override the band/mix locally. */
+export interface CityResolveContext extends SceneKindResolveContext {
+    zoneOverrides?: readonly SceneKindObject[];
+}
+/**
+ * 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
+ * rotated/translated into world space. Same volume (id, footprint, meta) over the same terrain
+ * always resolves to the identical plan. When `context` provides a ground sampler, lots respect
+ * the `maxSlope` cliff rule — hillside and canyon districts keep their steep faces open. When
+ * `context.zoneOverrides` carries sibling `cityzone` volumes, lots inside them adopt the override
+ * band/mix. Returns null without a usable footprint.
+ *
+ * @capability city-district resolve a `city` volume into deterministic streets, zoned lots, parks, and furniture
+ */
+export declare function resolveCityObject(object: SceneKindObject, context?: CityResolveContext): ResolvedCity | null;
+/** Registers the `city` + `cityzone` scene kinds (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerCityKind(): void;