@jgengine/core 0.10.0 → 0.11.0

package/dist/world/terrain.js

@@ -1,3 +1,4 @@
+import { withPathProfiles } from "./pathTerrain.js";
 import { nearestOnPath } from "./roads.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
@@ -14,7 +15,9 @@ function hash2(ix, iz, seed) {
     h ^= h >>> 12;
     return (h >>> 0) / 4294967295;
 }
-/** Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed. */
+/** Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed.
+ * @internal
+ */
 export function valueNoise(x, z, seed) {
     const x0 = Math.floor(x);
     const z0 = Math.floor(z);
@@ -30,7 +33,9 @@ export function valueNoise(x, z, seed) {
     const bottom = lerp(v01, v11, sx);
     return lerp(top, bottom, sz) * 2 - 1;
 }
-/** Layers `valueNoise` octaves per `config` into a single normalized noise sample. */
+/** Layers `valueNoise` octaves per `config` into a single normalized noise sample.
+ * @internal
+ */
 export function fractalNoise(x, z, config) {
     let amplitude = 1;
     let frequency = config.frequency;
@@ -47,6 +52,7 @@ export function fractalNoise(x, z, config) {
     }
     return norm === 0 ? 0 : sum / norm;
 }
+/** @internal */
 export function seedFrom(value, fallback) {
     if (typeof value === "number")
         return value | 0;
@@ -60,7 +66,9 @@ export function seedFrom(value, fallback) {
     }
     return fallback;
 }
-/** Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients. */
+/** Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients.
+ * @internal
+ */
 export function withNormal(sampleHeight) {
     const epsilon = 0.75;
     return (x, z) => {
@@ -85,11 +93,15 @@ export const FLAT_FIELD = {
     sampleHeight: () => 0,
     sampleNormal: () => [0, 1, 0],
 };
-/** A flat, zero-height `TerrainField` for arenas with no elevation. */
+/** A flat, zero-height `TerrainField` for arenas with no elevation.
+ * @internal
+ */
 export function flatField() {
     return FLAT_FIELD;
 }
-/** Builds a `TerrainField` whose height is fractal noise shaped by `config`. */
+/** Builds a `TerrainField` whose height is fractal noise shaped by `config`.
+ * @internal
+ */
 export function noiseField(config = {}) {
     const fractal = {
         seed: seedFrom(config.seed, 1337),
@@ -106,6 +118,7 @@ export function noiseField(config = {}) {
         waterLevel: config.waterLevel,
     });
 }
+/** @internal */
 export function rollingField(config = {}) {
     return noiseField({
         seed: config.seed ?? "rolling",
@@ -126,7 +139,9 @@ function smoothstep(edge0, edge1, value) {
     const t = clamp01((value - edge0) / (edge1 - edge0));
     return t * t * (3 - 2 * t);
 }
-/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas. */
+/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas.
+ * @internal
+ */
 export function arenaField(config = {}) {
     const seed = seedFrom(config.seed ?? "arena", 7);
     const rolling = {
@@ -155,12 +170,15 @@ export function arenaField(config = {}) {
     };
     return fieldFromHeight(sampleHeight, { bounds: config.bounds, waterLevel: ARENA_WATER_LEVEL });
 }
+/** @internal */
 export function groundFieldFor(world) {
     if (world !== undefined && world.kind === "environment")
         return resolveEnvironmentField(world);
     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. */
+/** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers.
+ * @internal
+ */
 export function hasEnvironmentTerrain(world) {
     return world?.kind === "environment" && (world.terrain !== undefined || (world.islands?.length ?? 0) > 0);
 }
@@ -174,7 +192,8 @@ function islandContains(descriptor, x, z) {
  * Composes a base terrain and any number of bounded islands into one world field: inside an island's
  * rect the island's own field (sampled in island-local coordinates) wins, elsewhere the base terrain
  * answers, and with no base the gap is `ISLAND_VOID_HEIGHT` void. Later islands win overlaps.
- */
+  * @internal
+  */
 export function composeIslandFields(base, islands, voidHeight = ISLAND_VOID_HEIGHT) {
     if (islands.length === 0)
         return base ?? flatField();
@@ -209,14 +228,95 @@ export function composeIslandFields(base, islands, voidHeight = ISLAND_VOID_HEIG
         ...(base?.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
     };
 }
-/** The full ground field for an environment world: base `terrain` composed with any `islands`. */
+/** Bilinear offset sampled from an editor {@link TerraformSnapshot}'s vertex grid at a world point. */
+function sampleSnapshotOffset(snapshot, x, z) {
+    const { bounds, cols, rows, offsets } = snapshot;
+    const vertsX = cols + 1;
+    const spanX = Math.max(bounds.maxX - bounds.minX, snapshot.cellSize);
+    const spanZ = Math.max(bounds.maxZ - bounds.minZ, snapshot.cellSize);
+    const fx = clamp01((x - bounds.minX) / spanX) * cols;
+    const fz = clamp01((z - bounds.minZ) / spanZ) * rows;
+    const x0 = Math.min(cols, Math.floor(fx));
+    const z0 = Math.min(rows, Math.floor(fz));
+    const x1 = Math.min(cols, x0 + 1);
+    const z1 = Math.min(rows, z0 + 1);
+    const tx = fx - x0;
+    const tz = fz - z0;
+    const v00 = offsets[z0 * vertsX + x0] ?? 0;
+    const v10 = offsets[z0 * vertsX + x1] ?? 0;
+    const v01 = offsets[z1 * vertsX + x0] ?? 0;
+    const v11 = offsets[z1 * vertsX + x1] ?? 0;
+    const top = v00 + (v10 - v00) * tx;
+    const bottom = v01 + (v11 - v01) * tx;
+    return top + (bottom - top) * tz;
+}
+/**
+ * Layers an authored sculpt snapshot's offsets over a base field — the editor-to-runtime ground seam.
+ * @internal — reached through `environment({ sculpt })`; not called directly by games.
+ */
+export function sculptedField(base, snapshot) {
+    const sampleHeight = (x, z) => base.sampleHeight(x, z) + sampleSnapshotOffset(snapshot, x, z);
+    return {
+        sampleHeight,
+        sampleNormal: withNormal(sampleHeight),
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+    };
+}
+/**
+ * Levels a base field toward each clearance zone's center height within its radius (feathered) — so
+ * spawns, plots, and paths sit on flat ground even when a mound is nearby. The strongest overlapping
+ * zone wins. Pairs with scatter's avoid: one clearance zone both flattens ground and repels foliage.
+ * @internal — reached through `environment({ clearings })`; not called directly by games.
+ */
+export function flattenFieldAround(base, zones) {
+    if (zones.length === 0)
+        return base;
+    const sampleHeight = (x, z) => {
+        let best = 0;
+        let target = 0;
+        for (const zone of zones) {
+            const dist = Math.hypot(x - zone.x, z - zone.z);
+            if (dist >= zone.radius)
+                continue;
+            const feather = Math.max(0, zone.feather ?? 0);
+            const inner = zone.radius - feather;
+            const t = dist <= inner || feather <= 0 ? 1 : (zone.radius - dist) / feather;
+            if (t > best) {
+                best = t;
+                target = base.sampleHeight(zone.x, zone.z);
+            }
+        }
+        const height = base.sampleHeight(x, z);
+        return best > 0 ? height + (target - height) * best : height;
+    };
+    return {
+        sampleHeight,
+        sampleNormal: withNormal(sampleHeight),
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+    };
+}
+/**
+ * The full ground field for an environment world: base `terrain` composed with any `islands`, then
+ * any authored `sculpt` snapshot, then any `clearings` flattened on top — so an editor-sculpted
+ * heightfield drives both the rendered mesh and player collision, and gameplay spots stay level,
+ * through the one seam every consumer already reads.
+  * @internal
+  */
 export function resolveEnvironmentField(feature) {
     const base = feature.terrain === undefined ? null : resolveTerrainField(feature.terrain);
-    if (feature.islands === undefined || feature.islands.length === 0)
-        return base ?? flatField();
-    return composeIslandFields(base, feature.islands);
-}
-/** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6). */
+    const composed = feature.islands === undefined || feature.islands.length === 0
+        ? base ?? flatField()
+        : composeIslandFields(base, feature.islands);
+    const sculpted = feature.sculpt === undefined ? composed : sculptedField(composed, feature.sculpt);
+    return feature.clearings === undefined || feature.clearings.length === 0
+        ? sculpted
+        : flattenFieldAround(sculpted, feature.clearings);
+}
+/** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6).
+ * @internal
+ */
 export function sampleSlope(field, x, z) {
     const [nx, ny, nz] = field.sampleNormal(x, z);
     const horizontal = Math.hypot(nx, nz);
@@ -230,7 +330,8 @@ export function sampleSlope(field, x, z) {
 /**
  * Downhill force/acceleration from the local slope: direction × sin(slope angle) × `scale`.
  * Add it to any integrator's XZ velocity each tick (`scale` ≈ gravity for a free-rolling body).
- */
+  * @internal
+  */
 export function slopeForce(field, x, z, scale = 9.8) {
     const [nx, , nz] = field.sampleNormal(x, z);
     if (Math.hypot(nx, nz) < 1e-9)
@@ -258,7 +359,11 @@ const DEFAULT_TERRAIN_DETAIL = {
     roughness: 0.9,
     strength: 1,
 };
-/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level. */
+const DEFAULT_TERRAIN_MATERIAL_REPEAT = 4;
+const DEFAULT_TERRAIN_MATERIAL_STRENGTH = 1;
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
+ * @internal
+ */
 export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
     return {
         rockColor: config.rockColor ?? DEFAULT_TERRAIN_DETAIL.rockColor,
@@ -269,10 +374,20 @@ export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
         detailScale: config.detailScale ?? DEFAULT_TERRAIN_DETAIL.detailScale,
         macroScale: config.macroScale ?? DEFAULT_TERRAIN_DETAIL.macroScale,
         roughness: config.roughness ?? DEFAULT_TERRAIN_DETAIL.roughness,
-        strength: config.strength ?? DEFAULT_TERRAIN_DETAIL.strength,
+        strength: clamp01(config.strength ?? DEFAULT_TERRAIN_DETAIL.strength),
         waterLevel: config.waterLevel ?? terrainWaterLevel,
+        ...(config.material === undefined
+            ? {}
+            : {
+                material: {
+                    maps: config.material.maps,
+                    repeat: config.material.repeat ?? DEFAULT_TERRAIN_MATERIAL_REPEAT,
+                    strength: clamp01(config.material.strength ?? DEFAULT_TERRAIN_MATERIAL_STRENGTH),
+                },
+            }),
     };
 }
+/** @internal */
 export function resolveTerrainPalette(descriptor = {}) {
     const material = descriptor.material ?? DEFAULT_TERRAIN_MATERIAL;
     const preset = TERRAIN_MATERIAL_PALETTES[material];
@@ -314,25 +429,19 @@ function mixPalette(from, to, t) {
         waterline: mixHex(from.waterline, to.waterline, t),
     };
 }
-/**
- * Per-z palette sampler over a descriptor's `biomeBands` — ordered zones that cross-fade their
- * ground palette across a `fade`-wide window centered on the midpoint z between adjacent centers.
- * Below the first / above the last band clamps to that band's palette. Returns `fallback` when no
- * bands are declared. Pure math, unit-testable independent of rendering.
- */
-export function createBiomeBandSampler(bands, fallback) {
+function createBandValueSampler(bands, fallback, resolve, mix) {
     if (bands.length === 0)
         return () => fallback;
     const resolved = bands
-        .map((band) => ({ z: band.z, fade: band.fade ?? 64, palette: resolveTerrainPalette(band) }))
+        .map((band) => ({ z: band.z, fade: band.fade ?? 64, value: resolve(band) }))
         .sort((a, b) => a.z - b.z);
     const first = resolved[0];
     const last = resolved[resolved.length - 1];
     return (z) => {
         if (z <= first.z)
-            return first.palette;
+            return first.value;
         if (z >= last.z)
-            return last.palette;
+            return last.value;
         for (let i = 0; i < resolved.length - 1; i += 1) {
             const lower = resolved[i];
             const upper = resolved[i + 1];
@@ -341,19 +450,86 @@ export function createBiomeBandSampler(bands, fallback) {
             const boundary = (lower.z + upper.z) / 2;
             const half = Math.min(lower.fade, upper.fade) / 2;
             if (z <= boundary - half)
-                return lower.palette;
+                return lower.value;
             if (z >= boundary + half)
-                return upper.palette;
-            return mixPalette(lower.palette, upper.palette, smoothstep(boundary - half, boundary + half, z));
+                return upper.value;
+            return mix(lower.value, upper.value, smoothstep(boundary - half, boundary + half, z));
         }
         return fallback;
     };
 }
+/**
+ * Per-z palette sampler over a descriptor's `biomeBands` — ordered zones that cross-fade their
+ * ground palette across a `fade`-wide window centered on the midpoint z between adjacent centers.
+ * Below the first / above the last band clamps to that band's palette. Returns `fallback` when no
+ * bands are declared. Pure math, unit-testable independent of rendering.
+  * @internal
+  */
+export function createBiomeBandSampler(bands, fallback) {
+    return createBandValueSampler(bands, fallback, resolveTerrainPalette, mixPalette);
+}
+function mixBiomeFog(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    return {
+        color: mixHex(from.color, to.color, t),
+        near: lerp(from.near, to.near, t),
+        far: lerp(from.far, to.far, t),
+        density: lerp(from.density, to.density, t),
+    };
+}
+/**
+ * Per-z fog sampler over a descriptor's `biomeBands` — cross-fades each band's `fog` (unset fields
+ * falling through to `fallback`) across the same `fade` window as the ground sampler, so fog color and
+ * range track the camera's z. Bands with no `fog` resolve to `fallback`. Pure math, unit-testable.
+  * @internal
+  */
+export function createBiomeFogSampler(bands, fallback) {
+    return createBandValueSampler(bands, fallback, (band) => band.fog === undefined
+        ? fallback
+        : {
+            color: band.fog.color ?? fallback.color,
+            near: band.fog.near ?? fallback.near,
+            far: band.fog.far ?? fallback.far,
+            density: band.fog.density ?? fallback.density,
+        }, mixBiomeFog);
+}
+function mixBiomeSky(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    return {
+        horizonColor: mixHex(from.horizonColor, to.horizonColor, t),
+        zenithColor: mixHex(from.zenithColor, to.zenithColor, t),
+        sunIntensity: lerp(from.sunIntensity, to.sunIntensity, t),
+        ambientIntensity: lerp(from.ambientIntensity, to.ambientIntensity, t),
+    };
+}
+/**
+ * Per-z sky sampler over a descriptor's `biomeBands` — cross-fades each band's `sky` (unset fields
+ * falling through to `fallback`) across the same `fade` window as the ground sampler, so horizon/zenith
+ * colors and sun/ambient intensity track the camera's z. Bands with no `sky` resolve to `fallback`.
+  * @internal
+  */
+export function createBiomeSkySampler(bands, fallback) {
+    return createBandValueSampler(bands, fallback, (band) => band.sky === undefined
+        ? fallback
+        : {
+            horizonColor: band.sky.horizonColor ?? fallback.horizonColor,
+            zenithColor: band.sky.zenithColor ?? fallback.zenithColor,
+            sunIntensity: band.sky.sunIntensity ?? fallback.sunIntensity,
+            ambientIntensity: band.sky.ambientIntensity ?? fallback.ambientIntensity,
+        }, mixBiomeSky);
+}
 /**
  * Per-position palette sampler over the descriptor's base `material`/`colors` plus its z-ordered
  * `biomeBands` (painted first) and radial `materialRegions` (painted over) — the multi-biome coloring
  * seam. Regions paint fully inside `radius` and blend back across `falloff`; later regions win overlaps.
- */
+  * @internal
+  */
 export function createTerrainPaletteSampler(descriptor) {
     const base = resolveTerrainPalette(descriptor);
     const bandSampler = descriptor.biomeBands === undefined || descriptor.biomeBands.length === 0
@@ -440,6 +616,7 @@ function withFlattenMasks(sampleHeight, masks) {
         return height;
     };
 }
+/** @internal */
 export function heightMapField(config) {
     const { columns, rows, samples } = config;
     if (columns <= 0 || rows <= 0)
@@ -476,7 +653,9 @@ export function heightMapField(config) {
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
     });
 }
-/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks. */
+/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks.
+ * @internal
+ */
 export function resolveTerrainField(descriptor) {
     if (descriptor === undefined)
         return flatField();
@@ -498,19 +677,44 @@ export function resolveTerrainField(descriptor) {
             waterLevel: descriptor.waterLevel,
             bounds: descriptor.bounds,
         });
-    if (descriptor.flatten === undefined || descriptor.flatten.length === 0)
-        return base;
-    return fieldFromHeight(withFlattenMasks(base.sampleHeight, descriptor.flatten), {
-        bounds: base.bounds,
-        waterLevel: base.waterLevel,
-    });
+    const flattened = descriptor.flatten === undefined || descriptor.flatten.length === 0
+        ? base
+        : fieldFromHeight(withFlattenMasks(base.sampleHeight, descriptor.flatten), {
+            bounds: base.bounds,
+            waterLevel: base.waterLevel,
+        });
+    if (descriptor.pathProfiles === undefined || descriptor.pathProfiles.length === 0)
+        return flattened;
+    return applyPathProfiles(flattened, descriptor.pathProfiles);
 }
-/** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`. */
+/**
+ * Composes authored path profiles onto a field — the shared seam that turns a scene road/river/ramp path
+ * into flattened, graded, carved, or retained ground. Applies after `flatten` masks in `resolveTerrainField`
+ * so a corridor grades over already-leveled pads; call it directly to layer profiles onto any field a game
+ * builds by hand. Returns the field unchanged when no profile is given.
+ * @capability path-terrain apply flatten/grade/carve/retaining path profiles to a terrain field
+ */
+export function applyPathProfiles(field, profiles) {
+    if (profiles.length === 0)
+        return field;
+    const sampleHeight = withPathProfiles((x, z) => field.sampleHeight(x, z), profiles);
+    return {
+        sampleHeight,
+        sampleNormal: withNormal(sampleHeight),
+        ...(field.bounds === undefined ? {} : { bounds: field.bounds }),
+        ...(field.waterLevel === undefined ? {} : { waterLevel: field.waterLevel }),
+    };
+}
+/** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`.
+ * @internal
+ */
 export function snapToGround(field, position, offset = 0) {
     const [x, , z] = position;
     return [x, field.sampleHeight(x, z) + offset, z];
 }
-/** Ground-snaps an already-spawned entity in place; returns false when `id` is unknown. */
+/** Ground-snaps an already-spawned entity in place; returns false when `id` is unknown.
+ * @internal
+ */
 export function snapEntityToGround(entities, id, field, offset = 0) {
     const entity = entities.get(id);
     if (entity === null)
@@ -518,7 +722,9 @@ export function snapEntityToGround(entities, id, field, offset = 0) {
     return entities.setPose(id, { position: snapToGround(field, entity.position, offset) });
 }
 export const DEFAULT_MAX_WALK_SLOPE = 0.6;
-/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`. */
+/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`.
+ * @internal
+ */
 export function resolveGroundStep(field, x, z, stepX, stepZ, maxSlope = DEFAULT_MAX_WALK_SLOPE) {
     const baseHeight = field.sampleHeight(x, z);
     const tooSteep = (dx, dz) => {

package/dist/world/terrainGuides.d.ts

@@ -0,0 +1,182 @@
+import type { TerrainField } from "./terrain.js";
+/** A world-space point on the ground plane as an `[x, z]` pair. */
+export type GroundPoint = readonly [number, number];
+/** A height sampler over the ground: world elevation at any `x`/`z`. */
+export type HeightSampler = (x: number, z: number) => number;
+/** An axis-aligned XZ rectangle to generate terrain-readability guides within. */
+export interface GuideRegion {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/**
+ * A sampled height grid over a region — the shared substrate contour extraction and elevation
+ * summaries both read, so a caller can sample once and derive several guides from it.
+ * @internal — an intermediate; games call {@link extractContours} / {@link summarizeElevation} directly.
+ */
+export interface HeightGrid {
+    region: GuideRegion;
+    /** Sample columns and rows (each is `resolution + 1` points across its axis). */
+    cols: number;
+    rows: number;
+    /** Row-major heights, length `cols * rows` (row `r`, column `c` at index `r * cols + c`). */
+    heights: Float64Array;
+    min: number;
+    max: number;
+}
+/**
+ * Samples `sampleHeight` on a `(resolution + 1)²` grid across `region`, capturing the min/max seen —
+ * the bounded, budget-capped scan every guide derives from. `resolution` is clamped to `[1, maxSamples]`.
+ * @internal — building block behind the public guide generators.
+ */
+export declare function sampleHeightGrid(sampleHeight: HeightSampler, region: GuideRegion, resolution?: number, maxSamples?: number): HeightGrid;
+/** A single iso-elevation contour traced across a region as a flat list of XZ line segments. */
+export interface ContourLine {
+    /** The world elevation (`y`) this contour follows. */
+    level: number;
+    /** Whether this is a major (emphasised) contour rather than a minor one. */
+    major: boolean;
+    /**
+     * Flat segment endpoints `[x0, z0, x1, z1, ...]` — every four numbers is one XZ segment. Draw each
+     * at `y = level` to drape it on the surface; the contour is exact iso-height so it hugs terrain.
+     */
+    segments: readonly number[];
+}
+/** Shaping for {@link extractContours}: region, vertical spacing, emphasis cadence, and sample budget. */
+export interface ContourOptions {
+    region: GuideRegion;
+    /** Vertical spacing between adjacent contour lines, in world units. Must be `> 0`. */
+    interval: number;
+    /** Every Nth line (counting from `y = 0`) is a major contour. Default `5`; `<= 1` makes all major. */
+    majorEvery?: number;
+    /** Samples per axis for the marching-squares grid. Default `128`, clamped to `[1, maxSamples]`. */
+    resolution?: number;
+    /** Hard per-axis sample cap so extraction stays within an explicit budget. Default `256`. */
+    maxSamples?: number;
+}
+/**
+ * Traces surface-following contour lines from a height field via marching squares: samples a bounded
+ * grid over the region, then for every multiple of `interval` strictly inside the sampled height range
+ * emits the iso-line as XZ segments (saddle cells disambiguated by the cell-center average). Because a
+ * contour is exact constant elevation, drawing each segment at `y = level` makes it hug the terrain —
+ * the readable, scale-bearing overlay a flat ground grid cannot give. Pure math, renderer-agnostic.
+ * @capability terrain-contours iso-elevation contour lines that drape on sculpted terrain
+ * @consumer editor terrain-readability overlay; any map/minimap wanting elevation contours
+ */
+export declare function extractContours(sampleHeight: HeightSampler, options: ContourOptions): ContourLine[];
+/**
+ * Picks a human-friendly contour interval — a `1/2/2.5/5 × 10ⁿ` step — so an elevation `range` splits
+ * into roughly `targetLines` bands. Drives adaptive contour density: a tall terrain gets a coarse
+ * interval, a shallow one a fine interval, without the author choosing a number. Returns `0` when the
+ * range is non-positive (nothing to contour).
+ * @capability contour-interval readable auto-spacing for elevation contours
+ * @consumer editor terrain-readability overlay density control
+ */
+export declare function chooseContourInterval(range: number, targetLines?: number): number;
+/** Measurable elevation readout at a single world point — the cursor/hover feedback value. */
+export interface ElevationReadout {
+    x: number;
+    z: number;
+    /** Ground elevation at the point. */
+    height: number;
+    /** `height - reference` — signed distance above (+) or below (−) the reference plane. */
+    delta: number;
+    /** The reference-plane height the delta was measured against. */
+    reference: number;
+}
+/**
+ * Reads the ground elevation under a world point and its signed delta from a reference plane — the
+ * measurable cursor/hover feedback ("+3.4 above the pad") an author needs to judge sculpted height.
+ * @capability elevation-readout cursor height and delta-from-reference feedback
+ * @consumer editor terrain-readability HUD readout
+ */
+export declare function sampleElevation(sampleHeight: HeightSampler, x: number, z: number, reference?: number): ElevationReadout;
+/** Aggregate elevation statistics over a region — the selection min/max/mean and legend range. */
+export interface ElevationSummary {
+    min: number;
+    max: number;
+    mean: number;
+    /** `max - min` — the vertical relief across the region. */
+    range: number;
+    /** World point where the lowest sample was found. */
+    minAt: GroundPoint;
+    /** World point where the highest sample was found. */
+    maxAt: GroundPoint;
+    /** Number of grid samples taken. */
+    samples: number;
+}
+/**
+ * Summarises elevation across a region on a bounded sample grid: min, max, mean, relief range, and the
+ * world points of the extremes — the selection min/max and legend feedback the readability overlay
+ * reports, and the input to {@link chooseContourInterval}. Pure math, renderer-agnostic.
+ * @capability elevation-summary selection min/max/mean and relief over a region
+ * @consumer editor terrain-readability legend and selection stats
+ */
+export declare function summarizeElevation(sampleHeight: HeightSampler, region: GuideRegion, resolution?: number, maxSamples?: number): ElevationSummary;
+/** Shaping for surface draping: subdivision spacing and a lift to keep the line off the ground. */
+export interface DrapeOptions {
+    /** Max world spacing between draped vertices; longer spans are subdivided so the line hugs the surface. Default `1`. */
+    spacing?: number;
+    /** Lift each draped vertex this far above the sampled surface, to avoid z-fighting. Default `0`. */
+    offset?: number;
+}
+/**
+ * Drapes an XZ polyline onto the surface: subdivides each span to at most `spacing` and lifts every
+ * vertex to `sampleHeight + offset`, returning flat `[x, y, z, ...]` world triples. The reusable seam
+ * behind surface-following placement guides and grid lines — a straight guide bends to follow terrain.
+ * @capability surface-drape lift an XZ polyline onto sculpted terrain
+ * @consumer editor placement guides and surface grid overlay
+ */
+export declare function drapePolyline(sampleHeight: HeightSampler, points: readonly GroundPoint[], options?: DrapeOptions): number[];
+/**
+ * A closed circle draped on the surface — the surface-following placement guide ring under a cursor or
+ * a selected object. Returns flat `[x, y, z, ...]` world triples forming a loop (last vertex repeats
+ * the first). `segments` sets the smoothness of the ring.
+ * @capability surface-ring surface-following placement guide ring
+ * @consumer editor cursor/placement guide
+ */
+export declare function surfaceRing(sampleHeight: HeightSampler, center: GroundPoint, radius: number, segments?: number, options?: DrapeOptions): number[];
+/** One draped grid line from {@link surfaceGridLines}: its axis, emphasis, and draped vertices. */
+export interface SurfaceGridLine {
+    /** Which axis the line runs constant along: an `"x"` line holds `x` fixed and spans `z`, and vice versa. */
+    axis: "x" | "z";
+    /** The constant coordinate value the line holds. */
+    at: number;
+    /** Whether this is a major (emphasised) grid line. */
+    major: boolean;
+    /** Flat `[x, y, z, ...]` world triples draped on the surface. */
+    points: readonly number[];
+}
+/** Shaping for {@link surfaceGridLines}: region, spacing, emphasis cadence, and draping. */
+export interface SurfaceGridOptions {
+    region: GuideRegion;
+    /** World distance between adjacent grid lines. Must be `> 0`. */
+    spacing: number;
+    /** Every Nth line (counting from origin) is a major line. Default `5`; `<= 1` makes all major. */
+    majorEvery?: number;
+    /** Draping options for each line. */
+    drape?: DrapeOptions;
+}
+/**
+ * Builds a surface-following major/minor grid over a region: constant-`x` and constant-`z` lines at
+ * `spacing`, each draped onto the terrain so the reference grid climbs sculpted surfaces instead of
+ * being occluded by them (the flat `y = 0` grid's core failure). Draping subdivides to
+ * `drape.spacing`. Pure math, renderer-agnostic.
+ * @capability surface-grid terrain-following reference grid that is not occluded by relief
+ * @consumer editor terrain-readability grid overlay
+ */
+export declare function surfaceGridLines(sampleHeight: HeightSampler, options: SurfaceGridOptions): SurfaceGridLine[];
+/**
+ * Convenience over {@link extractContours} that auto-picks the interval from the field's own relief:
+ * summarises the region, chooses a readable interval for `targetLines` bands, and traces the contours —
+ * the one call the editor overlay makes to turn a `TerrainField` into ready-to-draw guides. Returns an
+ * empty list for flat ground.
+ * @capability terrain-guides one-call adaptive contours for a terrain field
+ * @consumer editor terrain-readability overlay
+ */
+export declare function terrainContourGuides(field: Pick<TerrainField, "sampleHeight">, region: GuideRegion, targetLines?: number, resolution?: number): {
+    interval: number;
+    summary: ElevationSummary;
+    contours: ContourLine[];
+};