@jgengine/core 0.9.0 → 0.11.0

package/dist/world/footprintGrid.js

@@ -0,0 +1,141 @@
+function cellKey(cell) {
+    return `${cell.col}:${cell.row}`;
+}
+/**
+ * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
+ * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
+ * hover's `isFree` check (or another player's, in a shared world) sees it. Bridge into
+ * `world/placement`'s `PlacementRules.obstacles` with {@link footprintObstacles} instead of
+ * hand-rolling an occupancy map per game.
+ *
+ * @capability footprint-grid multi-cell footprint occupancy/reservation on a shared build grid
+ */
+export function createFootprintGrid(options = {}) {
+    const cellSize = options.cellSize ?? 1;
+    const occupied = new Map();
+    const reservations = new Map();
+    return {
+        cellSize,
+        cellsFor(origin, footprint, quarterTurns = 0) {
+            const turned = ((quarterTurns % 2) + 2) % 2 === 1;
+            const cols = Math.max(1, Math.round((turned ? footprint.d : footprint.w) / cellSize));
+            const rows = Math.max(1, Math.round((turned ? footprint.w : footprint.d) / cellSize));
+            const originCol = Math.round(origin[0] / cellSize - cols / 2);
+            const originRow = Math.round(origin[1] / cellSize - rows / 2);
+            const cells = [];
+            for (let row = 0; row < rows; row += 1) {
+                for (let col = 0; col < cols; col += 1)
+                    cells.push({ col: originCol + col, row: originRow + row });
+            }
+            return cells;
+        },
+        isFree(cells) {
+            return cells.every((cell) => !occupied.has(cellKey(cell)));
+        },
+        reserve(id, kind, cells) {
+            if (reservations.has(id))
+                return false;
+            if (!cells.every((cell) => !occupied.has(cellKey(cell))))
+                return false;
+            for (const cell of cells)
+                occupied.set(cellKey(cell), id);
+            reservations.set(id, { id, kind, cells: cells.slice() });
+            return true;
+        },
+        release(id) {
+            const reservation = reservations.get(id);
+            if (reservation === undefined)
+                return false;
+            for (const cell of reservation.cells)
+                occupied.delete(cellKey(cell));
+            reservations.delete(id);
+            return true;
+        },
+        occupantAt(cell) {
+            return occupied.get(cellKey(cell)) ?? null;
+        },
+        kindAt(cell) {
+            const id = occupied.get(cellKey(cell));
+            if (id === undefined)
+                return null;
+            return reservations.get(id)?.kind ?? null;
+        },
+        reservationOf(id) {
+            return reservations.get(id) ?? null;
+        },
+        list() {
+            return Array.from(reservations.values());
+        },
+        clear() {
+            occupied.clear();
+            reservations.clear();
+        },
+    };
+}
+const CARDINAL_OFFSETS = [
+    { col: 0, row: -1 },
+    { col: 1, row: 0 },
+    { col: 0, row: 1 },
+    { col: -1, row: 0 },
+];
+/** Every occupied cell orthogonally touching `cells` but outside them — the connective-piece neighbor set. */
+export function boundaryNeighbors(grid, cells) {
+    const own = new Set(cells.map(cellKey));
+    const seen = new Set();
+    const out = [];
+    for (const cell of cells) {
+        for (const offset of CARDINAL_OFFSETS) {
+            const neighbor = { col: cell.col + offset.col, row: cell.row + offset.row };
+            const key = cellKey(neighbor);
+            if (own.has(key) || seen.has(key))
+                continue;
+            seen.add(key);
+            const kind = grid.kindAt(neighbor);
+            if (kind !== null)
+                out.push({ cell: neighbor, kind });
+        }
+    }
+    return out;
+}
+/**
+ * Connective-piece adjacency validity: every occupied neighbor of `cells` must satisfy `accepts`
+ * (no incompatible piece touching), and when `requireConnection` is true at least one neighbor must
+ * (a road/pipe/belt segment placed with nothing to connect to is invalid). An empty-bordered footprint
+ * (no occupied neighbors at all) passes unless `requireConnection` demands one.
+ */
+export function hasValidAdjacency(grid, cells, accepts, requireConnection = false) {
+    const neighbors = boundaryNeighbors(grid, cells);
+    if (requireConnection && neighbors.length === 0)
+        return false;
+    if (!neighbors.every((neighbor) => accepts(neighbor.kind)))
+        return false;
+    return !requireConnection || neighbors.some((neighbor) => accepts(neighbor.kind));
+}
+/** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
+export function footprintObstacles(grid) {
+    return grid.list().map((reservation) => {
+        let minCol = Infinity;
+        let minRow = Infinity;
+        let maxCol = -Infinity;
+        let maxRow = -Infinity;
+        for (const cell of reservation.cells) {
+            if (cell.col < minCol)
+                minCol = cell.col;
+            if (cell.col > maxCol)
+                maxCol = cell.col;
+            if (cell.row < minRow)
+                minRow = cell.row;
+            if (cell.row > maxRow)
+                maxRow = cell.row;
+        }
+        return {
+            id: reservation.id,
+            aabb: {
+                minX: minCol * grid.cellSize,
+                maxX: (maxCol + 1) * grid.cellSize,
+                minZ: minRow * grid.cellSize,
+                maxZ: (maxRow + 1) * grid.cellSize,
+            },
+        };
+    });
+}

package/dist/world/geometry.d.ts

@@ -1,4 +1,6 @@
 export type Vec2 = readonly [number, number];
+/** A 3D point/vector as an `[x, y, z]` tuple — the engine's zero-allocation spatial primitive. */
+export type Vec3 = readonly [number, number, number];
 export interface Footprint {
     w: number;
     d: number;
@@ -13,11 +15,73 @@ export interface MoveOptions {
     bounds?: Aabb;
     radius?: number;
 }
+/**
+ * A circular clearance around a gameplay spot (spawn, plot, path point, POI): scatter is repelled
+ * from it and terrain is flattened toward its center. `feather` (meters) is the soft outer band —
+ * full effect within `radius - feather`, ramping to zero at `radius`.
+ */
+export interface AvoidZone {
+    x: number;
+    z: number;
+    radius: number;
+    feather?: number;
+}
+/**
+ * A clearance *corridor* along a polyline (a path/road): scatter is repelled within `halfWidth` of
+ * the centerline, feathered over the outer band. Clean straight edges — unlike approximating a
+ * corridor with a scalloped chain of discs.
+ */
+export interface AvoidCorridor {
+    points: readonly Vec2[];
+    halfWidth: number;
+    feather?: number;
+}
+/** A clearance region: point discs (spawns/plots) plus centerline corridors (paths). */
+export interface AvoidMasks {
+    discs: readonly AvoidZone[];
+    corridors: readonly AvoidCorridor[];
+}
+/**
+ * How strongly a point falls inside a clearance zone: 1 at/inside the solid core, ramping to 0 at
+ * the zone's outer `radius` across its `feather` band, 0 outside. The max over all zones.
+ * @internal — the falloff math behind scatter avoid and terrain flatten.
+ */
+export declare function zoneInfluence(x: number, z: number, zones: readonly AvoidZone[]): number;
+/** Clearance influence of a corridor: nearest-segment distance vs `halfWidth`, feathered. @internal */
+export declare function corridorInfluence(x: number, z: number, corridor: AvoidCorridor): number;
+/** Combined clearance influence of discs + corridors — the max over every mask. @internal */
+export declare function masksInfluence(x: number, z: number, masks: AvoidMasks): number;
+/** @internal */
 export declare function snapToGrid(point: Vec2, size: number): Vec2;
+/** @internal */
 export declare function footprintAabb(center: Vec2, footprint: Footprint, quarterTurns?: number): Aabb;
+/** @internal */
 export declare function expandAabb(aabb: Aabb, margin: number): Aabb;
+/** @internal */
 export declare function aabbOverlap(a: Aabb, b: Aabb): boolean;
+/** @internal */
 export declare function aabbContains(outer: Aabb, inner: Aabb): boolean;
+/** @internal */
 export declare function pointInAabb(point: Vec2, aabb: Aabb): boolean;
+/** @internal */
 export declare function clampToAabb(point: Vec2, aabb: Aabb): Vec2;
+/** @internal */
 export declare function resolveMove(from: Vec2, delta: Vec2, blockers: readonly Aabb[], options?: MoveOptions): Vec2;
+/** An axis-aligned ellipse: `center` with semi-axes `radiusX` and `radiusY`. */
+export interface Ellipse {
+    center: Vec2;
+    radiusX: number;
+    radiusY: number;
+}
+/** True when `point` sits inside (or on) the ellipse — the oval-arena containment test.
+ * @internal
+ */
+export declare function pointInEllipse(point: Vec2, ellipse: Ellipse): boolean;
+/** Clamp `point` to the ellipse boundary when it strays outside, else return it unchanged.
+ * @internal
+ */
+export declare function clampToEllipse(point: Vec2, ellipse: Ellipse): Vec2;
+/** Outward unit normal of the ellipse at the point nearest `point` — the boundary bounce direction.
+ * @internal
+ */
+export declare function ellipseNormal(point: Vec2, ellipse: Ellipse): Vec2;

package/dist/world/geometry.js

@@ -1,8 +1,61 @@
+function bandInfluence(dist, radius, feather) {
+    if (dist >= radius)
+        return 0;
+    const inner = radius - Math.max(0, feather);
+    return dist <= inner || feather <= 0 ? 1 : (radius - dist) / feather;
+}
+/** Perpendicular distance from a point to a polyline segment [a,b] on the XZ plane. */
+function distanceToSegment(px, pz, a, b) {
+    const dx = b[0] - a[0];
+    const dz = b[1] - a[1];
+    const lenSq = dx * dx + dz * dz || 1;
+    let t = ((px - a[0]) * dx + (pz - a[1]) * dz) / lenSq;
+    t = t < 0 ? 0 : t > 1 ? 1 : t;
+    return Math.hypot(px - (a[0] + dx * t), pz - (a[1] + dz * t));
+}
+/**
+ * How strongly a point falls inside a clearance zone: 1 at/inside the solid core, ramping to 0 at
+ * the zone's outer `radius` across its `feather` band, 0 outside. The max over all zones.
+ * @internal — the falloff math behind scatter avoid and terrain flatten.
+ */
+export function zoneInfluence(x, z, zones) {
+    let best = 0;
+    for (const zone of zones) {
+        const t = bandInfluence(Math.hypot(x - zone.x, z - zone.z), zone.radius, zone.feather ?? 0);
+        if (t > best)
+            best = t;
+    }
+    return best;
+}
+/** Clearance influence of a corridor: nearest-segment distance vs `halfWidth`, feathered. @internal */
+export function corridorInfluence(x, z, corridor) {
+    const { points, halfWidth } = corridor;
+    const feather = corridor.feather ?? 0;
+    let best = 0;
+    for (let i = 1; i < points.length; i += 1) {
+        const t = bandInfluence(distanceToSegment(x, z, points[i - 1], points[i]), halfWidth, feather);
+        if (t > best)
+            best = t;
+    }
+    return best;
+}
+/** Combined clearance influence of discs + corridors — the max over every mask. @internal */
+export function masksInfluence(x, z, masks) {
+    let best = zoneInfluence(x, z, masks.discs);
+    for (const corridor of masks.corridors) {
+        const t = corridorInfluence(x, z, corridor);
+        if (t > best)
+            best = t;
+    }
+    return best;
+}
+/** @internal */
 export function snapToGrid(point, size) {
     if (!(size > 0))
         return point;
     return [Math.round(point[0] / size) * size, Math.round(point[1] / size) * size];
 }
+/** @internal */
 export function footprintAabb(center, footprint, quarterTurns = 0) {
     const turned = ((quarterTurns % 2) + 2) % 2 === 1;
     const halfW = (turned ? footprint.d : footprint.w) / 2;
@@ -14,6 +67,7 @@ export function footprintAabb(center, footprint, quarterTurns = 0) {
         maxZ: center[1] + halfD,
     };
 }
+/** @internal */
 export function expandAabb(aabb, margin) {
     return {
         minX: aabb.minX - margin,
@@ -22,18 +76,22 @@ export function expandAabb(aabb, margin) {
         maxZ: aabb.maxZ + margin,
     };
 }
+/** @internal */
 export function aabbOverlap(a, b) {
     return a.minX < b.maxX && a.maxX > b.minX && a.minZ < b.maxZ && a.maxZ > b.minZ;
 }
+/** @internal */
 export function aabbContains(outer, inner) {
     return (inner.minX >= outer.minX &&
         inner.maxX <= outer.maxX &&
         inner.minZ >= outer.minZ &&
         inner.maxZ <= outer.maxZ);
 }
+/** @internal */
 export function pointInAabb(point, aabb) {
     return point[0] >= aabb.minX && point[0] <= aabb.maxX && point[1] >= aabb.minZ && point[1] <= aabb.maxZ;
 }
+/** @internal */
 export function clampToAabb(point, aabb) {
     return [
         Math.min(Math.max(point[0], aabb.minX), aabb.maxX),
@@ -62,6 +120,7 @@ function resolveAxis(main, cross, delta, blockers, axisX) {
     }
     return next;
 }
+/** @internal */
 export function resolveMove(from, delta, blockers, options = {}) {
     const radius = options.radius ?? 0;
     const expanded = radius === 0 ? blockers : blockers.map((blocker) => expandAabb(blocker, radius));
@@ -73,3 +132,38 @@ export function resolveMove(from, delta, blockers, options = {}) {
         z = Math.min(Math.max(z, options.bounds.minZ + radius), options.bounds.maxZ - radius);
     return [x, z];
 }
+function normalizedRadius2(point, ellipse) {
+    const nx = ellipse.radiusX > 0 ? (point[0] - ellipse.center[0]) / ellipse.radiusX : 0;
+    const ny = ellipse.radiusY > 0 ? (point[1] - ellipse.center[1]) / ellipse.radiusY : 0;
+    return nx * nx + ny * ny;
+}
+/** True when `point` sits inside (or on) the ellipse — the oval-arena containment test.
+ * @internal
+ */
+export function pointInEllipse(point, ellipse) {
+    return normalizedRadius2(point, ellipse) <= 1;
+}
+/** Clamp `point` to the ellipse boundary when it strays outside, else return it unchanged.
+ * @internal
+ */
+export function clampToEllipse(point, ellipse) {
+    const r2 = normalizedRadius2(point, ellipse);
+    if (r2 <= 1)
+        return point;
+    const scale = 1 / Math.sqrt(r2);
+    return [
+        ellipse.center[0] + (point[0] - ellipse.center[0]) * scale,
+        ellipse.center[1] + (point[1] - ellipse.center[1]) * scale,
+    ];
+}
+/** Outward unit normal of the ellipse at the point nearest `point` — the boundary bounce direction.
+ * @internal
+ */
+export function ellipseNormal(point, ellipse) {
+    const nx = ellipse.radiusX > 0 ? (point[0] - ellipse.center[0]) / (ellipse.radiusX * ellipse.radiusX) : 0;
+    const ny = ellipse.radiusY > 0 ? (point[1] - ellipse.center[1]) / (ellipse.radiusY * ellipse.radiusY) : 0;
+    const len = Math.hypot(nx, ny);
+    if (len < 1e-6)
+        return [1, 0];
+    return [nx / len, ny / len];
+}

package/dist/world/grassKind.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `grass_field` studio: a GPU grass patch authored as a box volume — its XZ footprint is the grass
+ * area, its top the ground height. Pure config here (blade/wind/color params + a footprint resolver);
+ * the instanced vertex-wind grass mesh lives in the `shell` renderer, which drives the existing
+ * `GrassField`. An engine environment kind (like water/scatter) so grass wind and colours are
+ * slider-authorable in the editor and persisted in `editor.scene.json` — the #813 grass studio.
+ *
+ * @capability grass-field editor-authorable GPU grass patch
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/** The editor volume kind marking a box as a GPU grass patch. */
+export declare const GRASS_FIELD_KIND = "grass_field";
+/** Fully-defaulted grass params parsed from a volume's `meta`. */
+export interface GrassRules {
+    /** Blades per square meter (the shell caps by an instance budget). */
+    density: number;
+    /** Blade height in meters. */
+    bladeHeight: number;
+    /** Base (root) color, hex. */
+    colorBase: string;
+    /** Tip color, hex. */
+    colorTip: string;
+    /** Per-blade color jitter, 0..1. */
+    colorVariation: number;
+    /** Vertex-wind sway strength, 0..1. */
+    windStrength: number;
+    /** Wind animation speed. */
+    windSpeed: number;
+    /** Gust patch scale (spatial frequency of gusts). */
+    windGust: number;
+    /** Blade material roughness, 0..1. */
+    roughness: number;
+    /** Seed string; same seed reproduces the same blade layout. */
+    seed: string;
+}
+/** Grass defaults: a lush, lightly-swaying meadow. */
+export declare const GRASS_DEFAULTS: GrassRules;
+/** The grass parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const GRASS_SCHEMA: ParamSchema;
+/** Parse a volume's `meta` into fully-defaulted grass rules. @internal */
+export declare function readGrassRules(meta: Record<string, unknown> | undefined): GrassRules;
+/** A resolved grass patch: world-space area center at ground height, footprint size (XZ), and rules. */
+export interface ResolvedGrass {
+    center: readonly [number, number, number];
+    size: readonly [number, number];
+    rules: GrassRules;
+}
+/** Resolve a grass volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export declare function resolveGrassObject(object: SceneKindObject): ResolvedGrass | null;
+/** Registers the `grass_field` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerGrassKind(): void;

package/dist/world/grassKind.js

@@ -0,0 +1,101 @@
+/**
+ * `grass_field` studio: a GPU grass patch authored as a box volume — its XZ footprint is the grass
+ * area, its top the ground height. Pure config here (blade/wind/color params + a footprint resolver);
+ * the instanced vertex-wind grass mesh lives in the `shell` renderer, which drives the existing
+ * `GrassField`. An engine environment kind (like water/scatter) so grass wind and colours are
+ * slider-authorable in the editor and persisted in `editor.scene.json` — the #813 grass studio.
+ *
+ * @capability grass-field editor-authorable GPU grass patch
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/** The editor volume kind marking a box as a GPU grass patch. */
+export const GRASS_FIELD_KIND = "grass_field";
+/** Grass defaults: a lush, lightly-swaying meadow. */
+export const GRASS_DEFAULTS = {
+    density: 4,
+    bladeHeight: 0.6,
+    colorBase: "#3f6f37",
+    colorTip: "#9ac25a",
+    colorVariation: 0.35,
+    windStrength: 0.22,
+    windSpeed: 1.6,
+    windGust: 0.16,
+    roughness: 0.85,
+    seed: "",
+};
+/** The grass parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const GRASS_SCHEMA = {
+    fields: [
+        { type: "range", key: "density", label: "density", min: 0.5, max: 16, step: 0.5, default: GRASS_DEFAULTS.density, unit: "/m²" },
+        { type: "range", key: "bladeHeight", label: "blade height", min: 0.1, max: 2, step: 0.05, default: GRASS_DEFAULTS.bladeHeight, unit: "m" },
+        { type: "color", key: "colorBase", label: "base color", default: GRASS_DEFAULTS.colorBase },
+        { type: "color", key: "colorTip", label: "tip color", default: GRASS_DEFAULTS.colorTip },
+        { type: "range", key: "colorVariation", label: "color variation", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.colorVariation },
+        { type: "range", key: "windStrength", label: "wind strength", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.windStrength },
+        { type: "range", key: "windSpeed", label: "wind speed", min: 0, max: 4, step: 0.05, default: GRASS_DEFAULTS.windSpeed },
+        { type: "range", key: "windGust", label: "gust scale", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.windGust },
+        { type: "range", key: "roughness", label: "roughness", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.roughness },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+function metaNumber(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function metaString(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+/** Parse a volume's `meta` into fully-defaulted grass rules. @internal */
+export function readGrassRules(meta) {
+    return {
+        density: Math.max(0, metaNumber(meta, "density", GRASS_DEFAULTS.density)),
+        bladeHeight: Math.max(0.05, metaNumber(meta, "bladeHeight", GRASS_DEFAULTS.bladeHeight)),
+        colorBase: metaString(meta, "colorBase", GRASS_DEFAULTS.colorBase),
+        colorTip: metaString(meta, "colorTip", GRASS_DEFAULTS.colorTip),
+        colorVariation: metaNumber(meta, "colorVariation", GRASS_DEFAULTS.colorVariation),
+        windStrength: metaNumber(meta, "windStrength", GRASS_DEFAULTS.windStrength),
+        windSpeed: metaNumber(meta, "windSpeed", GRASS_DEFAULTS.windSpeed),
+        windGust: metaNumber(meta, "windGust", GRASS_DEFAULTS.windGust),
+        roughness: metaNumber(meta, "roughness", GRASS_DEFAULTS.roughness),
+        seed: metaString(meta, "seed", GRASS_DEFAULTS.seed),
+    };
+}
+function axis(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Resolve a grass volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export function resolveGrassObject(object) {
+    const center = object.center ?? object.position;
+    if (center === undefined)
+        return null;
+    const he = object.halfExtents;
+    const radius = object.radius;
+    const halfX = axis(he?.x) ?? radius ?? 10;
+    const halfZ = axis(he?.z) ?? radius ?? 10;
+    const halfY = axis(he?.y) ?? 0;
+    return {
+        center: [center.x, center.y - halfY, center.z],
+        size: [Math.max(0.5, halfX * 2), Math.max(0.5, halfZ * 2)],
+        rules: readGrassRules(object.meta),
+    };
+}
+/** Registers the `grass_field` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerGrassKind() {
+    registerSceneKind({
+        kind: GRASS_FIELD_KIND,
+        target: "volume",
+        label: "Grass field",
+        addCategory: "Studios",
+        accent: "#7fbf4d",
+        schema: GRASS_SCHEMA,
+        resolve: (object) => resolveGrassObject(object),
+        note: (object) => {
+            const resolved = resolveGrassObject(object);
+            if (resolved === null)
+                return "Give the volume a box footprint.";
+            const area = resolved.size[0] * resolved.size[1];
+            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈${Math.round(area * resolved.rules.density).toLocaleString()} blades`;
+        },
+    });
+}

package/dist/world/pathInstances.d.ts

@@ -0,0 +1,27 @@
+/** One placed transform along a path: grounded position, facing yaw, and its ordinal + arc distance. */
+export interface PathInstance {
+    index: number;
+    /** Arc-length distance from the path start, meters. */
+    distance: number;
+    position: readonly [number, number, number];
+    /** Yaw (radians) facing along the direction of travel. */
+    yaw: number;
+}
+/** Options for {@link placeAlongPath}. */
+export interface PlaceAlongPathOptions {
+    /** Target meters between instances. The run is divided into equal spans nearest this spacing. */
+    spacing: number;
+    /** Ground each instance to this height sampler (else y = 0). */
+    sampleHeight?: (x: number, z: number) => number;
+    /** Force at least this many instances regardless of length. Default 1 (endpoints only when short). */
+    minCount?: number;
+}
+/**
+ * Evenly place transforms along `points` (XZ polyline). The run length is divided into the whole
+ * number of equal spans closest to `spacing`, so instances always land on both endpoints and stay
+ * evenly distributed. Returns `spans + 1` instances. Empty for fewer than 2 points.
+ */
+export declare function placeAlongPath(points: readonly {
+    x: number;
+    z: number;
+}[], options: PlaceAlongPathOptions): PathInstance[];

package/dist/world/pathInstances.js

@@ -0,0 +1,27 @@
+import { pointAtDistance, polyline, tangentAtDistance } from "./polyline.js";
+/**
+ * Evenly place transforms along `points` (XZ polyline). The run length is divided into the whole
+ * number of equal spans closest to `spacing`, so instances always land on both endpoints and stay
+ * evenly distributed. Returns `spans + 1` instances. Empty for fewer than 2 points.
+ */
+export function placeAlongPath(points, options) {
+    if (points.length < 2)
+        return [];
+    const line = polyline(points.map((point) => [point.x, point.z]));
+    const total = line.length;
+    if (total <= 0)
+        return [];
+    const spacing = Math.max(0.01, options.spacing);
+    const minSpans = Math.max(1, (options.minCount ?? 1) - 1);
+    const spans = Math.max(minSpans, Math.round(total / spacing), 1);
+    const step = total / spans;
+    const out = [];
+    for (let i = 0; i <= spans; i += 1) {
+        const distance = i * step;
+        const [x, z] = pointAtDistance(line, distance);
+        const [tx, tz] = tangentAtDistance(line, Math.min(distance, total - 1e-4));
+        const y = options.sampleHeight?.(x, z) ?? 0;
+        out.push({ index: i, distance, position: [x, y, z], yaw: Math.atan2(tx, tz) });
+    }
+    return out;
+}

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;