@jgengine/core 0.11.0 → 0.12.0

package/dist/world/resourceNode.js

@@ -0,0 +1,140 @@
+import { clamp } from "../math/scalar.js";
+function resolveQuantity(quantity, rng) {
+    if (typeof quantity === "number")
+        return quantity;
+    const [lo, hi] = quantity;
+    return lo + rng() * (hi - lo);
+}
+function toState(node) {
+    return {
+        id: node.def.id,
+        budget: node.budget,
+        maxBudget: node.maxBudget,
+        depleted: node.depleted,
+        respawnTimer: node.respawnTimer,
+        respawnBlocked: node.respawnBlocked,
+        fraction: node.maxBudget > 0 ? clamp(node.budget / node.maxBudget, 0, 1) : 0,
+    };
+}
+/**
+ * A field of depletable, respawning harvest nodes with tool-dependent yields — the generic rock / tree /
+ * bush / vein / corpse. Each node holds a finite budget across one or more resource kinds. A harvest applies
+ * a {@link ToolProfile} whose per-resource biases decide *which* resources and *how much* the same node
+ * returns (pick favors ore, hatchet favors wood), scaled by a creature/harvester multiplier and optional
+ * deterministic rng variance; the budget drops by the tool's power. When a node empties it starts a respawn
+ * timer that `tick(dt)` counts down and refills — unless respawn is suppressed by the per-node flag or the
+ * injected predicate (a structure claimed the spot). All state is plain and serializable for save-load and
+ * multiplayer sync via {@link snapshot}/{@link hydrate}.
+ *
+ * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
+ */
+export function createResourceNodeField(config) {
+    const rng = config.rng ?? Math.random;
+    const nodes = new Map();
+    const order = [];
+    for (const def of config.nodes) {
+        if (nodes.has(def.id))
+            throw new Error(`duplicate resource node "${def.id}"`);
+        const respawnBudget = def.respawnBudget ?? def.budget;
+        nodes.set(def.id, {
+            def,
+            budget: def.budget,
+            maxBudget: def.budget,
+            respawnBudget,
+            depleted: def.budget <= 0,
+            respawnTimer: 0,
+            respawnBlocked: false,
+        });
+        order.push(def.id);
+    }
+    const getNode = (id) => {
+        const node = nodes.get(id);
+        if (node === undefined)
+            throw new Error(`unknown resource node "${id}"`);
+        return node;
+    };
+    const isSuppressed = (node) => {
+        if (node.respawnBlocked)
+            return true;
+        if (config.respawnSuppressed === undefined)
+            return false;
+        return config.respawnSuppressed(toState(node));
+    };
+    return {
+        harvest(nodeId, tool, options = {}) {
+            const node = getNode(nodeId);
+            if (node.depleted || node.budget <= 0) {
+                return { nodeId, granted: [], spent: 0, harvested: false, depleted: node.depleted };
+            }
+            const power = tool.power !== undefined && tool.power > 0 ? tool.power : 1;
+            const spent = Math.min(power, node.budget);
+            const multiplier = options.multiplier ?? 1;
+            const defaultBias = tool.defaultBias ?? 1;
+            const granted = [];
+            for (const resource of node.def.resources) {
+                // Resolve variance for every resource so the rng stream stays independent of tool choice.
+                const base = resolveQuantity(resource.amount, rng);
+                const bias = tool.biases?.[resource.kind] ?? defaultBias;
+                const amount = base * bias * multiplier;
+                if (amount > 0)
+                    granted.push({ kind: resource.kind, amount });
+            }
+            node.budget -= spent;
+            let depleted = false;
+            if (node.budget <= 0) {
+                node.budget = 0;
+                node.depleted = true;
+                depleted = true;
+                node.respawnTimer = node.def.respawn ?? 0;
+            }
+            return { nodeId, granted, spent, harvested: true, depleted };
+        },
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            for (const id of order) {
+                const node = nodes.get(id);
+                if (!node.depleted || node.def.respawn === undefined)
+                    continue;
+                if (isSuppressed(node))
+                    continue;
+                node.respawnTimer -= dt;
+                if (node.respawnTimer <= 0) {
+                    node.budget = node.respawnBudget;
+                    node.depleted = false;
+                    node.respawnTimer = 0;
+                }
+            }
+        },
+        state(nodeId) {
+            return toState(getNode(nodeId));
+        },
+        isDepleted(nodeId) {
+            return getNode(nodeId).depleted;
+        },
+        setRespawnBlocked(nodeId, blocked) {
+            getNode(nodeId).respawnBlocked = blocked;
+        },
+        ids() {
+            return order;
+        },
+        snapshot() {
+            const out = {};
+            for (const id of order)
+                out[id] = toState(nodes.get(id));
+            return out;
+        },
+        hydrate(snapshot) {
+            for (const id of order) {
+                const saved = snapshot[id];
+                if (saved === undefined)
+                    continue;
+                const node = nodes.get(id);
+                node.budget = saved.budget;
+                node.depleted = saved.depleted;
+                node.respawnTimer = saved.respawnTimer;
+                node.respawnBlocked = saved.respawnBlocked;
+            }
+        },
+    };
+}

package/dist/world/scatter.js

@@ -1,4 +1,5 @@
 import { expandAabb, pointInAabb } from "./geometry.js";
+import { seededRng } from "../random/rng.js";
 function isAabb(area) {
     return (typeof area.minX === "number" &&
         typeof area.minZ === "number" &&
@@ -15,25 +16,6 @@ export function scatterAabb(area) {
     const halfD = area.d / 2;
     return { minX: cx - halfW, minZ: cz - halfD, maxX: cx + halfW, maxZ: cz + halfD };
 }
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
-    let h = 2166136261 >>> 0;
-    for (let i = 0; i < text.length; i++) {
-        h ^= text.charCodeAt(i);
-        h = Math.imul(h, 16777619);
-    }
-    return h >>> 0;
-}
-function mulberry32(state) {
-    let a = state >>> 0;
-    return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
 export function scatter(config) {
     const aabb = scatterAabb(config.area);
     const width = aabb.maxX - aabb.minX;
@@ -47,7 +29,7 @@ export function scatter(config) {
     const jitter = config.jitter ?? 1;
     const maxAttempts = config.maxAttempts ?? target * 30;
     const avoid = (config.avoid ?? []).map((a) => (avoidMargin !== 0 ? expandAabb(a, avoidMargin) : a));
-    const rng = mulberry32(hashSeed(config.seed ?? "scatter"));
+    const rng = seededRng(config.seed ?? "scatter");
     const useDistance = minDistance > 0;
     const buckets = new Map();
     const bucketKey = (x, z) => `${Math.floor(x / minDistance)}:${Math.floor(z / minDistance)}`;

package/dist/world/streets.d.ts

@@ -73,6 +73,35 @@ export interface ParkingSpot {
  * coordinates in the middle of the carriageway.
  */
 export declare function parkingSpots(road: RoadEnvironmentDescriptor, options?: ParkingSpotOptions): readonly ParkingSpot[];
+/**
+ * Signed planar distance from `(x, z)` to the nearest road *surface edge* across every segment of
+ * every road (#1051): negative inside the asphalt (magnitude = how far in from the closest edge, so
+ * `-width/2` on the centerline), `~0` right at the curb, and positive off the road (the gap to the
+ * nearest edge). Point-to-segment distance minus the road's half width, minimised over all segments —
+ * the "am I on the road, and by how much" seam driving grip, tyre audio, and off-road penalties.
+ *
+ * Allocation-free per call (only scalars — no arrays or objects) so a per-tick car sim can sample it
+ * on the hot path; degenerate roads (fewer than two path points) contribute nothing, and with no road
+ * surface at all it returns {@link Number.POSITIVE_INFINITY} (everywhere is off-road).
+ */
+export declare function distanceToRoadEdge(roads: readonly RoadEnvironmentDescriptor[], x: number, z: number): number;
+/** Grip levels and blend width for {@link roadSurfaceSampler}; each field is optional and defaulted. */
+export interface RoadSurfaceOptions {
+    /** Grip multiplier on the asphalt. Default 1. */
+    onRoad?: number;
+    /** Grip multiplier once fully off the road past the shoulder. Default 0.72. */
+    offRoad?: number;
+    /** Width (world units) of the blend band outside the curb from full to off-road grip. Default 3. */
+    shoulder?: number;
+}
+/**
+ * A `surfaceFriction`-compatible sampler (the `(x, z) => grip` hook a kinematic car reads each tick)
+ * that turns road geometry into grip (#1051): full `onRoad` grip on the asphalt, a monotonic linear ramp
+ * down across a `shoulder`-wide band at the curb, and flat `offRoad` grip beyond it — so a car that
+ * clips onto the grass loses bite progressively instead of snapping. Closes over {@link
+ * distanceToRoadEdge}, so the returned sampler is itself allocation-free per call.
+ */
+export declare function roadSurfaceSampler(roads: readonly RoadEnvironmentDescriptor[], options?: RoadSurfaceOptions): (x: number, z: number) => number;
 /**
  * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
  * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.

package/dist/world/streets.js

@@ -130,6 +130,61 @@ export function parkingSpots(road, options = {}) {
     }
     return spots;
 }
+/**
+ * Signed planar distance from `(x, z)` to the nearest road *surface edge* across every segment of
+ * every road (#1051): negative inside the asphalt (magnitude = how far in from the closest edge, so
+ * `-width/2` on the centerline), `~0` right at the curb, and positive off the road (the gap to the
+ * nearest edge). Point-to-segment distance minus the road's half width, minimised over all segments —
+ * the "am I on the road, and by how much" seam driving grip, tyre audio, and off-road penalties.
+ *
+ * Allocation-free per call (only scalars — no arrays or objects) so a per-tick car sim can sample it
+ * on the hot path; degenerate roads (fewer than two path points) contribute nothing, and with no road
+ * surface at all it returns {@link Number.POSITIVE_INFINITY} (everywhere is off-road).
+ */
+export function distanceToRoadEdge(roads, x, z) {
+    let best = Number.POSITIVE_INFINITY;
+    for (let r = 0; r < roads.length; r += 1) {
+        const road = roads[r];
+        const path = road.path;
+        if (path.length < 2)
+            continue;
+        const half = road.width / 2;
+        for (let i = 0; i < path.length - 1; i += 1) {
+            const a = path[i];
+            const b = path[i + 1];
+            const abx = b[0] - a[0];
+            const abz = b[1] - a[1];
+            const lengthSq = abx * abx + abz * abz;
+            const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / lengthSq));
+            const px = a[0] + abx * t;
+            const pz = a[1] + abz * t;
+            const edge = Math.hypot(x - px, z - pz) - half;
+            if (edge < best)
+                best = edge;
+        }
+    }
+    return best;
+}
+/**
+ * A `surfaceFriction`-compatible sampler (the `(x, z) => grip` hook a kinematic car reads each tick)
+ * that turns road geometry into grip (#1051): full `onRoad` grip on the asphalt, a monotonic linear ramp
+ * down across a `shoulder`-wide band at the curb, and flat `offRoad` grip beyond it — so a car that
+ * clips onto the grass loses bite progressively instead of snapping. Closes over {@link
+ * distanceToRoadEdge}, so the returned sampler is itself allocation-free per call.
+ */
+export function roadSurfaceSampler(roads, options = {}) {
+    const onRoad = options.onRoad ?? 1;
+    const offRoad = options.offRoad ?? 0.72;
+    const shoulder = options.shoulder ?? 3;
+    return (x, z) => {
+        const edge = distanceToRoadEdge(roads, x, z);
+        if (edge <= 0)
+            return onRoad;
+        if (shoulder <= 0 || edge >= shoulder)
+            return offRoad;
+        return onRoad + (offRoad - onRoad) * (edge / shoulder);
+    };
+}
 /**
  * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
  * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.

package/dist/world/terraform.js

@@ -218,13 +218,18 @@ export function createEditableTerrain(config) {
         record?.(index, before, surface);
         return true;
     }
-    function paintSurface(edit, record) {
-        const surface = edit.surface ?? null;
+    /**
+     * Visits every cell in a brush footprint on the CELL grid, yielding each cell's flat `index`, its
+     * {@link brushWeight} `weight`, world center (`wx`,`wz`), and raw `dist` from the brush center.
+     * Shared by the cell-grid brushes ({@link paintSurface}, {@link blendPaint}); each applies its own
+     * inclusion test on the yielded values (paint uses `dist <= radius`, blend uses `weight > 0`).
+     */
+    function forEachBrushCell(edit, visit) {
+        const falloff = edit.falloff ?? "smooth";
         const shape = edit.shape ?? "circle";
         const rCells = Math.ceil(edit.radius / cellSize) + 1;
         const cx = gridX(edit.center[0]);
         const cz = gridZ(edit.center[1]);
-        let painted = 0;
         for (let iz = -rCells; iz <= rCells; iz += 1) {
             const gz = Math.floor(cz) + iz;
             if (gz < 0 || gz >= rows)
@@ -233,15 +238,25 @@ export function createEditableTerrain(config) {
                 const gx = Math.floor(cx) + ix;
                 if (gx < 0 || gx >= cols)
                     continue;
-                const dx = cellWorldX(gx) - edit.center[0];
-                const dz = cellWorldZ(gz) - edit.center[1];
+                const wx = cellWorldX(gx);
+                const wz = cellWorldZ(gz);
+                const dx = wx - edit.center[0];
+                const dz = wz - edit.center[1];
                 const dist = shape === "square" ? Math.max(Math.abs(dx), Math.abs(dz)) : Math.hypot(dx, dz);
-                if (dist > edit.radius)
-                    continue;
-                if (writeSurface(gz * cols + gx, surface, record))
-                    painted += 1;
+                visit(gz * cols + gx, brushWeight(dist, edit.radius, falloff), wx, wz, dist);
             }
         }
+    }
+    function paintSurface(edit, record) {
+        const surface = edit.surface ?? null;
+        let painted = 0;
+        // Binary inclusion by raw distance (includes dist == radius), independent of falloff shaping.
+        forEachBrushCell(edit, (index, _weight, _wx, _wz, dist) => {
+            if (dist > edit.radius)
+                return;
+            if (writeSurface(index, surface, record))
+                painted += 1;
+        });
         return painted;
     }
     function localNormal(wx, wz) {
@@ -371,31 +386,14 @@ export function createEditableTerrain(config) {
         const target = layers.findIndex((entry) => entry.surface === surface);
         if (target < 0)
             return 0;
-        const falloff = edit.falloff ?? "smooth";
-        const shape = edit.shape ?? "circle";
         const strength = edit.strength ?? 1;
-        const rCells = Math.ceil(edit.radius / cellSize) + 1;
-        const cx = gridX(edit.center[0]);
-        const cz = gridZ(edit.center[1]);
         let painted = 0;
-        for (let iz = -rCells; iz <= rCells; iz += 1) {
-            const gz = Math.floor(cz) + iz;
-            if (gz < 0 || gz >= rows)
-                continue;
-            for (let ix = -rCells; ix <= rCells; ix += 1) {
-                const gx = Math.floor(cx) + ix;
-                if (gx < 0 || gx >= cols)
-                    continue;
-                const dx = cellWorldX(gx) - edit.center[0];
-                const dz = cellWorldZ(gz) - edit.center[1];
-                const dist = shape === "square" ? Math.max(Math.abs(dx), Math.abs(dz)) : Math.hypot(dx, dz);
-                const weight = brushWeight(dist, edit.radius, falloff);
-                if (weight <= 0)
-                    continue;
-                if (blendCell(gz * cols + gx, target, weight * strength, record))
-                    painted += 1;
-            }
-        }
+        forEachBrushCell(edit, (index, weight) => {
+            if (weight <= 0)
+                return;
+            if (blendCell(index, target, weight * strength, record))
+                painted += 1;
+        });
         return painted;
     }
     function runHeightEdit(edit, record) {
@@ -545,23 +543,29 @@ export function createEditableTerrain(config) {
     };
     return field;
 }
-/** Opens a stroke recorder over `terrain`; stamp edits into it, then read one net delta. */
-export function beginTerraformStroke(terrain) {
+/**
+ * The shared first/latest Map accumulator behind every `begin*Stroke`. Records each key's first
+ * `before` and latest `after` across many stamps, then assembles the net changed entries (skipping
+ * keys whose latest equals their first). Each stroke supplies its own recording call via `recordStamp`
+ * and wraps {@link StrokeChanges} into its concrete delta shape.
+ */
+function createStroke(recordStamp) {
     const first = new Map();
     const latest = new Map();
     return {
         stamp(edit) {
-            return terrain.applyRecording(edit, (index, before, after) => {
+            return recordStamp(edit, (index, before, after) => {
                 if (!first.has(index))
                     first.set(index, before);
                 latest.set(index, after);
             });
         },
-        delta() {
+        changes() {
             const indices = [];
             const before = [];
             const after = [];
             for (const [index, next] of latest) {
+                // Every latest key was set in `first` on the same callback, so this is always present.
                 const prev = first.get(index);
                 if (next === prev)
                     continue;
@@ -576,35 +580,22 @@ export function beginTerraformStroke(terrain) {
         },
     };
 }
+/** Opens a stroke recorder over `terrain`; stamp edits into it, then read one net delta. */
+export function beginTerraformStroke(terrain) {
+    const stroke = createStroke((edit, record) => terrain.applyRecording(edit, record));
+    return {
+        stamp: stroke.stamp,
+        delta: () => stroke.changes(),
+        isEmpty: stroke.isEmpty,
+    };
+}
 /** Opens a paint-stroke recorder over `terrain`; stamp paint edits into it, then read one net delta. */
 export function beginSurfaceStroke(terrain) {
-    const first = new Map();
-    const latest = new Map();
+    const stroke = createStroke((edit, record) => terrain.paintRecording(edit, record));
     return {
-        stamp(edit) {
-            return terrain.paintRecording(edit, (index, before, after) => {
-                if (!first.has(index))
-                    first.set(index, before);
-                latest.set(index, after);
-            });
-        },
-        delta() {
-            const indices = [];
-            const before = [];
-            const after = [];
-            for (const [index, next] of latest) {
-                const prev = first.get(index) ?? null;
-                if (next === prev)
-                    continue;
-                indices.push(index);
-                before.push(prev);
-                after.push(next);
-            }
-            return { indices, before, after };
-        },
-        isEmpty() {
-            return latest.size === 0;
-        },
+        stamp: stroke.stamp,
+        delta: () => stroke.changes(),
+        isEmpty: stroke.isEmpty,
     };
 }
 /** Returns a new snapshot with a surface delta's `after` ids applied (copy-on-write). */
@@ -700,33 +691,12 @@ export function revertWeightDeltaFromSnapshot(snapshot, delta) {
  * @internal — the stroke recorder behind the blend brush and the `blendTerrain` command.
  */
 export function beginBlendStroke(terrain) {
-    const first = new Map();
-    const latest = new Map();
+    const stroke = createStroke((edit, record) => terrain.blendRecording(edit, record));
     return {
-        stamp(edit) {
-            return terrain.blendRecording(edit, (index, before, after) => {
-                if (!first.has(index))
-                    first.set(index, before);
-                latest.set(index, after);
-            });
-        },
-        delta() {
-            const indices = [];
-            const before = [];
-            const after = [];
-            for (const [index, next] of latest) {
-                const prev = first.get(index);
-                if (next === prev)
-                    continue;
-                indices.push(index);
-                before.push(prev);
-                after.push(next);
-            }
-            return { layerCount: terrain.layers.length, indices, before, after };
-        },
-        isEmpty() {
-            return latest.size === 0;
-        },
+        stamp: stroke.stamp,
+        // layerCount is read at delta() time, guarding replay after the layer stack changed shape.
+        delta: () => ({ layerCount: terrain.layers.length, ...stroke.changes() }),
+        isEmpty: stroke.isEmpty,
     };
 }
 /**

package/dist/world/terrain.d.ts

@@ -124,6 +124,51 @@ export declare function sampleSlope(field: TerrainField, x: number, z: number):
   * @internal
   */
 export declare function slopeForce(field: TerrainField, x: number, z: number, scale?: number): readonly [number, number];
+/** XZ region a {@link raycastHeightField} march is clipped to. */
+export interface HeightFieldRayBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** Tuning for {@link raycastHeightField}: march resolution and refinement depth. */
+export interface HeightFieldRaycastOptions {
+    /** XZ region to march within; the ray is clipped to it before any sampling. */
+    bounds: HeightFieldRayBounds;
+    /**
+     * March step in world units. Use about half the field's cell size — features narrower than one
+     * step can be skipped. Defaults to 1/256 of the larger bounds span, clamped to `[0.25, 4]`.
+     */
+    step?: number;
+    /** Bisection iterations refining the crossing once found (default 8 ≈ step/256 precision). */
+    refine?: number;
+    /** Stop marching past this ray distance (default: the full bounds crossing). */
+    maxDistance?: number;
+    /**
+     * Hard cap on march samples (default 4096). Bounds the work for rays the XZ slab cannot clip —
+     * a near-vertical ray inside bounds has an enormous slab crossing, and an upward ray never
+     * meets the surface at all; the cap turns both into a prompt miss instead of a stall.
+     */
+    maxSteps?: number;
+}
+/** Where a {@link raycastHeightField} march crossed the surface. */
+export interface HeightFieldRayHit {
+    x: number;
+    y: number;
+    z: number;
+    /** Ray-parameter distance from the origin to the hit (direction is normalized internally). */
+    distance: number;
+}
+/**
+ * Intersects a ray with a `sampleHeight` field by fixed-step raymarching plus bisection — the
+ * O(steps) editor/gameplay picking seam that replaces brute-force triangle raycasts against a
+ * tessellated ground mesh (tens of thousands of triangle tests per pick on a sculpt-sized grid).
+ * The ray is clipped to `bounds` on XZ first, marched at `step`, and the first above→below
+ * crossing is bisected. An origin already under the surface hits immediately at entry. Returns
+ * null when the clipped ray never crosses the surface.
+ * @capability terrain-raycast pick a point on a heightfield along a camera/pointer ray
+ */
+export declare function raycastHeightField(sampleHeight: (x: number, z: number) => number, origin: readonly [number, number, number], direction: readonly [number, number, number], options: HeightFieldRaycastOptions): HeightFieldRayHit | null;
 export interface TerrainPalette {
     low: string;
     high: string;

package/dist/world/terrain.js

@@ -174,6 +174,10 @@ export function arenaField(config = {}) {
 export function groundFieldFor(world) {
     if (world !== undefined && world.kind === "environment")
         return resolveEnvironmentField(world);
+    // Place worlds (`world()` from world/place) stand on a flat baseline field: flat/board grounds are
+    // exactly y=0, while round/voxel grounds keep their sampled shape in the game's own generation
+    // systems (the substrate declaration never bakes a heightfield). Editor-authored sculpt still
+    // layers through the environment path above.
     return flatField();
 }
 /** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers.
@@ -338,6 +342,80 @@ export function slopeForce(field, x, z, scale = 9.8) {
         return [0, 0];
     return [nx * scale, nz * scale];
 }
+/**
+ * Intersects a ray with a `sampleHeight` field by fixed-step raymarching plus bisection — the
+ * O(steps) editor/gameplay picking seam that replaces brute-force triangle raycasts against a
+ * tessellated ground mesh (tens of thousands of triangle tests per pick on a sculpt-sized grid).
+ * The ray is clipped to `bounds` on XZ first, marched at `step`, and the first above→below
+ * crossing is bisected. An origin already under the surface hits immediately at entry. Returns
+ * null when the clipped ray never crosses the surface.
+ * @capability terrain-raycast pick a point on a heightfield along a camera/pointer ray
+ */
+export function raycastHeightField(sampleHeight, origin, direction, options) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (length < 1e-12)
+        return null;
+    const dx = direction[0] / length;
+    const dy = direction[1] / length;
+    const dz = direction[2] / length;
+    const { bounds } = options;
+    // Clip [t0, t1] to the XZ slab of bounds.
+    let t0 = 0;
+    let t1 = options.maxDistance ?? Infinity;
+    for (const [o, d, min, max] of [
+        [origin[0], dx, bounds.minX, bounds.maxX],
+        [origin[2], dz, bounds.minZ, bounds.maxZ],
+    ]) {
+        if (Math.abs(d) < 1e-12) {
+            if (o < min || o > max)
+                return null;
+            continue;
+        }
+        const ta = (min - o) / d;
+        const tb = (max - o) / d;
+        const near = Math.min(ta, tb);
+        const far = Math.max(ta, tb);
+        if (near > t0)
+            t0 = near;
+        if (far < t1)
+            t1 = far;
+    }
+    if (t1 <= t0)
+        return null;
+    const spanX = bounds.maxX - bounds.minX;
+    const spanZ = bounds.maxZ - bounds.minZ;
+    const step = options.step ?? Math.min(4, Math.max(0.25, Math.max(spanX, spanZ) / 256));
+    const refine = options.refine ?? 8;
+    const maxSteps = options.maxSteps ?? 4096;
+    const above = (t) => origin[1] + dy * t - sampleHeight(origin[0] + dx * t, origin[2] + dz * t);
+    let prevT = t0;
+    if (above(t0) <= 0) {
+        return { x: origin[0] + dx * t0, y: origin[1] + dy * t0, z: origin[2] + dz * t0, distance: t0 };
+    }
+    let steps = 0;
+    while (prevT < t1 && steps < maxSteps) {
+        steps += 1;
+        const t = Math.min(prevT + step, t1);
+        if (above(t) <= 0) {
+            let lo = prevT;
+            let hi = t;
+            for (let i = 0; i < refine; i += 1) {
+                const mid = (lo + hi) / 2;
+                if (above(mid) <= 0)
+                    hi = mid;
+                else
+                    lo = mid;
+            }
+            const x = origin[0] + dx * hi;
+            const z = origin[2] + dz * hi;
+            return { x, y: sampleHeight(x, z), z, distance: hi };
+        }
+        if (t >= t1)
+            break;
+        prevT = t;
+    }
+    return null;
+}
 export const DEFAULT_TERRAIN_MATERIAL = "grass";
 export const TERRAIN_MATERIAL_PALETTES = {
     grass: { low: "#30402c", high: "#7f8b50", waterline: "#1d4c6e" },