@jgengine/core 0.9.0 → 0.11.0

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

@@ -0,0 +1,55 @@
+/** A road centerline vertex in world XZ. */
+export type RoadPoint = readonly [number, number];
+/** Renderer-ready triangle ribbon: flat position triples plus triangle indices. */
+export interface RoadRibbon {
+    /** Interleaved xyz vertex positions. */
+    positions: Float32Array;
+    /** 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. */
+    elevation?: number;
+    /** Longest centerline step before the polyline is subdivided to drape over relief. Default 4. */
+    maxSegmentLength?: number;
+}
+/**
+ * Triangulate a road centerline into a ground-draped ribbon mesh: the polyline is subdivided,
+ * each vertex is offset half a `width` along the local perpendicular, and every vertex sits at
+ * `sampleHeight(x, z) + elevation`. Pure geometry — the shell (or any renderer) turns the result
+ * into a mesh, and tests can assert on it directly.
+ */
+export declare function buildRoadRibbon(path: readonly RoadPoint[], width: number, sampleHeight: (x: number, z: number) => number, options?: RoadRibbonOptions): RoadRibbon;
+/**
+ * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
+ * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ */
+export declare function dashSegments(path: readonly RoadPoint[], dashLength?: number, gapLength?: number): readonly (readonly RoadPoint[])[];
+/** Result of {@link nearestOnPath}: closest point on the centerline plus distance and tangent. */
+export interface RoadSample {
+    /** Closest point on the centerline. */
+    point: RoadPoint;
+    /** World distance from the query to `point`. */
+    distance: number;
+    /** Unit tangent of the centerline at `point`. */
+    tangent: readonly [number, number];
+}
+/**
+ * Closest-point query against a road centerline — the seam traffic AI, spawn placement, and
+ * "am I on the road" checks share. Returns null for a degenerate path.
+ */
+export declare function nearestOnPath(path: readonly RoadPoint[], x: number, z: number): RoadSample | null;
+/** True when the query point lies within half the road `width` of the centerline. */
+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;