@jgengine/core 0.10.0 → 0.11.0

package/dist/world/pathTerrain.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Path-driven terrain modifiers: one authored centerline reshapes a heightfield across a corridor —
+ * flatten a roadbed, grade a constant-slope ramp, carve a river/trench, and hold retaining walls where
+ * the corridor cuts or fills into the surrounding ground. Genre-agnostic: roads, rails, rivers,
+ * trenches, runways, and accessibility ramps are all the same profile with different numbers, so no game
+ * hand-rolls its own flatten-mask generator. Pure XZ math over a polyline — deterministic, bounded
+ * (O(points) per sample), and serializable; it composes onto any height sampler and pairs with
+ * `resolveTerrainField` so the same authored path drives both the rendered mesh and player collision.
+ * @capability path-terrain flatten / grade / carve a heightfield from an authored path with retaining profiles
+ * @consumer packages/core/src/world/terrain.ts (resolveTerrainField), Games/the-robots roads
+ */
+import type { Vec2 } from "./geometry.js";
+/**
+ * Where a path corridor drives its centerline height:
+ * - `sample` — follow the base terrain under the centerline, so the corridor drapes level across its
+ *   width while still tracking the hills the path crosses (the natural policy for a road or trail).
+ * - `fixed` — hold one constant height for the whole corridor (a level causeway, runway, or dam crest).
+ * - `grade` — interpolate linearly from `start` to `end` height along the path's arc length, a
+ *   constant-slope ramp between two anchors (a switchback, a graded rail bed, an accessibility ramp).
+ */
+export type PathHeightPolicy = {
+    readonly kind: "sample";
+} | {
+    readonly kind: "fixed";
+    readonly height: number;
+} | {
+    readonly kind: "grade";
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * Retaining behavior for a path corridor's shoulders. A wall rises only where the corridor already cuts or
+ * fills into the surrounding ground by at least `threshold` — gentle stretches stay open — so a road
+ * through a canyon gets held banks while the same profile on flat ground does not. The wall fades in
+ * smoothly across `taper` above the threshold so it never steps on or off between adjacent samples.
+ */
+export interface PathRetaining {
+    /** Crest height raised above the corridor edge on both shoulders (canyon walls, road berms, levee banks). */
+    readonly wallHeight: number;
+    /** Minimum cut/fill (world units) between corridor and surrounding ground before a wall rises. Default 0 (wall the whole path). */
+    readonly threshold?: number;
+    /** Cut/fill band above `threshold` over which the wall fades from none to full height. Default equal to `threshold`. */
+    readonly taper?: number;
+}
+/**
+ * A serializable path-driven terrain modifier. The `points` centerline reshapes the heightfield across a
+ * corridor of `width`, feathering back to the surrounding ground across `shoulder`. `height` sets the
+ * centerline target (sample / fixed / grade); `depth` carves a channel below it (deepest at the
+ * centerline, easing to zero at the core edge — rivers and trenches); `retaining` raises walls where the
+ * cut/fill exceeds a threshold; `maxCut`/`maxFill` cap how far the ground may move from its base height.
+ * All fields are plain data (numbers, string enums, point arrays) so a profile round-trips through the
+ * scene document and evaluates identically at author time and runtime.
+ */
+export interface TerrainPathProfile {
+    /** Centerline vertices in world XZ; needs at least two points. Repeat the first point as the last for a closed loop. */
+    readonly points: readonly Vec2[];
+    /** Full corridor width; the reshaped core extends `width / 2` either side of the centerline. */
+    readonly width: number;
+    /** Blend-ring width outside the core where the corridor height smoothsteps back to the surrounding ground. Default `width * 0.5`. */
+    readonly shoulder?: number;
+    /** Centerline target-height policy. Default `{ kind: "sample" }` (drape level across the base terrain). */
+    readonly height?: PathHeightPolicy;
+    /** Carve depth below the target height, deepest at the centerline and easing to zero at the core edge (0 = flat corridor). Default 0. */
+    readonly depth?: number;
+    /** Never cut the ground more than this far below its base height. Omit for unlimited cut. */
+    readonly maxCut?: number;
+    /** Never fill the ground more than this far above its base height. Omit for unlimited fill. */
+    readonly maxFill?: number;
+    /** Raise retaining walls along the shoulders where the corridor cuts/fills into the surrounding ground. */
+    readonly retaining?: PathRetaining;
+}
+/**
+ * Wraps a height sampler so each authored `TerrainPathProfile` reshapes it. Profiles apply in list order
+ * (later profiles compose over earlier ones, so an intersection's last profile wins its core); each reads
+ * the running height as its surrounding ground and the original `base` for `sample` centerline heights.
+ * The returned sampler is pure and deterministic. Degenerate profiles (fewer than two points, non-positive
+ * width or length) are skipped; with no usable profile the original `base` is returned unchanged.
+ * @capability path-terrain compose flatten/grade/carve/retaining path profiles onto a height sampler
+ */
+export declare function withPathProfiles(base: (x: number, z: number) => number, profiles: readonly TerrainPathProfile[]): (x: number, z: number) => number;

package/dist/world/pathTerrain.js

@@ -0,0 +1,142 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function smoothstep01(t) {
+    const clamped = clamp01(t);
+    return clamped * clamped * (3 - 2 * clamped);
+}
+function buildCorridor(points) {
+    const cumulative = [0];
+    for (let i = 1; i < points.length; i += 1) {
+        const a = points[i - 1];
+        const b = points[i];
+        cumulative.push(cumulative[i - 1] + Math.hypot(b[0] - a[0], b[1] - a[1]));
+    }
+    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0 };
+}
+/**
+ * Closest point on the corridor to `(x, z)`: unsigned lateral distance and arc-length position. Self-
+ * contained (each segment projects independently and the minimum lateral wins) so a vertex always reports
+ * a near-zero lateral, regardless of which side of the line the neighbours fall.
+ */
+function nearestOnCorridor(corridor, x, z) {
+    let bestLateral = Number.POSITIVE_INFINITY;
+    let bestAlong = 0;
+    let bestPoint = corridor.points[0] ?? [x, z];
+    for (let i = 1; i < corridor.points.length; i += 1) {
+        const a = corridor.points[i - 1];
+        const b = corridor.points[i];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const segLenSq = abx * abx + abz * abz;
+        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / segLenSq));
+        const px = a[0] + abx * t;
+        const pz = a[1] + abz * t;
+        const lateral = Math.hypot(x - px, z - pz);
+        if (lateral < bestLateral) {
+            bestLateral = lateral;
+            bestAlong = corridor.cumulative[i - 1] + t * Math.sqrt(segLenSq);
+            bestPoint = [px, pz];
+        }
+    }
+    return { lateral: bestLateral, along: bestAlong, point: bestPoint };
+}
+function resolveProfile(profile) {
+    if (profile.points.length < 2 || profile.width <= 0)
+        return null;
+    const corridor = buildCorridor(profile.points.map((point) => [point[0], point[1]]));
+    if (corridor.total <= 0)
+        return null;
+    const shoulder = Math.max(0, profile.shoulder ?? profile.width * 0.5);
+    return {
+        corridor,
+        half: profile.width / 2,
+        shoulder,
+        reach: profile.width / 2 + shoulder,
+        height: profile.height ?? { kind: "sample" },
+        depth: Math.max(0, profile.depth ?? 0),
+        ...(profile.maxCut === undefined ? {} : { maxCut: Math.max(0, profile.maxCut) }),
+        ...(profile.maxFill === undefined ? {} : { maxFill: Math.max(0, profile.maxFill) }),
+        wallHeight: Math.max(0, profile.retaining?.wallHeight ?? 0),
+        threshold: Math.max(0, profile.retaining?.threshold ?? 0),
+        taper: Math.max(0, profile.retaining?.taper ?? profile.retaining?.threshold ?? 0),
+    };
+}
+/** Wall strength 0..1: full above `threshold + taper`, none below `threshold`, smooth between. */
+function wallStrength(profile, cutFill) {
+    if (profile.wallHeight <= 0)
+        return 0;
+    if (cutFill < profile.threshold)
+        return 0;
+    if (profile.taper <= 0)
+        return 1;
+    return smoothstep01((cutFill - profile.threshold) / profile.taper);
+}
+function clampCutFill(height, base, maxCut, maxFill) {
+    let out = height;
+    if (maxFill !== undefined && out > base + maxFill)
+        out = base + maxFill;
+    if (maxCut !== undefined && out < base - maxCut)
+        out = base - maxCut;
+    return out;
+}
+function centerlineTarget(profile, along, point, base) {
+    const policy = profile.height;
+    if (policy.kind === "fixed")
+        return policy.height;
+    if (policy.kind === "grade") {
+        const fraction = profile.corridor.total <= 0 ? 0 : clamp01(along / profile.corridor.total);
+        return policy.start + (policy.end - policy.start) * fraction;
+    }
+    return base(point[0], point[1]);
+}
+function applyProfileAt(profile, x, z, surrounding, base) {
+    const hit = nearestOnCorridor(profile.corridor, x, z);
+    const lateral = hit.lateral;
+    if (lateral > profile.reach)
+        return surrounding;
+    const target = clampCutFill(centerlineTarget(profile, hit.along, hit.point, base), surrounding, profile.maxCut, profile.maxFill);
+    // Inside the core: carve a channel below the target, deepest at the centerline, level at the edge.
+    if (lateral <= profile.half) {
+        const edgeT = profile.half <= 0 ? 0 : lateral / profile.half;
+        const carved = target - profile.depth * (1 - edgeT * edgeT);
+        return clampCutFill(carved, surrounding, profile.maxCut, profile.maxFill);
+    }
+    // Shoulder: feather the corridor edge (target) back to the surrounding ground, or hold a retaining wall.
+    const shoulderT = clamp01((lateral - profile.half) / profile.shoulder);
+    const feathered = lerp(target, surrounding, smoothstep01(shoulderT));
+    const strength = wallStrength(profile, Math.abs(target - surrounding));
+    if (strength <= 0)
+        return feathered;
+    const crest = target + profile.wallHeight;
+    const walled = shoulderT <= 0.5 ? lerp(target, crest, smoothstep01(shoulderT / 0.5)) : lerp(crest, surrounding, smoothstep01((shoulderT - 0.5) / 0.5));
+    return lerp(feathered, walled, strength);
+}
+/**
+ * Wraps a height sampler so each authored `TerrainPathProfile` reshapes it. Profiles apply in list order
+ * (later profiles compose over earlier ones, so an intersection's last profile wins its core); each reads
+ * the running height as its surrounding ground and the original `base` for `sample` centerline heights.
+ * The returned sampler is pure and deterministic. Degenerate profiles (fewer than two points, non-positive
+ * width or length) are skipped; with no usable profile the original `base` is returned unchanged.
+ * @capability path-terrain compose flatten/grade/carve/retaining path profiles onto a height sampler
+ */
+export function withPathProfiles(base, profiles) {
+    const resolved = [];
+    for (const profile of profiles) {
+        const prepared = resolveProfile(profile);
+        if (prepared !== null)
+            resolved.push(prepared);
+    }
+    if (resolved.length === 0)
+        return base;
+    return (x, z) => {
+        let height = base(x, z);
+        for (const profile of resolved) {
+            height = applyProfileAt(profile, x, z, height, base);
+        }
+        return height;
+    };
+}

package/dist/world/placeAsset.d.ts

@@ -0,0 +1,81 @@
+import { type AssetSpace } from "../scene/assetSpace.js";
+import type { PlacementCommit } from "./placementController.js";
+import type { AddStructureInput, StructureVec3 } from "./placedStructureStore.js";
+/** World-space point shared by structure stores and editor markers. */
+export type PlaceAssetVec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Shared place-asset verb: one resolved payload for editor `place_asset` and in-game
+ * build-mode commits. Convert with {@link toStructureInput} / {@link toEditorMarker}.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export interface PlaceAssetResult {
+    id: string;
+    assetId: string;
+    kind: string;
+    label: string;
+    position: PlaceAssetVec3;
+    rotationY: number;
+    color: string;
+    meta: Readonly<Record<string, unknown>>;
+}
+/** Inputs to {@link resolvePlaceAsset}: asset id, pose, and optional catalog/known fields. */
+export interface ResolvePlaceAssetInput {
+    assetId: string;
+    position: PlaceAssetVec3 | StructureVec3;
+    kind?: string;
+    label?: string;
+    rotationY?: number;
+    /**
+     * Placement heading in degrees (engine north = `0`, clockwise). When set it takes precedence over
+     * `rotationY`: the resolved `rotationY` runs through `space.rotation` (the asset's rotation policy)
+     * and `space.forwardDegrees` (canonical facing), so the catalog owns the correction instead of games.
+     */
+    headingDegrees?: number;
+    /** Asset-space metadata driving the heading resolution when `headingDegrees` is set. */
+    space?: AssetSpace;
+    id?: string;
+    color?: string;
+    meta?: Readonly<Record<string, unknown>>;
+    url?: string;
+    knownKind?: string;
+    knownLabel?: string;
+    knownUrl?: string;
+}
+/** Optional catalog/label overrides for {@link placeAssetFromCommit}. */
+export interface PlaceAssetFromCommitOptions {
+    kind?: string;
+    label?: string;
+    id?: string;
+    color?: string;
+    meta?: Readonly<Record<string, unknown>>;
+    url?: string;
+    knownKind?: string;
+    knownLabel?: string;
+    knownUrl?: string;
+}
+/**
+ * Resolve a place-asset intent into a shared payload (editor + games, one verb).
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export declare function resolvePlaceAsset(input: ResolvePlaceAssetInput): PlaceAssetResult;
+/**
+ * Bridge a {@link PlacementCommit} into the shared place-asset verb.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export declare function placeAssetFromCommit(commit: PlacementCommit, assetId: string, options?: PlaceAssetFromCommitOptions): PlaceAssetResult;
+/** Game-state form: feed {@link createPlacedStructureStore}.add. */
+export declare function toStructureInput(result: PlaceAssetResult): AddStructureInput;
+/** Scene-document form: feed editor `addMarker` / `place_asset` path. */
+export declare function toEditorMarker(result: PlaceAssetResult): {
+    id: string;
+    kind: string;
+    position: PlaceAssetVec3;
+    rotationY: number;
+    label: string;
+    color: string;
+    meta: Record<string, unknown>;
+};

package/dist/world/placeAsset.js

@@ -0,0 +1,77 @@
+import { applyRotationPolicy, resolveFacingRotationY } from "../scene/assetSpace.js";
+function normalizePosition(position) {
+    if (typeof position.x === "number") {
+        const p = position;
+        return { x: p.x, y: p.y, z: p.z };
+    }
+    const t = position;
+    return { x: t[0], y: t[1], z: t[2] };
+}
+function placementId(assetId, explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return `placed_${assetId}_${Date.now().toString(36)}`;
+}
+/**
+ * Resolve a place-asset intent into a shared payload (editor + games, one verb).
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export function resolvePlaceAsset(input) {
+    const position = normalizePosition(input.position);
+    const assetId = input.assetId;
+    const kind = input.kind ?? input.knownKind ?? "prop";
+    const label = input.label ?? input.knownLabel ?? assetId;
+    const url = input.url ?? input.knownUrl;
+    const meta = {
+        assetId,
+        ...(url === undefined ? {} : { url }),
+        ...(input.meta ?? {}),
+    };
+    const rotationY = input.headingDegrees === undefined
+        ? (input.rotationY ?? 0)
+        : resolveFacingRotationY(applyRotationPolicy(input.headingDegrees, input.space?.rotation), input.space);
+    return {
+        id: placementId(assetId, input.id),
+        assetId,
+        kind,
+        label,
+        position,
+        rotationY,
+        color: input.color ?? "#e2e8f0",
+        meta,
+    };
+}
+/**
+ * Bridge a {@link PlacementCommit} into the shared place-asset verb.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export function placeAssetFromCommit(commit, assetId, options = {}) {
+    return resolvePlaceAsset({
+        assetId,
+        position: [commit.center[0], commit.y, commit.center[1]],
+        rotationY: commit.rotationY,
+        ...options,
+    });
+}
+/** Game-state form: feed {@link createPlacedStructureStore}.add. */
+export function toStructureInput(result) {
+    return {
+        id: result.id,
+        catalogId: result.assetId,
+        position: [result.position.x, result.position.y, result.position.z],
+        rotationY: result.rotationY,
+        data: { ...result.meta, kind: result.kind, label: result.label, color: result.color },
+    };
+}
+/** Scene-document form: feed editor `addMarker` / `place_asset` path. */
+export function toEditorMarker(result) {
+    return {
+        id: result.id,
+        kind: result.kind,
+        position: result.position,
+        rotationY: result.rotationY,
+        label: result.label,
+        color: result.color,
+        meta: { ...result.meta },
+    };
+}

package/dist/world/placement.d.ts

@@ -26,5 +26,9 @@ export type PlacementResult = {
     obstacle: PlacementObstacle;
     index: number;
 };
+/**
+ * Footprint validity: bounds + obstacle overlap after optional grid snap.
+ * @capability placement-math grid/surface footprint validity for build mode
+ */
 export declare function validatePlacement(request: PlacementRequest, rules?: PlacementRules): PlacementResult;
 export declare function footprintObstacle(request: PlacementRequest, id?: string): PlacementObstacle;

package/dist/world/placement.js

@@ -1,4 +1,8 @@
 import { aabbContains, aabbOverlap, footprintAabb, snapToGrid, } from "./geometry.js";
+/**
+ * Footprint validity: bounds + obstacle overlap after optional grid snap.
+ * @capability placement-math grid/surface footprint validity for build mode
+ */
 export function validatePlacement(request, rules = {}) {
     const center = rules.snap === undefined ? request.center : snapToGrid(request.center, rules.snap);
     const aabb = footprintAabb(center, request.footprint, request.quarterTurns ?? 0);

package/dist/world/placementController.d.ts

@@ -65,5 +65,11 @@ export interface PlacementController {
     commit(): PlacementCommit | null;
     reset(): void;
 }
+/** Maps 0–3 quarter turns onto radians for ghost/commit rotation. */
 export declare function quarterTurnsToRotationY(quarterTurns: number): number;
+/**
+ * Headless placement ghost: hover → valid/invalid preview, rotate, grid/free/surface snap, commit.
+ * Pair with `@jgengine/shell/structures` `PlacementGhost` and {@link placeAssetFromCommit}.
+ * @capability placement-controller interactive build-mode ghost preview and commit
+ */
 export declare function createPlacementController(config: PlacementControllerConfig): PlacementController;

package/dist/world/placementController.js

@@ -5,10 +5,16 @@ const DEFAULT_SLOT_RADIUS = 1.5;
 function distanceVec3(a, b) {
     return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }
+/** Maps 0–3 quarter turns onto radians for ghost/commit rotation. */
 export function quarterTurnsToRotationY(quarterTurns) {
     const turns = ((quarterTurns % 4) + 4) % 4;
     return turns === 0 ? 0 : -turns * (Math.PI / 2);
 }
+/**
+ * Headless placement ghost: hover → valid/invalid preview, rotate, grid/free/surface snap, commit.
+ * Pair with `@jgengine/shell/structures` `PlacementGhost` and {@link placeAssetFromCommit}.
+ * @capability placement-controller interactive build-mode ghost preview and commit
+ */
 export function createPlacementController(config) {
     let footprint = config.footprint;
     let rules = config.rules ?? {};

package/dist/world/polyline.d.ts

@@ -0,0 +1,34 @@
+import type { Vec2 } from "./geometry.js";
+/** A polyline prepared for repeated distance/fraction sampling, with cumulative arc-length precomputed. */
+export interface Polyline {
+    readonly points: readonly Vec2[];
+    readonly cumulative: readonly number[];
+    readonly length: number;
+}
+/** The closest point on a polyline to a query point, with where it lands along the line. */
+export interface PolylineHit {
+    readonly point: Vec2;
+    readonly distanceAlong: number;
+    readonly segment: number;
+    readonly lateral: number;
+}
+/** Prepare a polyline from ordered points, computing cumulative arc-length once for O(log n) sampling.
+ * @internal
+ */
+export declare function polyline(points: readonly Vec2[]): Polyline;
+/** Point at an absolute arc-length distance along the line, clamped to the endpoints.
+ * @internal
+ */
+export declare function pointAtDistance(line: Polyline, dist: number): Vec2;
+/** Point at a `[0, 1]` fraction of the line's total length.
+ * @internal
+ */
+export declare function pointAtFraction(line: Polyline, fraction: number): Vec2;
+/** Unit tangent (direction of travel) at an absolute distance along the line.
+ * @internal
+ */
+export declare function tangentAtDistance(line: Polyline, dist: number): Vec2;
+/** Closest point on the line to `query`, reporting arc-length position, segment index, and signed lateral offset.
+ * @internal
+ */
+export declare function closestPoint(line: Polyline, query: Vec2): PolylineHit;

package/dist/world/polyline.js

@@ -0,0 +1,81 @@
+import { distance, lerp, normalize, perp, sub } from "./vec2.js";
+/** Prepare a polyline from ordered points, computing cumulative arc-length once for O(log n) sampling.
+ * @internal
+ */
+export function polyline(points) {
+    const cumulative = [0];
+    for (let i = 1; i < points.length; i += 1) {
+        cumulative.push(cumulative[i - 1] + distance(points[i - 1], points[i]));
+    }
+    return { points, cumulative, length: cumulative[cumulative.length - 1] ?? 0 };
+}
+function segmentAt(line, dist) {
+    const { cumulative } = line;
+    const clamped = dist < 0 ? 0 : dist > line.length ? line.length : dist;
+    let lo = 1;
+    let hi = cumulative.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cumulative[mid] < clamped)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const start = cumulative[lo - 1];
+    const span = cumulative[lo] - start;
+    return { index: lo, t: span <= 0 ? 0 : (clamped - start) / span };
+}
+/** Point at an absolute arc-length distance along the line, clamped to the endpoints.
+ * @internal
+ */
+export function pointAtDistance(line, dist) {
+    if (line.points.length === 0)
+        return [0, 0];
+    if (line.points.length === 1)
+        return line.points[0];
+    const { index, t } = segmentAt(line, dist);
+    return lerp(line.points[index - 1], line.points[index], t);
+}
+/** Point at a `[0, 1]` fraction of the line's total length.
+ * @internal
+ */
+export function pointAtFraction(line, fraction) {
+    return pointAtDistance(line, fraction * line.length);
+}
+/** Unit tangent (direction of travel) at an absolute distance along the line.
+ * @internal
+ */
+export function tangentAtDistance(line, dist) {
+    if (line.points.length < 2)
+        return [0, 1];
+    const { index } = segmentAt(line, dist);
+    return normalize(sub(line.points[index], line.points[index - 1]));
+}
+/** Closest point on the line to `query`, reporting arc-length position, segment index, and signed lateral offset.
+ * @internal
+ */
+export function closestPoint(line, query) {
+    const { points, cumulative } = line;
+    if (points.length === 0)
+        return { point: [0, 0], distanceAlong: 0, segment: 0, lateral: 0 };
+    if (points.length === 1) {
+        return { point: points[0], distanceAlong: 0, segment: 0, lateral: distance(points[0], query) };
+    }
+    let best = { point: points[0], distanceAlong: 0, segment: 0, lateral: Infinity };
+    for (let i = 1; i < points.length; i += 1) {
+        const a = points[i - 1];
+        const b = points[i];
+        const abx = b[0] - a[0];
+        const aby = b[1] - a[1];
+        const segLenSq = abx * abx + aby * aby;
+        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((query[0] - a[0]) * abx + (query[1] - a[1]) * aby) / segLenSq));
+        const point = [a[0] + abx * t, a[1] + aby * t];
+        const lateral = distance(point, query);
+        if (lateral < best.lateral) {
+            const along = cumulative[i - 1] + t * Math.sqrt(segLenSq);
+            const side = Math.sign(perp(normalize([abx, aby]))[0] * (query[0] - point[0]) + perp(normalize([abx, aby]))[1] * (query[1] - point[1]));
+            best = { point, distanceAlong: along, segment: i - 1, lateral: lateral * (side === 0 ? 1 : side) };
+        }
+    }
+    return best;
+}

package/dist/world/roads.d.ts

@@ -7,6 +7,14 @@ export interface RoadRibbon {
     /** Triangle indices into `positions`. */
     indices: Uint32Array;
 }
+/**
+ * Fillets sharp corners of a centerline into short arcs so a ribbon built from it reads as a smooth
+ * road instead of overlapping/notching rectangles at each bend. Each interior vertex is replaced by a
+ * quadratic-bezier arc of `radius` (clamped to half the shorter adjacent segment) sampled at
+ * `cornerSegments` steps; endpoints and near-straight vertices pass through unchanged.
+ * @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[];
 /** Options for {@link buildRoadRibbon}. */
 export interface RoadRibbonOptions {
     /** Lift above the sampled ground so the ribbon never z-fights the terrain. Default 0.08. */

package/dist/world/roads.js

@@ -1,3 +1,41 @@
+/**
+ * Fillets sharp corners of a centerline into short arcs so a ribbon built from it reads as a smooth
+ * road instead of overlapping/notching rectangles at each bend. Each interior vertex is replaced by a
+ * quadratic-bezier arc of `radius` (clamped to half the shorter adjacent segment) sampled at
+ * `cornerSegments` steps; endpoints and near-straight vertices pass through unchanged.
+ * @internal — the corner-smoothing behind `<AuthoredPaths>`; games get it for free through the render.
+ */
+export function roundPathCorners(points, radius, cornerSegments = 5) {
+    if (points.length < 3 || radius <= 0)
+        return points.map((point) => [point[0], point[1]]);
+    const out = [[points[0][0], points[0][1]]];
+    for (let i = 1; i < points.length - 1; i += 1) {
+        const a = points[i - 1];
+        const v = points[i];
+        const b = points[i + 1];
+        const ax = a[0] - v[0];
+        const az = a[1] - v[1];
+        const bx = b[0] - v[0];
+        const bz = b[1] - v[1];
+        const la = Math.hypot(ax, az) || 1;
+        const lb = Math.hypot(bx, bz) || 1;
+        const r = Math.min(radius, la / 2, lb / 2);
+        const p0 = [v[0] + (ax / la) * r, v[1] + (az / la) * r];
+        const p1 = [v[0] + (bx / lb) * r, v[1] + (bz / lb) * r];
+        out.push(p0);
+        for (let s = 1; s < cornerSegments; s += 1) {
+            const t = s / cornerSegments;
+            const u = 1 - t;
+            out.push([
+                u * u * p0[0] + 2 * u * t * v[0] + t * t * p1[0],
+                u * u * p0[1] + 2 * u * t * v[1] + t * t * p1[1],
+            ]);
+        }
+        out.push(p1);
+    }
+    out.push([points[points.length - 1][0], points[points.length - 1][1]]);
+    return out;
+}
 function subdividePath(path, maxLength) {
     const out = [];
     for (let i = 0; i < path.length - 1; i += 1) {