@jgengine/core 0.11.0 → 0.12.0

package/dist/world/pathNetwork.d.ts

@@ -0,0 +1,159 @@
+/** A path vertex in the volume-local XZ frame. */
+export type PathVec2 = readonly [number, number];
+/** Road hierarchy, widest to narrowest — shared by the city fabric and the renderer. */
+export type PathLevel = "boulevard" | "avenue" | "street" | "lane";
+/** A path feature spanning part of an edge/street: a bridge deck over a gap or a tunnel bore under a ridge. */
+export type PathFeatureKind = "bridge" | "tunnel";
+/** The generator's chosen topology family: an open street `net`, or a closed `circuit` loop. */
+export type PathNetworkMode = "net" | "circuit";
+/** One graph node: a junction, a dead end, or a mid-street bend, with its connection count. */
+export interface PathNode {
+    id: number;
+    x: number;
+    z: number;
+    degree: number;
+}
+/** One atomic node-to-node edge — the fabric graph consumes these (welds at shared node coords). */
+export interface PathEdge {
+    id: number;
+    /** Endpoint node ids. */
+    a: number;
+    b: number;
+    /** Sampled centerline; `points[0]` sits exactly on node `a`, the last on node `b`. */
+    points: PathVec2[];
+    width: number;
+    level: PathLevel;
+    /** True when this edge belongs to the main closed loop (circuit mode). */
+    loop: boolean;
+}
+/** A feature span carried by a street: a `[from, to]` index window into the street's `points`. */
+export interface PathFeatureSpan {
+    kind: PathFeatureKind;
+    from: number;
+    to: number;
+    /** Ground height at each bank/portal — the deck/floor reference the renderer drapes to. */
+    bankHeight: number;
+}
+/** One chained through-street: a maximal run of edges through degree-2 nodes, for rendering + furniture. */
+export interface PathStreet {
+    id: number;
+    /** Ordered node ids the chain visits; first === last when `loop`. */
+    nodes: number[];
+    /** Smoothed, turn-clamped centerline. */
+    points: PathVec2[];
+    width: number;
+    level: PathLevel;
+    /** Closed chain (a circuit lap or an inner ring). */
+    loop: boolean;
+    /** Cul-de-sac turning bulb when the street ends at a dangling node. */
+    bulb?: PathVec2;
+    /** Bridge/tunnel spans along this street, if any. */
+    features: PathFeatureSpan[];
+}
+/** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
+export interface PathJunction {
+    x: number;
+    z: number;
+    radius: number;
+    level: PathLevel;
+    /** Outgoing arm directions (radians) with the crossing street width, for crosswalks/patches. */
+    arms: {
+        angle: number;
+        width: number;
+    }[];
+}
+/** One dangling street end kept as a cul-de-sac: node position plus the heading pointing off the road. */
+export interface PathDeadEnd {
+    node: number;
+    x: number;
+    z: number;
+    /** Yaw (radians) facing outward, away from the network. */
+    heading: number;
+    width: number;
+}
+/** A resolved path feature in world-of-the-volume space: a bridge deck or tunnel bore centerline. */
+export interface PathFeature {
+    kind: PathFeatureKind;
+    points: PathVec2[];
+    width: number;
+    bankHeight: number;
+}
+/** The fully-resolved network in volume-local coords. */
+export interface PathNetwork {
+    mode: PathNetworkMode;
+    nodes: PathNode[];
+    /** Atomic edges — feed to the block/parcel fabric. */
+    edges: PathEdge[];
+    /** Chained through-streets — feed to the renderer, furniture, and analysis. */
+    streets: PathStreet[];
+    junctions: PathJunction[];
+    deadEnds: PathDeadEnd[];
+    bridges: PathFeature[];
+    tunnels: PathFeature[];
+    /** Independent cycle count (E − V + components): 0 = pure tree, ≥1 = has loops. */
+    loops: number;
+}
+/** Fully-defaulted slider set the generator reads. */
+export interface PathNetworkRules {
+    seed: string;
+    /** 1 = regular lattice nodes; 0 = organic scatter. */
+    gridness: number;
+    /** 0 = tree (dead-ends); 1 = a single closed circuit. */
+    loopiness: number;
+    /** Extra chord edges between neighbors → mesh density. */
+    connectivity: number;
+    /** Spur-lane density forking off the mains. */
+    branching: number;
+    /** Fraction of dangling ends kept as cul-de-sacs (vs reconnected). */
+    deadEnds: number;
+    /** Target node spacing / block size, world units. */
+    segmentLength: number;
+    /** Cross-axis spacing multiplier (≥1 = long skinny Manhattan blocks). */
+    aspect: number;
+    /** Sideways wander amplitude, 0..1. */
+    winding: number;
+    /** Minimum curve radius (m) — caps wander curvature and corner tightness. */
+    minCurveRadius: number;
+    /** Shallowest corner (degrees) a street keeps — gentler bends are straightened. */
+    minTurnAngle: number;
+    /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
+    maxTurnAngle: number;
+    /** Base street width; the hierarchy scales off it. */
+    width: number;
+    /** Share of avenues upgraded to boulevards, 0..1. */
+    boulevards: number;
+}
+/** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
+export interface PathNetworkContext {
+    /** Volume-local ground height sampler. */
+    heightAt?: (x: number, z: number) => number;
+    /** Ground below this (local) height is a gap streets bridge over. */
+    minElevation?: number;
+    /** Emit bridge decks over sub-`minElevation` gaps. */
+    bridges?: boolean;
+    /** Emit tunnel bores where the ground rises this far above a span's banks. */
+    tunnels?: boolean;
+    /** Ridge height above the banks that triggers a tunnel. Default 6. */
+    tunnelClearance?: number;
+}
+/**
+ * Hard turn-angle clamp on a polyline with fixed endpoints: interior corners gentler than `minRad`
+ * are straightened away (deliberate winding only, no micro-wiggle) and corners sharper than `maxRad`
+ * are beveled — the corner vertex is replaced by two points pulled back along each leg, which
+ * strictly reduces the angle. Endpoints never move, so a graph node stays welded.
+ * @internal
+ */
+export declare function clampTurns(points: readonly PathVec2[], minRad: number, maxRad: number): PathVec2[];
+/** Decide which topology family the sliders call for. Circuit wins when loops dominate and both
+ *  branching and mesh connectivity are low — exactly the "race track" corner of the slider space.
+ *  @internal */
+export declare function pathNetworkMode(rules: PathNetworkRules): PathNetworkMode;
+/**
+ * Resolve a full path network from its rules inside a volume of half-extents `hx`×`hz`. Deterministic
+ * per `(rules.seed, hx, hz, context)`. Pass a {@link PathNetworkContext} with a ground sampler to turn
+ * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
+ * world space.
+ *
+ * @capability path-network build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ */
+export declare function buildPathNetwork(rules: PathNetworkRules, hx: number, hz: number, context?: PathNetworkContext): PathNetwork;