@jgengine/core 0.9.0 → 0.10.0

package/dist/world/roads.d.ts

@@ -0,0 +1,47 @@
+/** 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;
+}
+/** 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;

package/dist/world/roads.js

@@ -0,0 +1,146 @@
+function subdividePath(path, maxLength) {
+    const out = [];
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        const steps = Math.max(1, Math.ceil(length / maxLength));
+        for (let s = 0; s < steps; s += 1) {
+            const t = s / steps;
+            out.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+        }
+    }
+    const last = path[path.length - 1];
+    if (last !== undefined)
+        out.push(last);
+    return out;
+}
+function normalAt(points, index) {
+    const prev = points[Math.max(0, index - 1)];
+    const next = points[Math.min(points.length - 1, index + 1)];
+    const dx = next[0] - prev[0];
+    const dz = next[1] - prev[1];
+    const length = Math.hypot(dx, dz) || 1;
+    return [-dz / length, dx / length];
+}
+/**
+ * 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 function buildRoadRibbon(path, width, sampleHeight, options = {}) {
+    const elevation = options.elevation ?? 0.08;
+    const maxSegmentLength = options.maxSegmentLength ?? 4;
+    if (path.length < 2 || width <= 0) {
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    }
+    const points = subdividePath(path, maxSegmentLength);
+    const half = width / 2;
+    const positions = new Float32Array(points.length * 6);
+    for (let i = 0; i < points.length; i += 1) {
+        const [x, z] = points[i];
+        const [nx, nz] = normalAt(points, i);
+        const lx = x + nx * half;
+        const lz = z + nz * half;
+        const rx = x - nx * half;
+        const rz = z - nz * half;
+        positions[i * 6] = lx;
+        positions[i * 6 + 1] = sampleHeight(lx, lz) + elevation;
+        positions[i * 6 + 2] = lz;
+        positions[i * 6 + 3] = rx;
+        positions[i * 6 + 4] = sampleHeight(rx, rz) + elevation;
+        positions[i * 6 + 5] = rz;
+    }
+    const indices = new Uint32Array((points.length - 1) * 6);
+    for (let i = 0; i < points.length - 1; i += 1) {
+        const a = i * 2;
+        indices[i * 6] = a;
+        indices[i * 6 + 1] = a + 1;
+        indices[i * 6 + 2] = a + 2;
+        indices[i * 6 + 3] = a + 1;
+        indices[i * 6 + 4] = a + 3;
+        indices[i * 6 + 5] = a + 2;
+    }
+    return { positions, indices };
+}
+/**
+ * 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 function dashSegments(path, dashLength = 3, gapLength = 3) {
+    if (path.length < 2 || dashLength <= 0 || gapLength < 0)
+        return [];
+    const cumulative = [0];
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        cumulative.push(cumulative[i] + Math.hypot(b[0] - a[0], b[1] - a[1]));
+    }
+    const total = cumulative[cumulative.length - 1];
+    if (total <= 0)
+        return [];
+    const pointAt = (s) => {
+        const clamped = Math.max(0, Math.min(total, s));
+        let index = 0;
+        while (index < cumulative.length - 2 && cumulative[index + 1] < clamped)
+            index += 1;
+        const a = path[index];
+        const b = path[index + 1];
+        const segLength = cumulative[index + 1] - cumulative[index];
+        const t = segLength <= 0 ? 0 : (clamped - cumulative[index]) / segLength;
+        return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+    };
+    const period = dashLength + gapLength;
+    const dashes = [];
+    for (let start = 0; start < total; start += period) {
+        const end = Math.min(total, start + dashLength);
+        if (end - start < 1e-6)
+            break;
+        dashes.push([pointAt(start), pointAt(end)]);
+        if (period <= 0)
+            break;
+    }
+    return dashes;
+}
+/**
+ * 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 function nearestOnPath(path, x, z) {
+    if (path.length < 2)
+        return null;
+    let best = null;
+    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 distance = Math.hypot(x - px, z - pz);
+        if (best === null || distance < best.distance) {
+            const length = Math.sqrt(lengthSq) || 1;
+            best = { point: [px, pz], distance, tangent: [abx / length, abz / length] };
+        }
+    }
+    return best;
+}
+/** True when the query point lies within half the road `width` of the centerline. */
+export function isOnRoad(path, width, x, z) {
+    const sample = nearestOnPath(path, x, z);
+    return sample !== null && sample.distance <= width / 2;
+}
+/** Total arc length of a centerline in world units. */
+export function pathLength(path) {
+    let total = 0;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return total;
+}

package/dist/world/streets.d.ts

@@ -0,0 +1,80 @@
+import type { RoadEnvironmentDescriptor } from "./features.js";
+import { type RoadPoint } from "./roads.js";
+/**
+ * Offset a centerline sideways by a signed distance along its local perpendicular — the
+ * building block for lanes, curb lines, and sidewalk paths. Positive offsets fall on the
+ * left of the direction of travel, negative on the right.
+ */
+export declare function offsetPath(path: readonly RoadPoint[], offset: number): readonly RoadPoint[];
+/** A directed lane derived from a road: an offset centerline plus its direction of travel. */
+export interface StreetLane {
+    /** Lane centerline, ordered in the direction of travel. */
+    path: readonly RoadPoint[];
+    /** "forward" runs with the road's declared path order; "reverse" runs against it. */
+    direction: "forward" | "reverse";
+}
+/**
+ * Two right-hand-traffic lane centerlines for a road — each offset a quarter of the drivable
+ * width from the center and ordered in its direction of travel. Feed a lane's `path` straight
+ * into `nav/pathFollow` for traffic AI, or use its endpoints as directed car spawn points.
+ */
+export declare function laneCenters(road: RoadEnvironmentDescriptor): readonly [StreetLane, StreetLane];
+/** Resolved sidewalk band widths for a road; zero when the road declares no sidewalk. */
+export declare function sidewalkWidthOf(road: RoadEnvironmentDescriptor): number;
+/**
+ * The two sidewalk walking paths of a road — offset polylines running down the middle of each
+ * sidewalk band. Pedestrians spawn and route along these instead of the asphalt.
+ */
+export declare function sidewalkPaths(road: RoadEnvironmentDescriptor): readonly (readonly RoadPoint[])[];
+/** A placement anchor on the curb line: position, outward-facing heading, and which side it sits on. */
+export interface FurnitureSpot {
+    position: RoadPoint;
+    /** Yaw (radians, engine `rotationY` convention) facing away from the road. */
+    heading: number;
+    side: "left" | "right";
+    /** Arc-length distance along the road at this spot. */
+    along: number;
+}
+/** Options for {@link furnitureSpots}. */
+export interface FurnitureSpotOptions {
+    /** Distance between consecutive spots along the road. Default 24. */
+    spacing?: number;
+    /** Which curb lines to populate. Default "both". */
+    sides?: "both" | "left" | "right";
+    /** Alternate sides spot-by-spot instead of mirroring every spot. Default true. */
+    stagger?: boolean;
+    /** Extra outward shift past the curb line (e.g. to center furniture in the sidewalk). Default 0. */
+    outset?: number;
+}
+/**
+ * Evenly spaced street-furniture anchors along a road's curb lines — streetlights, palms, signs,
+ * hydrants, benches. Each spot sits just outside the asphalt (plus `outset`), faces away from
+ * the street, and alternates sides by default so lights stagger like a real avenue. This is the
+ * answer to "where do I put it": furniture is an asset of the street, never a hand-typed coordinate.
+ */
+export declare function furnitureSpots(road: RoadEnvironmentDescriptor, options?: FurnitureSpotOptions): readonly FurnitureSpot[];
+/** Options for {@link parkingSpots}. */
+export interface ParkingSpotOptions {
+    /** Distance between consecutive parked-car anchors. Default 18. */
+    spacing?: number;
+    /** Which side(s) of the street to line with parking. Default "both". */
+    sides?: "both" | "left" | "right";
+}
+/** A curbside parking anchor: position at the road edge and a heading parallel to the street. */
+export interface ParkingSpot {
+    position: RoadPoint;
+    /** Yaw (radians) aligned with the direction of travel on that side (right-hand traffic). */
+    heading: number;
+    side: "left" | "right";
+}
+/**
+ * Curbside parking anchors along a road: hugging the edge of the asphalt, headed parallel to the
+ * street in that side's direction of travel. Spawn parked vehicles here instead of eyeballing
+ * coordinates in the middle of the carriageway.
+ */
+export declare function parkingSpots(road: RoadEnvironmentDescriptor, options?: ParkingSpotOptions): readonly ParkingSpot[];
+/**
+ * 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.
+ */
+export declare function sidewalkPoint(road: RoadEnvironmentDescriptor, side: "left" | "right", fraction: number): RoadPoint | null;

package/dist/world/streets.js

@@ -0,0 +1,144 @@
+import { pathLength } from "./roads.js";
+function normalAt(path, index) {
+    const prev = path[Math.max(0, index - 1)];
+    const next = path[Math.min(path.length - 1, index + 1)];
+    const dx = next[0] - prev[0];
+    const dz = next[1] - prev[1];
+    const length = Math.hypot(dx, dz) || 1;
+    return [-dz / length, dx / length];
+}
+/**
+ * Offset a centerline sideways by a signed distance along its local perpendicular — the
+ * building block for lanes, curb lines, and sidewalk paths. Positive offsets fall on the
+ * left of the direction of travel, negative on the right.
+ */
+export function offsetPath(path, offset) {
+    return path.map((point, index) => {
+        const [nx, nz] = normalAt(path, index);
+        return [point[0] + nx * offset, point[1] + nz * offset];
+    });
+}
+/**
+ * Two right-hand-traffic lane centerlines for a road — each offset a quarter of the drivable
+ * width from the center and ordered in its direction of travel. Feed a lane's `path` straight
+ * into `nav/pathFollow` for traffic AI, or use its endpoints as directed car spawn points.
+ */
+export function laneCenters(road) {
+    const laneOffset = road.width / 4;
+    const forward = offsetPath(road.path, -laneOffset);
+    const reverse = offsetPath(road.path, laneOffset);
+    return [
+        { path: forward, direction: "forward" },
+        { path: [...reverse].reverse(), direction: "reverse" },
+    ];
+}
+/** Resolved sidewalk band widths for a road; zero when the road declares no sidewalk. */
+export function sidewalkWidthOf(road) {
+    return road.sidewalk === false ? 0 : road.sidewalk.width;
+}
+/**
+ * The two sidewalk walking paths of a road — offset polylines running down the middle of each
+ * sidewalk band. Pedestrians spawn and route along these instead of the asphalt.
+ */
+export function sidewalkPaths(road) {
+    const width = sidewalkWidthOf(road);
+    if (width <= 0)
+        return [];
+    const offset = road.width / 2 + width / 2;
+    return [offsetPath(road.path, offset), offsetPath(road.path, -offset)];
+}
+function pointAlong(path, along) {
+    let remaining = along;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const segLength = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        if (remaining <= segLength || i === path.length - 2) {
+            const t = segLength <= 0 ? 0 : Math.min(1, remaining / segLength);
+            const length = segLength || 1;
+            return {
+                point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
+                tangent: [(b[0] - a[0]) / length, (b[1] - a[1]) / length],
+            };
+        }
+        remaining -= segLength;
+    }
+    const first = path[0] ?? [0, 0];
+    return { point: first, tangent: [0, 1] };
+}
+/**
+ * Evenly spaced street-furniture anchors along a road's curb lines — streetlights, palms, signs,
+ * hydrants, benches. Each spot sits just outside the asphalt (plus `outset`), faces away from
+ * the street, and alternates sides by default so lights stagger like a real avenue. This is the
+ * answer to "where do I put it": furniture is an asset of the street, never a hand-typed coordinate.
+ */
+export function furnitureSpots(road, options = {}) {
+    const spacing = options.spacing ?? 24;
+    const sides = options.sides ?? "both";
+    const stagger = options.stagger ?? true;
+    const outset = options.outset ?? 0;
+    if (spacing <= 0)
+        return [];
+    const total = pathLength(road.path);
+    const curbOffset = road.width / 2 + 0.6 + outset;
+    const spots = [];
+    let index = 0;
+    for (let along = spacing / 2; along < total; along += spacing) {
+        const { point, tangent } = pointAlong(road.path, along);
+        const normal = [-tangent[1], tangent[0]];
+        const wanted = sides === "both" ? (stagger ? [index % 2 === 0 ? "left" : "right"] : ["left", "right"]) : [sides];
+        for (const side of wanted) {
+            const sign = side === "left" ? 1 : -1;
+            const position = [point[0] + normal[0] * curbOffset * sign, point[1] + normal[1] * curbOffset * sign];
+            spots.push({
+                position,
+                heading: Math.atan2(normal[0] * sign, normal[1] * sign),
+                side,
+                along,
+            });
+        }
+        index += 1;
+    }
+    return spots;
+}
+/**
+ * Curbside parking anchors along a road: hugging the edge of the asphalt, headed parallel to the
+ * street in that side's direction of travel. Spawn parked vehicles here instead of eyeballing
+ * coordinates in the middle of the carriageway.
+ */
+export function parkingSpots(road, options = {}) {
+    const spacing = options.spacing ?? 18;
+    const sides = options.sides ?? "both";
+    if (spacing <= 0)
+        return [];
+    const total = pathLength(road.path);
+    const edgeOffset = road.width / 2 - 1.2;
+    const spots = [];
+    for (let along = spacing; along < total - spacing / 2; along += spacing) {
+        const { point, tangent } = pointAlong(road.path, along);
+        const normal = [-tangent[1], tangent[0]];
+        const wanted = sides === "both" ? ["left", "right"] : [sides];
+        for (const side of wanted) {
+            const sign = side === "left" ? 1 : -1;
+            const dir = side === "left" ? 1 : -1;
+            spots.push({
+                position: [point[0] + normal[0] * edgeOffset * sign, point[1] + normal[1] * edgeOffset * sign],
+                heading: Math.atan2(tangent[0] * dir, tangent[1] * dir),
+                side,
+            });
+        }
+    }
+    return spots;
+}
+/**
+ * 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.
+ */
+export function sidewalkPoint(road, side, fraction) {
+    const paths = sidewalkPaths(road);
+    const path = side === "left" ? paths[0] : paths[1];
+    if (path === undefined)
+        return null;
+    const along = Math.max(0, Math.min(1, fraction)) * pathLength(path);
+    return pointAlong(path, along).point;
+}

package/dist/world/terrain.d.ts

@@ -1,12 +1,16 @@
-import type { EnvironmentWorldFeature, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, WorldBounds, WorldFeature } from "./features.js";
+import type { BiomeBand, EnvironmentWorldFeature, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, WorldBounds, WorldFeature } from "./features.js";
+/** A surface normal vector at a terrain sample point. */
 export type TerrainNormal = readonly [number, number, number];
+/** A sampleable ground surface: height and normal at any x/z, with optional bounds and water level. */
 export interface TerrainField {
     sampleHeight(x: number, z: number): number;
     sampleNormal(x: number, z: number): TerrainNormal;
     readonly bounds?: WorldBounds;
     readonly waterLevel?: number;
 }
+/** Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed. */
 export declare function valueNoise(x: number, z: number, seed: number): number;
+/** Octave settings for {@link fractalNoise}: frequency, layering, and optional ridged shaping. */
 export interface FractalNoiseConfig {
     seed: number;
     frequency: number;
@@ -15,11 +19,15 @@ export interface FractalNoiseConfig {
     persistence: number;
     ridged: boolean;
 }
+/** Layers `valueNoise` octaves per `config` into a single normalized noise sample. */
 export declare function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number;
 export declare function seedFrom(value: string | number | undefined, fallback: number): number;
+/** Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients. */
 export declare function withNormal(sampleHeight: (x: number, z: number) => number): TerrainField["sampleNormal"];
 export declare const FLAT_FIELD: TerrainField;
+/** A flat, zero-height `TerrainField` for arenas with no elevation. */
 export declare function flatField(): TerrainField;
+/** Configuration for {@link noiseField}: seed, amplitude, and fractal noise shaping. */
 export interface NoiseFieldConfig {
     seed?: string | number;
     amplitude?: number;
@@ -32,6 +40,7 @@ export interface NoiseFieldConfig {
     bounds?: WorldBounds;
     waterLevel?: number;
 }
+/** Builds a `TerrainField` whose height is fractal noise shaped by `config`. */
 export declare function noiseField(config?: NoiseFieldConfig): TerrainField;
 export interface RollingFieldConfig {
     seed?: string | number;
@@ -45,8 +54,11 @@ export interface ArenaFieldConfig {
     bounds?: WorldBounds;
 }
 export declare const ARENA_WATER_LEVEL = -0.9;
+/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas. */
 export declare function arenaField(config?: ArenaFieldConfig): TerrainField;
 export declare function groundFieldFor(world?: WorldFeature): TerrainField;
+/** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers. */
+export declare function hasEnvironmentTerrain(world: WorldFeature | undefined): boolean;
 /** Ground height between islands when no base terrain exists — deep enough to read as a fall into the void, finite so physics stays sane. */
 export declare const ISLAND_VOID_HEIGHT = -256;
 /**
@@ -77,13 +89,26 @@ export interface TerrainPalette {
 }
 export declare const DEFAULT_TERRAIN_MATERIAL: TerrainMaterial;
 export declare const TERRAIN_MATERIAL_PALETTES: Record<TerrainMaterial, TerrainPalette>;
+/** A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes. */
+export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel">> & {
+    waterLevel: number;
+};
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level. */
+export declare function resolveTerrainDetail(config: TerrainDetailConfig, terrainWaterLevel?: number): ResolvedTerrainDetail;
 export declare function resolveTerrainPalette(descriptor?: Pick<TerrainEnvironmentConfig, "material" | "colors">): TerrainPalette;
 /**
- * Per-position palette sampler over the descriptor's base `material`/`colors` plus its
- * `materialRegions` — the multi-biome coloring seam. Regions paint fully inside `radius`
- * and blend back to the surrounding palette across `falloff`; later regions win overlaps.
+ * 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 declare function createBiomeBandSampler(bands: readonly BiomeBand[], fallback: TerrainPalette): (z: number) => TerrainPalette;
+/**
+ * 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.
  */
-export declare function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions">): (x: number, z: number) => TerrainPalette;
+export declare function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions" | "biomeBands">): (x: number, z: number) => TerrainPalette;
 export interface HeightMapFieldConfig {
     columns: number;
     rows: number;
@@ -94,6 +119,7 @@ export interface HeightMapFieldConfig {
     waterLevel?: number;
 }
 export declare function heightMapField(config: HeightMapFieldConfig): TerrainField;
+/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks. */
 export declare function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField;
 /** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`. */
 export declare function snapToGround(field: TerrainField, position: readonly [number, number, number], offset?: number): [number, number, number];
@@ -109,6 +135,7 @@ export interface GroundSnapEntityStore {
 /** Ground-snaps an already-spawned entity in place; returns false when `id` is unknown. */
 export declare function snapEntityToGround(entities: GroundSnapEntityStore, id: string, field: TerrainField, offset?: number): boolean;
 export declare const DEFAULT_MAX_WALK_SLOPE = 0.6;
+/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`. */
 export declare function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope?: number): {
     stepX: number;
     stepZ: number;