@jgengine/core 0.10.0 → 0.12.0

package/dist/world/terrain.d.ts

@@ -1,4 +1,7 @@
-import type { BiomeBand, EnvironmentWorldFeature, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, WorldBounds, WorldFeature } from "./features.js";
+import type { BiomeBand, EnvironmentWorldFeature, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, TerrainMaterialMaps, WorldBounds, WorldFeature } from "./features.js";
+import type { AvoidZone } from "./geometry.js";
+import { type TerrainPathProfile } from "./pathTerrain.js";
+import type { TerraformSnapshot } from "./terraform.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. */
@@ -8,7 +11,9 @@ export interface TerrainField {
     readonly bounds?: WorldBounds;
     readonly waterLevel?: number;
 }
-/** 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 declare function valueNoise(x: number, z: number, seed: number): number;
 /** Octave settings for {@link fractalNoise}: frequency, layering, and optional ridged shaping. */
 export interface FractalNoiseConfig {
@@ -19,13 +24,20 @@ export interface FractalNoiseConfig {
     persistence: number;
     ridged: boolean;
 }
-/** Layers `valueNoise` octaves per `config` into a single normalized noise sample. */
+/** Layers `valueNoise` octaves per `config` into a single normalized noise sample.
+ * @internal
+ */
 export declare function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number;
+/** @internal */
 export declare function seedFrom(value: string | number | undefined, fallback: number): number;
-/** 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 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. */
+/** A flat, zero-height `TerrainField` for arenas with no elevation.
+ * @internal
+ */
 export declare function flatField(): TerrainField;
 /** Configuration for {@link noiseField}: seed, amplitude, and fractal noise shaping. */
 export interface NoiseFieldConfig {
@@ -40,7 +52,9 @@ export interface NoiseFieldConfig {
     bounds?: WorldBounds;
     waterLevel?: number;
 }
-/** Builds a `TerrainField` whose height is fractal noise shaped by `config`. */
+/** Builds a `TerrainField` whose height is fractal noise shaped by `config`.
+ * @internal
+ */
 export declare function noiseField(config?: NoiseFieldConfig): TerrainField;
 export interface RollingFieldConfig {
     seed?: string | number;
@@ -48,16 +62,22 @@ export interface RollingFieldConfig {
     frequency?: number;
     bounds?: WorldBounds;
 }
+/** @internal */
 export declare function rollingField(config?: RollingFieldConfig): TerrainField;
 export interface ArenaFieldConfig {
     seed?: string | number;
     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. */
+/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas.
+ * @internal
+ */
 export declare function arenaField(config?: ArenaFieldConfig): TerrainField;
+/** @internal */
 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. */
+/** 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 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;
@@ -65,9 +85,28 @@ export declare const ISLAND_VOID_HEIGHT = -256;
  * 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 declare function composeIslandFields(base: TerrainField | null, islands: readonly TerrainIslandDescriptor[], voidHeight?: number): TerrainField;
-/** The full ground field for an environment world: base `terrain` composed with any `islands`. */
+/**
+ * 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 declare function sculptedField(base: TerrainField, snapshot: TerraformSnapshot): TerrainField;
+/**
+ * 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 declare function flattenFieldAround(base: TerrainField, zones: readonly AvoidZone[]): TerrainField;
+/**
+ * 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 declare function resolveEnvironmentField(feature: EnvironmentWorldFeature): TerrainField;
 export interface TerrainSlopeSample {
     /** Unit XZ direction pointing downhill; `[0, 0]` on level ground. */
@@ -75,13 +114,61 @@ export interface TerrainSlopeSample {
     /** Rise over run (tan of the slope angle); `0` on level ground. */
     steepness: number;
 }
-/** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6). */
+/** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6).
+ * @internal
+ */
 export declare function sampleSlope(field: TerrainField, x: number, z: number): TerrainSlopeSample;
 /**
  * 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 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;
@@ -89,25 +176,65 @@ export interface TerrainPalette {
 }
 export declare const DEFAULT_TERRAIN_MATERIAL: TerrainMaterial;
 export declare const TERRAIN_MATERIAL_PALETTES: Record<TerrainMaterial, TerrainPalette>;
+/** A resolved {@link TerrainDetailMaterialConfig} — `repeat`/`strength` filled with defaults, `maps` passed through. */
+export interface ResolvedTerrainDetailMaterial {
+    maps: TerrainMaterialMaps;
+    repeat: number;
+    strength: number;
+}
 /** 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">> & {
+export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material">> & {
     waterLevel: number;
+    material?: ResolvedTerrainDetailMaterial;
 };
-/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level. */
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
+ * @internal
+ */
 export declare function resolveTerrainDetail(config: TerrainDetailConfig, terrainWaterLevel?: number): ResolvedTerrainDetail;
+/** @internal */
 export declare function resolveTerrainPalette(descriptor?: Pick<TerrainEnvironmentConfig, "material" | "colors">): TerrainPalette;
 /**
  * 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 declare function createBiomeBandSampler(bands: readonly BiomeBand[], fallback: TerrainPalette): (z: number) => TerrainPalette;
+/** A concrete fog look — the shape `createBiomeFogSampler` resolves per z from a band's `fog` over the base fog. */
+export interface BiomeFogValue {
+    color: string;
+    near: number;
+    far: number;
+    density: number;
+}
+/**
+ * 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 declare function createBiomeFogSampler(bands: readonly BiomeBand[], fallback: BiomeFogValue): (z: number) => BiomeFogValue;
+/** A concrete sky look — the shape `createBiomeSkySampler` resolves per z from a band's `sky` over the base sky. */
+export interface BiomeSkyValue {
+    horizonColor: string;
+    zenithColor: string;
+    sunIntensity: number;
+    ambientIntensity: number;
+}
+/**
+ * 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 declare function createBiomeSkySampler(bands: readonly BiomeBand[], fallback: BiomeSkyValue): (z: number) => BiomeSkyValue;
 /**
  * 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 declare function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions" | "biomeBands">): (x: number, z: number) => TerrainPalette;
 export interface HeightMapFieldConfig {
     columns: number;
@@ -118,10 +245,23 @@ export interface HeightMapFieldConfig {
     baseHeight?: number;
     waterLevel?: number;
 }
+/** @internal */
 export declare function heightMapField(config: HeightMapFieldConfig): TerrainField;
-/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks. */
+/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks.
+ * @internal
+ */
 export declare function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField;
-/** 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 declare function applyPathProfiles(field: TerrainField, profiles: readonly TerrainPathProfile[]): TerrainField;
+/** Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`.
+ * @internal
+ */
 export declare function snapToGround(field: TerrainField, position: readonly [number, number, number], offset?: number): [number, number, number];
 export interface GroundSnapTarget {
     position: readonly [number, number, number];
@@ -132,10 +272,14 @@ export interface GroundSnapEntityStore {
         position?: readonly [number, number, number];
     }): boolean;
 }
-/** 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 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`. */
+/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`.
+ * @internal
+ */
 export declare function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope?: number): {
     stepX: number;
     stepZ: number;