@threenative/terrain 0.0.0-stage → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+export { L as LayerPatch, O as OperationOptions, P as PatchCommand, T as Terrain, a as TerrainEvaluator } from './terrain-gPnkCU6S.js';
+import { M as MaterialId, a as IMask, i as ISampledGrid, O as OperationType, d as ITerrainDocument, I as ITerrainState, j as IBakeMeshOptions, g as IBakedMesh, k as IBakeTerrainOptions, l as IBakedTerrain, h as IPlacementOverride, m as IDecodeHeightPngOptions, n as IDecodeRaw16Options, o as IHeightRange, p as IRaw16Options, q as IExportFile, E as ExportKind, r as IExportArchive } from './types-Ant8-Axc.js';
+export { s as IBiomeParams, t as IBrushParams, u as IClearParams, f as ICopyRegionOptions, v as IDecodedHeightPng, w as IErodeParams, x as IErosionMaps, e as IEvaluateOptions, y as IFlattenParams, z as IGradeParams, A as IGrid, B as IHeightData, C as IHeightPngMetadata, D as IHeightmapParams, F as ILayer, G as IMaterialRule, H as IMaterialsParams, J as INoiseParams, K as IPaintParams, N as IPasteParams, P as IPlacement, Q as IRampParams, R as IRiver, S as IRiverParams, T as IRoadParams, U as IScatterClear, V as IScatterParams, W as IScatterRule, X as ISculptParams, Y as ISmoothParams, Z as ISplatPng, _ as IStampParams, $ as ITerraceParams, c as ITerrainConfig, a0 as ITerrainInspection, a1 as IWaterBody, a2 as IWaterParams, a3 as IWaterRule, L as Layer, b as LayerParams, a4 as MaskSampler, a5 as MaskType, a6 as SplinePoint } from './types-Ant8-Axc.js';
+
+/** The eight splat channels, in channel order. Index 0 is the default base channel. */
+declare const MATERIAL_IDS: readonly MaterialId[];
+/**
+ * Serializable mask builders. A mask is data, never a callback, so a recipe round-trips through
+ * JSON and an editor can rewrite one field without executing anything.
+ */
+declare const Mask: Readonly<{
+    all: () => IMask;
+    none: () => IMask;
+    circle: (at: readonly [number, number], radius: number, softness?: number) => IMask;
+    rectangle: (at: readonly [number, number], size: number | readonly [number, number], rotation?: number, softness?: number) => IMask;
+    height: (min?: number, max?: number, fade?: number) => IMask;
+    slope: (min?: number, max?: number, fade?: number) => IMask;
+    noise: (scale?: number, threshold?: number, seed?: number, fade?: number) => IMask;
+    biome: (name: string) => IMask;
+    material: (name: MaterialId) => IMask;
+    and: (...masks: IMask[]) => IMask;
+    or: (...masks: IMask[]) => IMask;
+    not: (mask: IMask) => IMask;
+}>;
+
+/** Bilinear world-space height query. It is not the rendered or collidable triangle surface. */
+/**
+ * Bilinear query of canonical height samples; triangle sampling is a separate contract.
+ * @requires npm i @threenative/terrain
+ * @situation query an authored heightfield at world coordinates
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
+ */
+declare const sampleHeight: (grid: ISampledGrid, x: number, z: number) => number;
+/** `[dh/dx, dh/dz]` at a world position. */
+/**
+ * World-space height gradient from the canonical samples.
+ * @requires npm i @threenative/terrain
+ * @situation measure an authored terrain gradient in metres
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
+ */
+declare function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number];
+/** Slope in degrees at one sample index. */
+/**
+ * Slope in degrees at a heightfield sample.
+ * @requires npm i @threenative/terrain
+ * @situation measure terrain slope for authoring diagnostics
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);
+ */
+declare function slopeAtIndex(grid: ISampledGrid, i: number): number;
+/**
+ * A slope, in degrees, that the given share of this terrain's interior vertices lie at or below.
+ *
+ * Placement rules keyed to fixed degrees break when a world is rebaked smoother or rougher: an
+ * outcrop rule of "over 30 degrees" placed nothing on a forest whose 98th percentile is 22. Asking
+ * the terrain for its own steepest share keeps the rule meaning the same thing on every world.
+ *
+ * @requires npm i @threenative/terrain
+ * @situation place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees
+ * @constraint interior vertices only (edges have one-sided differences); quantile must be in [0, 1]
+ * @example const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);
+ */
+declare function slopeQuantile(grid: ISampledGrid, quantile: number): number;
+/**
+ * Samples a spline: Catmull-Rom horizontally to avoid corners, linear vertically to avoid
+ * overshoot. `smooth: false` walks the polyline.
+ */
+/**
+ * Recovered horizontal Catmull–Rom and vertically linear profile sampler.
+ * @requires npm i @threenative/terrain
+ * @situation sample a road or river profile without vertical overshoot
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
+ */
+declare function splinePoints(points: readonly (readonly [number, number, number])[], step?: number, smooth?: boolean): [number, number, number][];
+
+/** Valid grid resolutions: vertices per side, not cells. */
+declare const RESOLUTIONS: readonly number[];
+/** The parameters each operation accepts. Anything else is rejected before the state changes. */
+declare const PARAMS: Readonly<Record<OperationType, readonly string[]>>;
+/** Validates a whole recipe: version, config, layer count and unique layer IDs. */
+/**
+ * Validates the recovered recipe schema, operation allow-lists and numeric bounds.
+ * @requires npm i @threenative/terrain
+ * @situation validate a terrain document before accepting an authoring write
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example validateDocument(new Terrain({ resolution: 17 }).toJSON());
+ */
+declare function validateDocument(doc: ITerrainDocument): void;
+
+/**
+ * Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
+ * @requires npm i @threenative/terrain
+ * @situation bake an authored terrain into portable indexed mesh arrays
+ * @constraint no material is chosen; vertex colours exist only with a caller-supplied palette
+ * @example const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());
+ * @override step, chunk bounds, skirtDepth and palette belong to the caller
+ */
+declare function bakeMesh(state: ITerrainState, { step, x, z, cells, skirtDepth, palette, }?: IBakeMeshOptions): IBakedMesh;
+/**
+ * Bakes finite LOD chunks, the same collision samples and resolved placements.
+ * @requires npm i @threenative/terrain
+ * @situation prepare terrain arrays and collision before a game starts
+ * @constraint collision origin is the southwest corner; engine Heightfield origin is its centre
+ * @example const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });
+ * @override chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices
+ */
+declare function bakeTerrain(state: ITerrainState, { chunkCells, lodSteps, skirtDepth, palette, }?: IBakeTerrainOptions): IBakedTerrain;
+
+/**
+ * Validate and clone stable-key placement transforms before saving or previewing them.
+ * @requires npm i -D @threenative/terrain
+ * @situation validate finite positive manual prop transforms before a terrain authoring transaction
+ * @constraint grounding defaults on only when omitted; position and scale have three components and quaternion is unit length
+ * @example const transforms = validatePlacementOverrides(document.placementOverrides);
+ * @override grounding=false preserves authored Y and keeps clearance observable
+ */
+declare function validatePlacementOverrides(value?: unknown): Record<string, IPlacementOverride>;
+/**
+ * Attach manual transforms to raw evaluated candidates and report orphan keys.
+ * @requires npm i -D @threenative/terrain
+ * @situation retain manual prop transforms across terrain scatter re-evaluation
+ * @constraint headless authoring; game applies transforms against its model bounds and actual terrain surface
+ * @example const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
+ * @override transform.grounding=false preserves requested Y while the game still measures clearance
+ */
+declare function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState;
+
+/**
+ * Encodes finite metre elevations as an explicit-range RAW16 buffer.
+ * @requires npm i @threenative/terrain
+ * @situation export terrain heights with a numerical range sidecar
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });
+ */
+declare function encodeRAW16(values: ArrayLike<number> & Iterable<number>, options?: IRaw16Options): Uint8Array<ArrayBuffer>;
+/**
+ * Validates dimensions and range before decoding numerical height samples.
+ * @requires npm i @threenative/terrain
+ * @situation import a RAW16 terrain height buffer with explicit dimensions
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });
+ */
+declare function decodeRAW16(input: Uint8Array | ArrayBuffer, { width, height, min, max, littleEndian }: IDecodeRaw16Options): {
+    width: number;
+    height: number;
+    values: Float32Array<ArrayBuffer>;
+    min: number;
+    max: number;
+};
+/**
+ * Encodes numerical grayscale PNG16 with embedded elevation range.
+ * @requires npm i @threenative/terrain
+ * @situation export a terrain heightmap without an eight-bit colour conversion
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());
+ */
+declare function encodeHeightPNG(state: ITerrainState, options?: Partial<IHeightRange>): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Encodes the eight linear material-weight channels as two RGBA images.
+ * @requires npm i @threenative/terrain
+ * @situation export terrain splat weights as linear data
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());
+ */
+declare function encodeSplatPNGs(state: ITerrainState): Promise<{
+    channels: MaterialId[];
+    bytes: Uint8Array<ArrayBuffer>;
+}[]>;
+/**
+ * CRC-checked bounded non-interlaced grayscale PNG height decoder.
+ * @requires npm i @threenative/terrain
+ * @situation import numerical PNG8 or PNG16 terrain elevations
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
+ */
+declare function decodeHeightPNG(input: Uint8Array | ArrayBuffer, options?: IDecodeHeightPngOptions): Promise<{
+    width: number;
+    height: number;
+    values: Float32Array<ArrayBuffer>;
+    min: number;
+    max: number;
+    bitDepth: number;
+    hasEmbeddedRange: boolean;
+}>;
+/** Engine-independent GLB 2.0: static colored terrain geometry, no hidden external resources. */
+/**
+ * Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.
+ * @requires npm i @threenative/terrain
+ * @situation export baked terrain geometry without engine extensions
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
+ */
+declare function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]): Uint8Array<ArrayBuffer>;
+
+/** Deterministic ZIP (store method). No compression library or server required. */
+/**
+ * Deterministic store-method ZIP with safe unique relative filenames.
+ * @requires npm i @threenative/terrain
+ * @situation archive derived terrain files without another dependency
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
+ */
+declare function encodeZIP(files: readonly IExportFile[]): Uint8Array<ArrayBuffer>;
+/**
+ * Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
+ * @requires npm i @threenative/terrain
+ * @situation export a terrain recipe and its numerical runtime data
+ * @constraint authoring data only; the game owns appearance, physics and rendering
+ * @example const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
+ */
+declare function makeExport(state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind): Promise<IExportArchive>;
+
+/** One streamed asset: its LOD0 model, its authored bounds and the levels it swaps to. */
+interface IWorldPackageAsset {
+    readonly glb: string;
+    readonly bounds: {
+        readonly min: readonly [number, number, number];
+        readonly max: readonly [number, number, number];
+    };
+    readonly lods?: readonly {
+        readonly glb: string;
+        readonly distance: number;
+    }[];
+    readonly maxDistance?: number;
+}
+/** One cell's contiguous run of placement records, eight float32 values each. */
+interface IWorldPackageRun {
+    readonly asset: string;
+    /** Record offset into the placement buffer, not a byte offset. */
+    readonly offset: number;
+    readonly count: number;
+}
+/** The `world.json` contract, declared here so this addon needs no `@threenative/core` import. */
+interface IWorldPackageManifest {
+    readonly version: 1;
+    readonly extent: {
+        readonly minX: number;
+        readonly minZ: number;
+        readonly sizeX: number;
+        readonly sizeZ: number;
+    };
+    readonly cellSize: number;
+    readonly terrain: {
+        readonly heightmap: string;
+        readonly columns: number;
+        readonly rows: number;
+        readonly spacing: number;
+        readonly heightMin: number;
+        readonly heightMax: number;
+        readonly layers?: Readonly<Record<string, string>>;
+    };
+    readonly assets: Readonly<Record<string, IWorldPackageAsset>>;
+    readonly placements: string;
+    readonly cells: readonly {
+        readonly x: number;
+        readonly z: number;
+        readonly runs: readonly IWorldPackageRun[];
+    }[];
+}
+/** The splat layout to copy into a terrain table: eight material masks in two RGBA8 planes. */
+interface IWorldPackageSplat {
+    readonly size: number;
+    readonly planes: number;
+    readonly masks: Readonly<Record<string, readonly [number, "r" | "g" | "b" | "a"]>>;
+}
+interface IBakeWorldPackageOptions {
+    /** Every asset any instance may reference. An instance outside this set fails the bake. */
+    readonly assets: Readonly<Record<string, IWorldPackageAsset>>;
+    /** Metres per streamed cell. Defaults to 64. */
+    readonly cellSize?: number;
+    /** Extra `terrain.layers` entries, e.g. `{ table: "terrain-table.json" }`. */
+    readonly layers?: Readonly<Record<string, string>>;
+    readonly names?: {
+        readonly heightmap?: string;
+        readonly placements?: string;
+        readonly splat?: string;
+    };
+}
+interface IBakedWorldPackage {
+    readonly manifest: IWorldPackageManifest;
+    readonly splat: IWorldPackageSplat;
+    /** The three binary files, keyed by the manifest names that point at them. */
+    readonly files: Readonly<Record<string, Uint8Array>>;
+}
+/**
+ * Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16
+ * heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square
+ * cells that stream them. The encodings and row orders are the ones the Blender recipe
+ * `export_world.py` writes, so one runtime streams both without a second reader.
+ *
+ * @requires npm i -D @threenative/terrain
+ * @situation hand an evaluated Strata terrain to a game without a Blender round trip
+ * @constraint headless authoring; no three, no DOM, and nothing here decides how the world looks
+ * @example const { manifest, files } = bakeWorldPackage(state, { assets });
+ * @override every asset path, bound, LOD distance and cell size comes from the caller's options
+ */
+declare function bakeWorldPackage(state: ITerrainState, options: IBakeWorldPackageOptions): IBakedWorldPackage;
+
+/**
+ * A spatial index for water proximity: river segments, river stations and lake shores.
+ *
+ * Every caller that asks "is this point near water?" over a whole heightfield or a scatter pass
+ * otherwise scans every segment per point. In the Strata preview that cost 3.4 s (scatter) and
+ * 2.3 s (ground curvature) of a synchronous scene entry on a 612-station river (PRD-466, PRD-541).
+ * Each segment is registered in every grid cell its bounding box covers once grown by its own reach,
+ * so `nearby` returns a superset of the segments within reach of the point. The caller keeps its own
+ * exact distance and level test on that short list.
+ */
+interface IWaterSegment<T> {
+    /** One end, `[x, z]` in world metres. A station or a lake centre passes the same point twice. */
+    readonly a: readonly [number, number];
+    readonly b: readonly [number, number];
+    /** How far from the segment the caller's test can still answer true, in metres. */
+    readonly reach: number;
+    readonly data: T;
+}
+interface ISegmentIndex<T> {
+    /** Every segment whose reach may cover `(x, z)`. Never misses one; may include farther ones. */
+    nearby(x: number, z: number): readonly T[];
+}
+/**
+ * Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
+ *
+ * @requires npm i @threenative/terrain
+ * @situation test scatter candidates or terrain vertices against rivers and lakes without scanning every segment
+ * @situation find which river stations can reach a heightfield vertex when baking a wet margin
+ * @constraint returns candidates only; the caller applies its own exact distance and level test
+ * @example const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);
+ */
+declare function createSegmentIndex<T>(segments: readonly IWaterSegment<T>[], cellSize: number): ISegmentIndex<T>;
+
+export { ExportKind, IBakeMeshOptions, IBakeTerrainOptions, IBakedMesh, IBakedTerrain, IDecodeHeightPngOptions, IDecodeRaw16Options, IExportArchive, IExportFile, IHeightRange, IMask, IPlacementOverride, IRaw16Options, ISampledGrid, type ISegmentIndex, ITerrainDocument, ITerrainState, type IWaterSegment, MATERIAL_IDS, Mask, MaterialId, OperationType, PARAMS, RESOLUTIONS, applyPlacementOverrides, bakeMesh, bakeTerrain, bakeWorldPackage, createSegmentIndex, decodeHeightPNG, decodeRAW16, encodeGLB, encodeHeightPNG, encodeRAW16, encodeSplatPNGs, encodeZIP, gradientAt, makeExport, sampleHeight, slopeAtIndex, slopeQuantile, splinePoints, validateDocument, validatePlacementOverrides };