Module terrain

A CDLOD heightmap terrain. By default a fully-resident finite slab that's easy to frame in the editor; set bounded to false with a large worldExtent for an "infinite" world that streams pages around the camera.

A finite water body on a terrain. Defaults are calm freshwater (greener scatter, visible shallow beds, foam off).

Draws the terrain into reflection-probe cube faces. Create once per (context, system) and register draw via ReflectionProbeCapturePass.addExternalDraw. Owns one small uniform per (probe slot, face) — the capture pass encodes all faces before the queue submits, so a shared buffer would be overwritten by the last face.

A normalized [0, 1] height field over a world-space rect, sampled bilinearly. Row-major width × height samples; texel (0, 0) sits at (originX, originZ) and texel (width-1, height-1) at (originX + extentX, originZ + extentZ) — the same mapping the page-gen shader uses when it samples the heightmap texture with a clamping sampler.

Reconciles the TerrainSystem against the authored Terrain each frame, drives its per-frame update, runs the LOD compute, and publishes the patch + indirect-args handles for the terrain shadow + G-Buffer features. Owns the shared system's lifetime (destroys it on engine teardown).

Appends terrain depth to every cascade of the directional shadow map produced by the engine's ShadowFeature. shadow:cascades is set during ShadowFeature's update() but the engine wipes frame.extras between update and addPasses, so it is cached in our own update(). Skips quietly when there is no shadow map, no cascades, or no terrain.

Loads the terrain into the deferred G-Buffer. When a prior geometry feature has already written it (mesh renderers, skinned models), this loads on top so terrain and meshes share one G-Buffer; otherwise it clears a fresh one. Inert when there is no terrain.

Grows the grass detail layer over the authored terrain: a deterministic scatterer seats blades on the CPU height mirror with density from the masked splat weights, and the engine's GrassPass draws + shadow-casts them. Inert until the Terrain enables grass and its height data is loaded.

Scatters trees over the authored terrain (jittered spacing grid, density from the masked splat weights, slope-culled) and contributes them as instanced batches to the engine's GeometryFeature (G-Buffer) and ShadowFeature (all cascades) via their additive provider APIs.

Maps the height field's texel grid onto world space (XZ plane).

Inclusive texel rect (x0/y0..x1/y1) touched by an edit.

One brush application (a pointer-move step of a stroke).

An editable height field bound to its GPU texture.

An editable RGBA splat weight map bound to its GPU texture.

An editable hole mask (one byte per texel, ≥128 = hole) bound to its r8unorm GPU texture.

An editable painted color/tint map (RGBA; rgb = overlay multiplier centered at 0.5, a = paint opacity) bound to its GPU texture.

Authored grass settings (mirrors the Terrain component's grass fields).

One region's texel rect (tile texels, 0..regionTexels inclusive).

One region's undo payload: the rect plus before/after sample blocks.

Maps a row-major grid onto world space (min corner + span).

Per-layer style knobs mirrored into the shader's LayerStyle UBO.

Maps authored splat weight textures onto world space.

CPU copy of the hole mask (one byte per texel, row-major; ≥128 = hole).

Maps the hole mask texture onto world space.

Maps a control map (see packControlTexel) onto world space.

CPU copy of the color/tint map (RGBA bytes, row-major).

Maps the color/tint map texture onto world space.

Maps the heightmap texture passed to TerrainSystem.setHeightmap onto world space.

Authored tree settings (mirrors the Terrain component's tree fields).

One packed record set: instance data + count.

Quality preset choices exposed by Terrain.

One authored PBR layer: texture asset refs + style knobs. Refs are opaque keys resolved by Terrain.resolveAssetBytes (asset guids in the editor, URLs elsewhere).

Height-changing brush operations.

World-space height query: world Y at (x, z), or null off the field.

How the carve moves ground toward the spline profile.

World size of one scatter tile.

Invalid layer marker in the region table (mirrors the VT page table).

Maximum PBR layers the shader supports (fixed-size uniform array + two RGBA splat weight textures = 8 channels).

World size of one scatter tile (holds many spacing cells).

Fetch and decode a grayscale heightmap image into an r16float texture. The R channel of the decoded image is read as height. Throws if the fetch or decode fails (so callers can fall back to procedural generation).

Decode a grayscale heightmap image from raw bytes (see loadHeightmapTexture for the denoising it applies). Used by hosts whose asset bytes don't come from a fetchable URL (the editor's Content/ pipeline).

Fetch a raw little-endian uint16 height field (e.g. the terrain stitcher's .r16 output) into an r16float texture + normalized CPU field. No denoising is applied — 16-bit sources don't have the 8-bit/JPG noise the image loader blurs away. Square fields can omit resolution (inferred from the byte length).

Decode a raw little-endian uint16 height field from bytes (the fetch-free core of loadHeightmapRaw16).

Upload a normalized [0, 1] Float32 height field as an r16float texture. data must be res * res row-major samples.

Fetch and decode a splat weight image (PNG/WebP) into an rgba8unorm texture. Channels are read verbatim — author the image with linear channel values, not color-managed ones.

Decode a splat weight image from raw bytes (the fetch-free core of loadSplatmapTexture).

Upload raw RGBA weight bytes (row-major width × height × 4) as an rgba8unorm splat texture.

Register the terrain component factory (idempotent; called on module import).

Union of two texel rects (for accumulating a stroke's total dirty area).

Register the three discovery-driven terrain features on an engine, ordered correctly against the standard deferred features. Call this once per engine that should be able to render an authored Terrain — after the engine's shadow / geometry / lighting features exist, so the anchors resolve (the editor calls it at the end of its preset for both the Scene and Game engines). The features stay inert until the scene contains an enabled Terrain.

March a ray against a height query. step is the coarse march step in world units — use about one heightmap texel; the hit is refined by bisection to ~1/64 step. Points where the query returns null are treated as "no ground" (the ray passes over the void beyond the field).

Pack a (possibly negative) region grid coordinate into a map key.

The square window of regions a camera position wants resident.

Carve (or flatten) the spline profile into a normalized height grid, in place. Returns the touched texel rect (undo snapshots + flush), or null when the spline misses the grid.

Paint a splat layer along the spline footprint (channel + banks) with the coverage as the blend weight, renormalizing the other layers down — the "dress the banks" half of a carve. Mutates the arrays in place; returns the touched SPLAT texel rect or null.

Pack one control-map texel (splat mode 3). Two layer ids + blend give two texture taps per texel regardless of palette size; rotation/scale detile the planar sampling frame per texel; autoshader hands the texel to the procedural height/slope rule.

Decode packControlTexel's word (CPU mirrors + tests).

out = a × b (column-major 4×4). Allocates when out is omitted.

Compose a column-major TRS matrix from glTF node components.

Build the shared low-poly pine mesh (call once per device; ~60 verts).

Far-LOD stand-in: a single canopy cone + trunk stub (~14 verts). Used for distant trees regardless of the near mesh, so the far field stays a few triangles per tree until baked impostors arrive.

Register the water-body component factory (idempotent; called on module import).