@jgengine/core 0.9.0 → 0.11.0

package/dist/world/terrain.d.ts

@@ -1,12 +1,21 @@
-import type { EnvironmentWorldFeature, 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. */
 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.
+ * @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 {
     seed: number;
     frequency: number;
@@ -15,11 +24,22 @@ export interface FractalNoiseConfig {
     persistence: number;
     ridged: boolean;
 }
+/** 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.
+ * @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.
+ * @internal
+ */
 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 +52,9 @@ export interface NoiseFieldConfig {
     bounds?: WorldBounds;
     waterLevel?: number;
 }
+/** 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;
@@ -39,23 +62,51 @@ 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.
+ * @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.
+ * @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;
 /**
  * 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. */
@@ -63,12 +114,15 @@ 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];
 export interface TerrainPalette {
     low: string;
@@ -77,13 +131,66 @@ 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" | "material">> & {
+    waterLevel: number;
+    material?: ResolvedTerrainDetailMaterial;
+};
+/** 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-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.
- */
-export declare function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions">): (x: number, z: number) => 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;
     rows: number;
@@ -93,9 +200,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.
+ * @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];
@@ -106,9 +227,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`.
+ * @internal
+ */
 export declare function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope?: number): {
     stepX: number;
     stepZ: number;