@jgengine/core 0.14.0 → 0.15.0

package/dist/world/roads.d.ts

@@ -15,9 +15,39 @@ export interface RoadRibbon {
  * @internal — the corner-smoothing behind `<AuthoredPaths>`; games get it for free through the render.
  */
 export declare function roundPathCorners(points: readonly RoadPoint[], radius: number, cornerSegments?: number): RoadPoint[];
+/**
+ * The single owning table of ground-decal Y offsets, in world units above the sampled terrain.
+ *
+ * Contract — the vertical stacking order is `terrain < road < junction < marking < glow`, and every
+ * ground overlay must draw from THIS table rather than picking a local magic epsilon (the old
+ * scatter of `0.08` ribbons, `+0.02` discs, `0.05` markings, `0.055–0.1` playground fudge factors
+ * is exactly the z-fighting this removes).
+ *
+ * - `road` and `junction` deliberately share one layer: {@link buildJunctionSurface} welds its
+ *   boundary vertices onto the exact corner vertices where the trimmed ribbon ends
+ *   ({@link trimPathAtJunctions}), so the two surfaces meet at a shared seam and never stack — they
+ *   must sit at the same height or the seam would tear. Do NOT bump `junction` above `road`.
+ * - `marking` is the ONLY permitted coplanar overlay (lane paint sits on top of asphalt at the same
+ *   XZ). Its Y separation alone is not enough to beat depth precision on sloped ground: consumers
+ *   rendering markings MUST ALSO set a negative `polygonOffset` and/or a higher `renderOrder` on the
+ *   marking material (renderer-side — this table only owns the Y term).
+ * - `glow` sits above markings for emissive decals (crosswalk glow, selection halos).
+ *
+ * Values are chosen with real separation so a small terrain slope can't invert the order.
+ */
+export declare const GROUND_DECAL_LAYERS: {
+    /** Road ribbons. */
+    readonly road: 0.06;
+    /** Junction surfaces — SAME layer as `road` because they are seam-welded, never stacked. */
+    readonly junction: 0.06;
+    /** Lane markings / crosswalks — the only coplanar overlay; also set polygonOffset/renderOrder. */
+    readonly marking: 0.11;
+    /** Emissive decals above markings (glow, halos). */
+    readonly glow: 0.14;
+};
 /** Options for {@link buildRoadRibbon}. */
 export interface RoadRibbonOptions {
-    /** Lift above the sampled ground so the ribbon never z-fights the terrain. Default 0.08. */
+    /** Lift above the sampled ground so the ribbon never z-fights the terrain. Default {@link GROUND_DECAL_LAYERS}.road. */
     elevation?: number;
     /** Longest centerline step before the polyline is subdivided to drape over relief. Default 4. */
     maxSegmentLength?: number;
@@ -35,10 +65,14 @@ export interface DashExclusion {
     radius: number;
 }
 /**
- * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
- * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
- * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
- * Pure geometry; the shell meshes the result with the asphalt material.
+ * Build a flat, ground-draped disc patch centered on `center` — a triangle fan of `segments` sides
+ * (default 16), every vertex draped at `sampleHeight + elevation`.
+ *
+ * @deprecated This floats a disc slightly above the crossing ribbons, which still overlaps and
+ * z-fights them. Prefer {@link buildJunctionSurface} (with {@link trimPathAtJunctions}, or the
+ * all-in-one {@link buildTrimmedIntersections}): it trims the ribbons back to the junction boundary
+ * and welds one seam-shared surface, with no overlap and no floating disc. Kept so existing callers
+ * don't break this round.
  */
 export declare function buildJunctionPatch(center: RoadPoint, radius: number, sampleHeight: (x: number, z: number) => number, options?: {
     elevation?: number;
@@ -70,3 +104,258 @@ export declare function nearestOnPath(path: readonly RoadPoint[], x: number, z:
 export declare function isOnRoad(path: readonly RoadPoint[], width: number, x: number, z: number): boolean;
 /** Total arc length of a centerline in world units. */
 export declare function pathLength(path: readonly RoadPoint[]): number;
+/**
+ * The minimal junction shape this geometry needs — a node position plus its outgoing arms. Matches
+ * the structural subset of `StreetJunction` (streetGenerator) so a network's `junctions` can be fed
+ * straight in. Arm `angle` follows the generator convention `atan2(dx, dz)`, i.e. the outward unit
+ * direction of an arm is `[sin(angle), cos(angle)]`.
+ */
+export interface RoadJunctionInput {
+    x: number;
+    z: number;
+    arms: readonly {
+        angle: number;
+        width: number;
+    }[];
+}
+/** Tunables shared by {@link trimPathAtJunctions}, {@link buildJunctionSurface}, and {@link buildTrimmedIntersections}. */
+export interface JunctionGeometryOptions {
+    /**
+     * Requested curb-return radius at exterior corners between adjacent approaches. Default 2.
+     * Clamped per corner by the two adjacent road widths, the corner chord, and available mouth gap —
+     * never inflates the paved conflict area the way an apron pull-back would.
+     */
+    curbReturnRadius?: number;
+    /**
+     * Extra clearance beyond the projected crossing half-width so ribbons stop just outside the
+     * carriageway union. Default 0.25. Does **not** include the curb-return radius (returns live only
+     * on the exterior corner arcs).
+     */
+    apronMargin?: number;
+    /** Samples per curb-return fillet arc between two adjacent approach corners. Default 4. */
+    filletSegments?: number;
+    /** Lift above sampled ground. Defaults to {@link GROUND_DECAL_LAYERS}.junction (== road: seam-shared). */
+    elevation?: number;
+    /** Longest step before draping subdivision, matching {@link buildRoadRibbon}. Default 4. */
+    maxSegmentLength?: number;
+    /** World-space tolerance for matching a path vertex onto a junction node. Default 1e-6. */
+    nodeEpsilon?: number;
+}
+/** One trim of a ribbon end back to a junction boundary — the seam the welded surface attaches to. */
+export interface RoadCut {
+    /** Index (into the `junctions` array passed to the trimmer) of the junction this cut welds to. */
+    junctionIndex: number;
+    /** Whether the cut is at the start or the end of the returned sub-path. */
+    at: "start" | "end";
+    /** Trimmed centerline endpoint — the point on the junction boundary the ribbon now ends at. */
+    center: RoadPoint;
+    /** Unit direction pointing from the junction center outward into the road. */
+    direction: readonly [number, number];
+    /** Left edge corner at the cut (`center` + width/2 along the local perpendicular). */
+    left: RoadPoint;
+    /** Right edge corner at the cut (`center` − width/2 along the local perpendicular). */
+    right: RoadPoint;
+    /** Arc-length the ribbon was pulled back from the junction center. */
+    apron: number;
+}
+/** A street sub-path after trimming, plus the cuts (0–2) that shortened it. Feed `path` to {@link buildRoadRibbon}. */
+export interface TrimmedRoad {
+    /** Trimmed centerline (≥2 points) ready for meshing. */
+    path: RoadPoint[];
+    /** Cuts applied to this sub-path — at most one `start` and one `end`. */
+    cuts: RoadCut[];
+}
+/**
+ * Cut a street centerline back from the junctions it passes through so its ribbon ENDS at the
+ * junction boundary instead of ploughing through the node. Junctions are matched to path vertices
+ * within `nodeEpsilon` (endpoints and interior vertices alike); a junction sitting on an interior
+ * vertex SPLITS the path into two independently-trimmed sub-paths. Each cut records the exact
+ * boundary point and the road's left/right edge corners there, so {@link buildJunctionSurface} can
+ * weld its polygon onto the identical vertices with no overlap.
+ *
+ * Pure geometry, allocation-aware, bounded by the vertex and junction counts. Returns one
+ * {@link TrimmedRoad} per surviving sub-path (a mid-polyline junction yields two).
+ */
+export declare function trimPathAtJunctions(path: readonly RoadPoint[], width: number, junctions: readonly RoadJunctionInput[], options?: JunctionGeometryOptions): TrimmedRoad[];
+/** Options for {@link trimBandAtJunctions} — junction geometry tunables plus a band-specific clearance. */
+export interface BandTrimOptions extends JunctionGeometryOptions {
+    /** Extra outward clearance added to every junction's apron radius before cutting the band. Default 0. */
+    clearance?: number;
+}
+/**
+ * Cut an offset band (a polyline running PARALLEL to a street — e.g. a sidewalk from
+ * `Street.sidewalks.{left,right}`) out of every junction's apron, so the band stops at the crossing
+ * instead of sailing straight through it. Unlike {@link trimPathAtJunctions} the band never passes
+ * through a node, so it is clipped by DISTANCE: each junction contributes a circular apron of radius
+ * `max arm half-width + apronMargin + bandWidth/2 + clearance` (plus a small curb-return allowance),
+ * and any part of the band inside any apron circle is removed, splitting the band into the sub-paths
+ * that survive outside. Entry/exit points land exactly on the apron boundary. A band that never
+ * enters an apron passes through as a single untouched copy.
+ *
+ * Pure geometry, deterministic, bounded by the band-vertex and junction counts.
+ *
+ * @example
+ * ```ts
+ * // Same `junctions` you fed the roads; trim both sidewalks of a street around every node.
+ * const left = trimBandAtJunctions(street.sidewalks.left, street.sidewalkWidth, junctions);
+ * const right = trimBandAtJunctions(street.sidewalks.right, street.sidewalkWidth, junctions);
+ * for (const sub of [...left, ...right]) meshes.push(buildRoadRibbon(sub, street.sidewalkWidth, sampleHeight));
+ * ```
+ *
+ * @capability world-intersections trim offset sidewalk/parallel bands around junction aprons
+ */
+export declare function trimBandAtJunctions(bandPath: readonly RoadPoint[], bandWidth: number, junctions: readonly RoadJunctionInput[], options?: BandTrimOptions): RoadPoint[][];
+/** One approach feeding {@link buildJunctionSurface}: the exact draped corner vertices a ribbon ends at. */
+export interface JunctionApproach {
+    /** Junction-boundary centerline point where the ribbon ends. */
+    center: RoadPoint;
+    /** Left edge corner (draped `[x, y, z]`) — the ribbon's terminal left vertex. */
+    left: readonly [number, number, number];
+    /** Right edge corner (draped `[x, y, z]`) — the ribbon's terminal right vertex. */
+    right: readonly [number, number, number];
+    /** Unit direction from the node into this approach. Present on approaches emitted by {@link buildTrimmedIntersections}. */
+    direction?: readonly [number, number];
+    /** Unit tangent in the source street's authored path order. */
+    sourceTangent?: readonly [number, number];
+    /** Source street index, so consumers never have to infer identity from rendered vertices. */
+    streetIndex?: number;
+    /** Source trimmed-ribbon index, parallel to {@link TrimmedIntersections.trimmed}. */
+    trimmedIndex?: number;
+    /** Which end of the source trimmed path meets this junction. */
+    cutAt?: "start" | "end";
+    /** Full pavement width at this mouth. */
+    width?: number;
+    /** Sidewalk widths attached to the source path's left and right pavement edges. */
+    sidewalkWidths?: IntersectionSidewalkWidths;
+    /** Lane-paint declaration inherited from the source street. */
+    markings?: IntersectionMarkingIntent;
+}
+/**
+ * Build a tangent-continuous centerline through a two-arm junction. This is the shared path for
+ * paint, medians, curbs, or other linear dressing that should follow a bend but stop at crossings.
+ * Returns `null` for anything other than exactly two approaches.
+ * @capability world-intersections connect linear road dressing through two-arm bends
+ */
+export declare function buildJunctionConnector(junction: {
+    x: number;
+    z: number;
+}, approaches: readonly JunctionApproach[], segments?: number): RoadPoint[] | null;
+/**
+ * Weld one triangulated junction surface onto the corner vertices its incident ribbons END at
+ * (from {@link trimPathAtJunctions}). Corners are grouped by approach (so unequal widths cannot
+ * interleave a neighbour between a mouth pair), ordered around the node, and bridged as follows:
+ *
+ * - **Road mouth** — the straight end-edge of the approach (shared seam with the ribbon).
+ * - **Through edge (~180°)** — straight chord along the continuing curb (T-junction far side).
+ * - **Exterior corner** — a compact circular curb-return of radius ≤ `curbReturnRadius`, clamped by
+ *   adjacent widths and chord length; bows *outward* only, never a plaza disc.
+ * - **Two-arm turn** — both edges get the same compact returns (no diagonal cap, no remote tangent).
+ *
+ * The boundary is ear-clipped so every triangle faces +Y. Draped height matches
+ * {@link buildRoadRibbon}. Mouth corners are the approach corners verbatim.
+ */
+export declare function buildJunctionSurface(junction: {
+    x: number;
+    z: number;
+}, approaches: readonly JunctionApproach[], sampleHeight: (x: number, z: number) => number, options?: JunctionGeometryOptions): RoadRibbon;
+/** Widths of renderer-neutral sidewalk bands on each authored side of a street. */
+export interface IntersectionSidewalkWidths {
+    /** Width beyond the left pavement edge. Omit or use zero for no band. */
+    left?: number;
+    /** Width beyond the right pavement edge. Omit or use zero for no band. */
+    right?: number;
+}
+/** One longitudinal lane-marking ribbon, offset left (+) or right (-) from the authored centerline. */
+export interface IntersectionMarkingLine {
+    /** Signed centerline offset in world units. Default 0. */
+    offset?: number;
+    /** Paint width. Default 0.15. */
+    width?: number;
+}
+/** Paint intent carried through trimming without renderer inference. */
+export interface IntersectionMarkingIntent {
+    /** Longitudinal marking ribbons. */
+    lines?: readonly IntersectionMarkingLine[];
+    /** Emit a transverse stop line at this street's multi-arm approaches. Default false. */
+    stopLine?: boolean;
+}
+/** One street to trim + mesh through {@link buildTrimmedIntersections}. */
+export interface IntersectionStreet {
+    /** Street centerline; endpoints/vertices coincide with junction nodes. */
+    path: readonly RoadPoint[];
+    /** Full road width. */
+    width: number;
+    /** Optional, independently-sized bands beyond the authored left/right pavement edges. */
+    sidewalks?: IntersectionSidewalkWidths;
+    /** Optional lane-paint declaration. Omission preserves the previous pavement-only output. */
+    markings?: IntersectionMarkingIntent;
+}
+/** Renderer-ready output of {@link buildTrimmedIntersections}: trimmed ribbons + welded junction surfaces. */
+export interface TrimmedIntersections {
+    /** One trimmed ribbon per surviving sub-path (a through-street contributes two). */
+    ribbons: RoadRibbon[];
+    /** The trimmed sub-paths, parallel to `ribbons`, for lane markings / analysis. */
+    trimmed: TrimmedRoad[];
+    /** One welded surface per junction that had ≥1 incident approach. */
+    junctions: RoadRibbon[];
+    /** Index into the input `junctions` for each surface, parallel to `junctions` above. */
+    junctionIndices: number[];
+    /** Exact ribbon-mouth approaches for each surface, parallel to `junctions`; useful for dressing. */
+    junctionApproaches: JunctionApproach[][];
+    /** Source street index for each entry in `trimmed`/`ribbons`. */
+    trimmedStreetIndices: number[];
+    /** Source pavement width for each entry in `trimmed`/`ribbons`. */
+    trimmedWidths: number[];
+    /** Source paint intent for each entry in `trimmed`/`ribbons`. */
+    trimmedMarkings: (IntersectionMarkingIntent | undefined)[];
+    /** Road-side sidewalk bands, excluding junction interiors. */
+    sidewalks: RoadRibbon[];
+    /** Sidewalk curb-return aprons around junction pavement; road-mouth edges and center fill are absent. */
+    sidewalkAprons: RoadRibbon[];
+    /** Input junction index for each entry in `sidewalkAprons`. */
+    sidewalkApronJunctionIndices: number[];
+}
+/**
+ * Trim a set of streets against a set of junctions and weld the crossing surfaces in one call — the
+ * ergonomic entry the shell/playground consume for meshing.
+ *
+ * Each street is trimmed by {@link trimPathAtJunctions} (through-streets split in two), each surviving
+ * sub-path is meshed with {@link buildRoadRibbon}, and every junction that any ribbon actually ends
+ * at gets one {@link buildJunctionSurface}. The junction's boundary vertices are read back BITWISE
+ * from the ribbons' terminal cross-sections, so ribbon and surface share the exact same floats at
+ * the seam — no overlap, no z-fighting, no floating disc. Ribbons and surfaces both live on the
+ * seam-shared {@link GROUND_DECAL_LAYERS}.road/.junction layer. Deterministic (junctions emitted in
+ * ascending index order) and bounded by the street/junction counts.
+ *
+ * @capability world-intersections trim streets at junctions and weld curb-return crossing surfaces in one call
+ */
+export declare function buildTrimmedIntersections(streets: readonly IntersectionStreet[], junctions: readonly RoadJunctionInput[], sampleHeight: (x: number, z: number) => number, options?: JunctionGeometryOptions): TrimmedIntersections;
+/** Tunables for {@link buildIntersectionMarkings}. */
+export interface IntersectionMarkingOptions {
+    /** Clearance between a multi-arm road mouth and longitudinal paint / stop lines. Default 1. */
+    mouthClearance?: number;
+    /** Default longitudinal paint width. Default 0.15. */
+    lineWidth?: number;
+    /** Transverse stop-line width along the approach. Default 0.35. */
+    stopLineWidth?: number;
+    /** Gap left between a stop line and each pavement edge. Default 0.5. */
+    stopLineEdgeClearance?: number;
+    /** Samples in a degree-2 marking connector. Default 8. */
+    connectorSegments?: number;
+    /** Painted dash length. Omit or use zero for a solid line. */
+    dashLength?: number;
+    /** Gap between painted dashes. Default 3 when `dashLength` is positive. */
+    dashGap?: number;
+    /** Marking lift above terrain. Default {@link GROUND_DECAL_LAYERS}.marking. */
+    elevation?: number;
+    /** Longest draping step. Default 4. */
+    maxSegmentLength?: number;
+}
+/**
+ * Mesh the paint declared on streets passed to {@link buildTrimmedIntersections}. Longitudinal
+ * ribbons follow the trimmed road paths. At degree-2 nodes corresponding lines are joined by a
+ * tangent-continuous cubic (signed offsets are preserved); at multi-arm nodes lines deliberately
+ * stop short of the mouth and optional transverse stop lines make that termination readable.
+ * @capability world-intersections connect sidewalks and lane guidance through generated intersections
+ */
+export declare function buildIntersectionMarkings(intersections: TrimmedIntersections, sampleHeight: (x: number, z: number) => number, options?: IntersectionMarkingOptions): RoadRibbon[];