@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/ecs/terrain/ecs/Terrain.js

@@ -1,790 +1,790 @@
-import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
-import { array_copy } from "../../../../core/collection/array/array_copy.js";
-import { assert } from "../../../../core/assert.js";
-import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
-import { IllegalStateException } from "../../../../core/fsm/exceptions/IllegalStateException.js";
-import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";
-import Vector2 from '../../../../core/geom/Vector2.js';
-import { Sampler2D } from '../../../graphics/texture/sampler/Sampler2D.js';
-import { WHITE_PIXEL_DATA_URL } from "../../../graphics/WHITE_PIXEL_DATA_URL.js";
-import { TerrainOverlay } from '../overlay/TerrainOverlay.js';
-
-import Clouds from '../TerrainClouds.js';
-import { TerrainPreview } from "../TerrainPreview.js";
-
-import TerrainTileManager from '../tiles/TerrainTileManager.js';
-import { buildLightTexture } from "./BuildLightTexture.js";
-import { GridTransformKind } from "./GridTransformKind.js";
-import { TerrainLayers } from "./layers/TerrainLayers.js";
-import { makeTerrainWorkerProxy } from "./makeTerrainWorkerProxy.js";
-import { OffsetScaleTransform2D } from "./OffsetScaleTransform2D.js";
-import { SplatMapping } from "./splat/SplatMapping.js";
-import { TerrainFlags } from "./TerrainFlags.js";
-
-let idCounter = 0;
-
-/**
- * Terrain is split into equal sized square patches
- * Dimensions of single patch in width and height
- * NOTE: edges of the terrain will typically result in patches smaller than this, so this is upper bound.
- * A fine {@link Terrain#resolution} lowers it further, see {@link TerrainTileManager#maxTileVertexCount}.
- * @type {number}
- */
-const TILE_SIZE = 32;
-
-class Terrain {
-    /**
-     * @readonly
-     * @type {number}
-     */
-    id = idCounter++;
-
-    /**
-     * @private
-     * @type {number|TerrainFlags}
-     */
-    flags = 0;
-
-    /**
-     *
-     * @type {number}
-     */
-    gridScale = 1;
-
-    /**
-     * Transform from grid coordinate system to world coordinate system
-     * @type {OffsetScaleTransform2D}
-     */
-    gridTransform = new OffsetScaleTransform2D();
-
-    /**
-     *
-     * @type {number}
-     */
-    gridTransformKind = GridTransformKind.Direct;
-
-    /**
-     * Number of geometric subdivisions per single terrain tile
-     * @example if value is set to 4, each tile will be split into 4x4 quads
-     * @type {number}
-     */
-    resolution = 4;
-
-    /**
-     * @readonly
-     * @type {Vector2}
-     */
-    size = new Vector2(0, 0);
-    /**
-     *
-     * @type {TerrainPreview}
-     */
-    preview = new TerrainPreview();
-    /**
-     * @readonly
-     * @type {SplatMapping}
-     */
-    splat = new SplatMapping();
-
-    /**
-     * @readonly
-     * @type {TerrainLayers}
-     */
-    layers = new TerrainLayers();
-
-    /**
-     * @readonly
-     * @type {WorkerProxy}
-     */
-    __buildWorker = makeTerrainWorkerProxy();
-
-    /**
-     * @readonly
-     * @type {BvhClient}
-     */
-    bvh = new BvhClient();
-
-    /**
-     * @deprecated
-     * @type {number}
-     */
-    heightRange = 0;
-
-    /**
-     * whether or not frustum culling is enabled
-     * @type {boolean}
-     */
-    frustumCulled = true;
-
-    /**
-     *
-     * @type {AssetManager}
-     * @private
-     */
-    __assetManager = null;
-
-    /**
-     * Authored data with no consumer: the lightmap it names was bound as the terrain material's
-     * `aoMap`, and terrain ambient occlusion under Shade is the renderer's own GTAO. Kept because
-     * levels on disk carry it (I-13) and the field is what round-trips them.
-     *
-     * @type {String}
-     */
-    lightMapURL = null;
-
-    constructor() {
-        /**
-         *
-         * @type {Clouds}
-         */
-        this.clouds = new Clouds();
-        this.clouds.enabled = true;
-
-        /**
-         *
-         * @type {Sampler2D}
-         */
-        this.samplerHeight = Sampler2D.float32(1, 1, 1);
-
-        /**
-         * 4x4 transform matrix
-         * @private
-         * @type {Float32Array}
-         */
-        this.__transform_matrix = m4_allocate();
-
-        /**
-         *
-         * @type {TerrainOverlay}
-         */
-        this.overlay = new TerrainOverlay(this.size);
-
-        /**
-         *
-         * @type {TerrainTileManager}
-         * @private
-         */
-        this.__tiles = new TerrainTileManager({
-            buildWorker: this.__buildWorker
-        });
-
-        this.__tiles.maxTileSize.set(TILE_SIZE, TILE_SIZE);
-    }
-
-    /**
-     *
-     * @param {number|TerrainFlags} flag
-     * @returns {void}
-     */
-    setFlag(flag) {
-        this.flags |= flag;
-    }
-
-    /**
-     *
-     * @param {number|TerrainFlags} flag
-     * @returns {void}
-     */
-    clearFlag(flag) {
-        this.flags &= ~flag;
-    }
-
-    /**
-     *
-     * @param {number|TerrainFlags} flag
-     * @param {boolean} value
-     */
-    writeFlag(flag, value) {
-        if (value) {
-            this.setFlag(flag);
-        } else {
-            this.clearFlag(flag);
-        }
-    }
-
-    /**
-     *
-     * @param {number|TerrainFlags} flag
-     * @returns {boolean}
-     */
-    getFlag(flag) {
-        return (this.flags & flag) === flag;
-    }
-
-    /**
-     * Stand the terrain's live services up: the tile build worker starts and the height field is
-     * shipped to it.
-     *
-     * The renderer is not in it. Linking used to bind a three `ShaderMaterial` through the graphics
-     * engine's material manager, which is what made this a renderer entry point; drawing terrain is
-     * `TerrainSystem3`'s, and it reads the component rather than being handed a material by it.
-     */
-    link() {
-
-        if (this.getFlag(TerrainFlags.Linked)) {
-            // already linked
-            return;
-        }
-
-        this.startBuildService();
-
-        this.setFlag(TerrainFlags.Linked);
-    }
-
-    /**
-     * disconnect the component, here all resources are released
-     */
-    unlink() {
-
-        if (!this.getFlag(TerrainFlags.Linked)) {
-            // not linked
-            return;
-        }
-
-        this.stopBuildService();
-
-        this.__tiles.dispose();
-
-        this.bvh.unlink();
-
-        this.clearFlag(TerrainFlags.Linked);
-    }
-
-    dispose() {
-        if (this.getFlag(TerrainFlags.Linked)) {
-            throw new IllegalStateException('component is linked, must be unlinked first');
-        }
-    }
-
-    update(timeDelta) {
-        this.clouds.update(timeDelta);
-    }
-
-    /**
-     * @param {number} x
-     * @param {number} y
-     * @param {function} callback
-     * @param {function} missCallback
-     * @param {function} errorCallback
-     */
-    sampleHeight(x, y, callback, missCallback, errorCallback) {
-        assert.isFunction(callback, 'callback');
-        assert.isFunction(missCallback, 'missCallback');
-        assert.isFunction(errorCallback, 'errorCallback');
-
-        const hit = new SurfacePoint3();
-
-        if (this.raycastVerticalFirstSync(hit, x, y)) {
-            callback(hit.position.y);
-        } else {
-            missCallback();
-        }
-    }
-
-    /**
-     *
-     * @param {SurfacePoint3} result
-     * @param {number} originX
-     * @param {number} originY
-     * @param {number} originZ
-     * @param {number} directionX
-     * @param {number} directionY
-     * @param {number} directionZ
-     * @returns {boolean}
-     */
-    raycastFirstSync(
-        result,
-        originX, originY, originZ,
-        directionX, directionY, directionZ
-    ) {
-        return this.__tiles.raycastFirstSync(result, originX, originY, originZ, directionX, directionY, directionZ);
-    }
-
-    /**
-     *
-     * @param {SurfacePoint3} contact
-     * @param {number} x
-     * @param {number} y
-     * @return {boolean}
-     */
-    raycastVerticalFirstSync(contact, x, y) {
-        return this.__tiles.raycastVerticalFirstSync(contact, x, y);
-    }
-
-    /**
-     *
-     * @param {Array.<Vector3>} points3v points in world coordinate space
-     * @param {function} callback
-     * @param {function} errorCallback
-     */
-    projectPointsVertical(points3v, callback, errorCallback) {
-        /**
-         *
-         * @type {Terrain}
-         */
-        const terrain = this;
-
-        let mappedCount = 0;
-
-        const l = points3v.length;
-
-        const missedPoints = [];
-
-        function finalizePoint() {
-            if (++mappedCount >= l) {
-                mendMissedPoints(points3v, missedPoints);
-                callback(points3v);
-            }
-        }
-
-
-        function mapPoint(index) {
-            const p = points3v[index];
-
-            function missedCallback() {
-                //no mapping
-                missedPoints.push(index);
-
-                finalizePoint();
-            }
-
-            function hitCallback(y) {
-                p.y = y;
-
-                finalizePoint();
-            }
-
-            terrain.sampleHeight(p.x, p.z, hitCallback, missedCallback, errorCallback);
-        }
-
-        if (l === 0) {
-            callback(points3v);
-        } else {
-            for (let i = 0; i < l; i++) {
-                mapPoint(i);
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {Array.<Vector2>} points2v
-     * @param {Vector3[]} result
-     * @param {function} callback
-     * @param {function} errorCallback
-     */
-    mapGridPoints(points2v, result, callback, errorCallback) {
-        const terrain = this;
-
-        const pointCount = points2v.length;
-
-        for (let i = 0; i < pointCount; i++) {
-            const v2 = points2v[i];
-
-            const v3 = result[i];
-
-            terrain.mapPointGrid2World(v2.x, v2.y, v3);
-        }
-
-        this.projectPointsVertical(result, callback, errorCallback);
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {Vector3} result
-     */
-    mapPointGrid2World(x, y, result) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-
-        assert.notNull(result,'result');
-        assert.defined(result, 'result');
-        assert.ok(result.isVector3, 'result is not Vector3');
-
-        const transform = this.gridTransform;
-
-        const _x = x * transform.scale_x + transform.offset_x;
-        const _z = y * transform.scale_y + transform.offset_y;
-
-        result.set(_x, result.y, _z);
-    }
-
-    /**
-     *
-     * @param {Vector3} v3
-     * @param {Vector2} result
-     */
-    mapPointWorld2Grid(v3, result) {
-        const transform = this.gridTransform;
-
-        const x = (v3.x - transform.offset_x) / transform.scale_x;
-        const y = (v3.z - transform.offset_y) / transform.scale_y;
-
-        result.set(x, y);
-    }
-
-    /**
-     *
-     * @return {Promise}
-     */
-    promiseAllTiles() {
-        /**
-         *
-         * @type {TerrainTileManager}
-         */
-        const tiles = this.__tiles;
-
-        const promisedTiles = [];
-
-        tiles.traverse(function (tile) {
-            const position = tile.gridPosition;
-
-            const x = position.x;
-            const y = position.y;
-
-            const tilePromise = tiles.obtain(x, y);
-
-            promisedTiles.push(tilePromise);
-        });
-
-        //promise all tiles
-        return Promise.all(promisedTiles);
-    }
-
-    /**
-     *
-     * @param {mat4|Float32Array|number[]} m4
-     */
-    set transform(m4) {
-        array_copy(m4, 0, this.__transform_matrix, 0, 16);
-
-        this.__tiles.transform = m4;
-    }
-
-    /**
-     *
-     * @return {Float32Array}
-     */
-    get transform() {
-        return this.__transform_matrix;
-    }
-
-    /**
-     *
-     * @param {TerrainLayer} layer
-     */
-    addLayer(layer) {
-        const layers = this.layers;
-        const index = layers.addLayer(layer);
-
-        // expand splat
-        this.splat.addWeightLayer();
-
-        if (this.getFlag(TerrainFlags.Built)) {
-            // terrain is built, need to do a few updates
-
-            layers.buildTexture();
-
-            layer.loadTextureData(this.__assetManager).then(() => {
-                // verify that layer is still present
-                if (layers.get(index) !== layer) {
-                    return;
-                }
-
-                layers.writeLayerDataIntoTexture(index);
-            });
-        }
-
-        return index;
-    }
-
-    /**
-     * Replace the terrain's layer set.
-     *
-     * Rebuilds only what a change of layers actually reaches: the splat map's depth and the layer
-     * texture array. Distinct from {@link Terrain#build}, which registers layers as one step of
-     * standing a terrain up from nothing -- grid transform, build-worker snapshot and a fresh set
-     * of tiles. A terrain that is already built needs none of that to take new layers, and paying
-     * for it throws away tile geometry that is still good.
-     *
-     * @param {TerrainLayer[]} layers
-     * @param {AssetManager} assetManager
-     * @returns {Promise} settles once every layer's texture data has been written into the array
-     */
-    replaceLayers(layers, assetManager) {
-        assert.defined(assetManager, 'assetManager');
-        assert.notNull(assetManager, 'assetManager');
-        assert.equal(assetManager.isAssetManager, true, '.isAssetManager !== true');
-
-        this.__assetManager = assetManager;
-
-        const terrain_layers = this.layers;
-
-        terrain_layers.clear();
-
-        const layer_count = layers.length;
-
-        for (let i = 0; i < layer_count; i++) {
-            terrain_layers.addLayer(layers[i]);
-        }
-
-        // the splat map carries one weight channel per layer; `Terrain#addLayer` keeps the two in
-        // step one layer at a time, this does it for the whole set at once
-        this.splat.resize(this.splat.size.x, this.splat.size.y, layer_count);
-
-        terrain_layers.buildTexture();
-
-        return terrain_layers.loadTextureData(assetManager);
-    }
-
-    /**
-     * Should be called after modifying heights to actualize changes
-     * @returns {Promise<void>}
-     */
-    async updateHeights() {
-        await this.updateWorkerHeights();
-    }
-
-    startBuildService() {
-        this.__buildWorker.start();
-        this.updateWorkerHeights();
-    }
-
-    /**
-     * Ship the current height field to the build worker, which builds tile geometry from a copy of
-     * it and is otherwise blind to main-thread height writes.
-     *
-     * @returns {Promise<void>}
-     */
-    async updateWorkerHeights() {
-        const s = this.samplerHeight;
-        const worker = this.__buildWorker;
-
-        const version = s.version;
-
-        const pending = worker.setHeightSampler(s.data, s.itemSize, s.width, s.height);
-
-        // Claim the snapshot for every tile build submitted from here on -- the worker serves
-        // requests in order, so they all see these heights -- and retire the tiles that describe
-        // an earlier one. Deliberately not awaited: waiting would leave a window in which builds
-        // are already reading the new heights while tiles still claim to hold the old.
-        this.__tiles.setHeightVersion(version);
-
-        await pending;
-
-        return await worker.computeHeightRange()
-            .then(({ min, max }) => {
-                this.__tiles.setHeightRange(min, max);
-            });
-    }
-
-    stopBuildService() {
-        this.__buildWorker.stop();
-    }
-
-    buildGridTransform() {
-        if (this.gridTransformKind === GridTransformKind.Legacy) {
-            this.gridTransform.scale_x = (this.size.x / (this.size.x - 1)) * this.gridScale;
-            this.gridTransform.scale_y = (this.size.y / (this.size.y - 1)) * this.gridScale;
-
-            this.gridTransform.offset_x = 0;
-            this.gridTransform.offset_y = 0;
-
-        } else if (this.gridTransformKind === GridTransformKind.Direct) {
-            this.gridTransform.scale_x = this.gridScale;
-            this.gridTransform.scale_y = this.gridScale;
-
-            this.gridTransform.offset_x = this.gridScale / 2;
-            this.gridTransform.offset_y = this.gridScale / 2;
-        }
-    }
-
-    buildNonVisual() {
-
-        this.buildGridTransform();
-
-        this.bvh.resize(0, 0, 0, 0, 0, 0);
-
-        //
-        this.overlay.size.copy(this.size);
-
-        this.__tiles.totalSize.copy(this.size);
-        this.__tiles.scale.set(this.gridScale, this.gridScale);
-        this.__tiles.resolution.set(this.resolution);
-
-        this.updateWorkerHeights();
-
-    }
-
-    /**
-     *
-     * @param {AssetManager} assetManager
-     */
-    build(assetManager) {
-        if (this.getFlag(TerrainFlags.Built)) {
-            // already built
-            console.warn('already built, if you want rebuild to occur, clear this flag first');
-            return;
-        }
-
-        assert.defined(assetManager, 'assetManager');
-        assert.notNull(assetManager, 'assetManager');
-        assert.equal(assetManager.isAssetManager, true, '.isAssetManager !== true');
-
-        this.__assetManager = assetManager;
-
-        this.buildNonVisual();
-
-        this.layers.buildTexture();
-
-        this.layers.loadTextureData(assetManager);
-
-        /**
-         *
-         * @type {Promise<TerrainTileManager>}
-         * @deprecated
-         */
-        this.pTiles = Promise.resolve(this.__tiles);
-
-        this.__tiles.initialize();
-
-        this.setFlag(TerrainFlags.Built);
-    }
-
-    /**
-     * Note: For advanced users only. You can seriously mess up how things look and function with respect to terrain here
-     * @return {TerrainTileManager}
-     */
-    get tiles() {
-        return this.__tiles;
-    }
-
-    /**
-     * Bake this terrain's ambient-occlusion lightmap onto its material.
-     *
-     * **Retired (D38, 2026-08-20). Calling this throws.** See {@link buildLightTexture} for what it
-     * did and what it cost: a second WebGL context per generated level, tracing a Monte-Carlo AO map
-     * into a texture that only the three-based terrain material ever sampled. Terrain shading under
-     * Shade is U3b's virtual-texture path, and its ambient occlusion is the renderer's own GTAO.
-     *
-     * @deprecated retired by D38 — terrain AO is not baked, and this throws if called
-     * @throws {Error} always
-     */
-    buildLightMap() {
-        buildLightTexture();
-    }
-
-    /**
-     *
-     * @param opt
-     * @param {Engine} engine
-     */
-    fromJSON({
-                 resolution = 4,
-                 preview,
-                 size = 1,
-                 scale = 1,
-                 material,
-                 heights,
-                 layers,
-                 splat,
-                 overlayTileImage
-             } = {}, engine) {
-        // mark as needing rebuilding
-        this.clearFlag(TerrainFlags.Built);
-
-        if (preview !== undefined) {
-            this.preview.fromJSON(preview);
-        }
-
-        this.resolution = resolution;
-
-        this.size.fromJSON(size);
-
-        this.gridScale = scale;
-        //
-
-        this.materialDesc = material;
-
-        if (heights !== undefined) {
-            this.samplerHeight.fromJSON(heights);
-        } else {
-            this.samplerHeight.data = new Float32Array(1);
-            this.samplerHeight.width = 1;
-            this.samplerHeight.height = 1;
-            this.samplerHeight.itemSize = 1;
-            this.samplerHeight.version++;
-        }
-
-        this.layers.fromJSON(layers);
-        this.splat.fromJSON(splat);
-
-        if (overlayTileImage !== undefined) {
-            this.overlay.baseTileImage = overlayTileImage;
-        } else {
-            this.overlay.baseTileImage = WHITE_PIXEL_DATA_URL;
-        }
-
-
-        // debugSamplers(this);
-        this.build(engine.assetManager);
-    }
-
-    toJSON() {
-
-        const result = {
-            size: this.size.toJSON(),
-            scale: this.gridScale,
-            resolution: this.resolution,
-            material: this.materialDesc,
-            preview: this.preview.toJSON(),
-            heights: this.samplerHeight.toJSON(),
-            layers: this.layers.toJSON(),
-            splat: this.splat.toJSON(),
-            overlayTileImage: this.overlay.baseTileImage
-        };
-
-        return result;
-    }
-}
-
-Terrain.typeName = "Terrain";
-
-/**
- *
- * @param {Vector3[]} points
- * @param {number[]} missIndices
- */
-function mendMissedPoints(points, missIndices) {
-    const numPoints = points.length;
-    const lastPointIndex = numPoints - 1;
-
-    const numMisses = missIndices.length;
-
-    for (let i = 0; i < numMisses; i++) {
-        const index = missIndices[i];
-
-        let heightSum = 0;
-        let sampleCount = 0;
-
-        if (index > 0) {
-            heightSum += points[index - 1].y;
-            sampleCount++;
-        }
-
-        if (index < lastPointIndex) {
-            heightSum += points[index + 1].y;
-            sampleCount++;
-        }
-
-        if (sampleCount > 0) {
-            points[index].y = heightSum / sampleCount;
-        }
-    }
-}
-
-
-export default Terrain;
-
+import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
+import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { assert } from "../../../../core/assert.js";
+import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
+import { IllegalStateException } from "../../../../core/fsm/exceptions/IllegalStateException.js";
+import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";
+import Vector2 from '../../../../core/geom/Vector2.js';
+import { Sampler2D } from '../../../graphics/texture/sampler/Sampler2D.js';
+import { WHITE_PIXEL_DATA_URL } from "../../../graphics/WHITE_PIXEL_DATA_URL.js";
+import { TerrainOverlay } from '../overlay/TerrainOverlay.js';
+
+import Clouds from '../TerrainClouds.js';
+import { TerrainPreview } from "../TerrainPreview.js";
+
+import TerrainTileManager from '../tiles/TerrainTileManager.js';
+import { buildLightTexture } from "./BuildLightTexture.js";
+import { GridTransformKind } from "./GridTransformKind.js";
+import { TerrainLayers } from "./layers/TerrainLayers.js";
+import { makeTerrainWorkerProxy } from "./makeTerrainWorkerProxy.js";
+import { OffsetScaleTransform2D } from "./OffsetScaleTransform2D.js";
+import { SplatMapping } from "./splat/SplatMapping.js";
+import { TerrainFlags } from "./TerrainFlags.js";
+
+let idCounter = 0;
+
+/**
+ * Terrain is split into equal sized square patches
+ * Dimensions of single patch in width and height
+ * NOTE: edges of the terrain will typically result in patches smaller than this, so this is upper bound.
+ * A fine {@link Terrain#resolution} lowers it further, see {@link TerrainTileManager#maxTileVertexCount}.
+ * @type {number}
+ */
+const TILE_SIZE = 32;
+
+class Terrain {
+    /**
+     * @readonly
+     * @type {number}
+     */
+    id = idCounter++;
+
+    /**
+     * @private
+     * @type {number|TerrainFlags}
+     */
+    flags = 0;
+
+    /**
+     *
+     * @type {number}
+     */
+    gridScale = 1;
+
+    /**
+     * Transform from grid coordinate system to world coordinate system
+     * @type {OffsetScaleTransform2D}
+     */
+    gridTransform = new OffsetScaleTransform2D();
+
+    /**
+     *
+     * @type {number}
+     */
+    gridTransformKind = GridTransformKind.Direct;
+
+    /**
+     * Number of geometric subdivisions per single terrain tile
+     * @example if value is set to 4, each tile will be split into 4x4 quads
+     * @type {number}
+     */
+    resolution = 4;
+
+    /**
+     * @readonly
+     * @type {Vector2}
+     */
+    size = new Vector2(0, 0);
+    /**
+     *
+     * @type {TerrainPreview}
+     */
+    preview = new TerrainPreview();
+    /**
+     * @readonly
+     * @type {SplatMapping}
+     */
+    splat = new SplatMapping();
+
+    /**
+     * @readonly
+     * @type {TerrainLayers}
+     */
+    layers = new TerrainLayers();
+
+    /**
+     * @readonly
+     * @type {WorkerProxy}
+     */
+    __buildWorker = makeTerrainWorkerProxy();
+
+    /**
+     * @readonly
+     * @type {BvhClient}
+     */
+    bvh = new BvhClient();
+
+    /**
+     * @deprecated
+     * @type {number}
+     */
+    heightRange = 0;
+
+    /**
+     * whether or not frustum culling is enabled
+     * @type {boolean}
+     */
+    frustumCulled = true;
+
+    /**
+     *
+     * @type {AssetManager}
+     * @private
+     */
+    __assetManager = null;
+
+    /**
+     * Authored data with no consumer: the lightmap it names was bound as the terrain material's
+     * `aoMap`, and terrain ambient occlusion under Shade is the renderer's own GTAO. Kept because
+     * levels on disk carry it (I-13) and the field is what round-trips them.
+     *
+     * @type {String}
+     */
+    lightMapURL = null;
+
+    constructor() {
+        /**
+         *
+         * @type {Clouds}
+         */
+        this.clouds = new Clouds();
+        this.clouds.enabled = true;
+
+        /**
+         *
+         * @type {Sampler2D}
+         */
+        this.samplerHeight = Sampler2D.float32(1, 1, 1);
+
+        /**
+         * 4x4 transform matrix
+         * @private
+         * @type {Float32Array}
+         */
+        this.__transform_matrix = m4_allocate();
+
+        /**
+         *
+         * @type {TerrainOverlay}
+         */
+        this.overlay = new TerrainOverlay(this.size);
+
+        /**
+         *
+         * @type {TerrainTileManager}
+         * @private
+         */
+        this.__tiles = new TerrainTileManager({
+            buildWorker: this.__buildWorker
+        });
+
+        this.__tiles.maxTileSize.set(TILE_SIZE, TILE_SIZE);
+    }
+
+    /**
+     *
+     * @param {number|TerrainFlags} flag
+     * @returns {void}
+     */
+    setFlag(flag) {
+        this.flags |= flag;
+    }
+
+    /**
+     *
+     * @param {number|TerrainFlags} flag
+     * @returns {void}
+     */
+    clearFlag(flag) {
+        this.flags &= ~flag;
+    }
+
+    /**
+     *
+     * @param {number|TerrainFlags} flag
+     * @param {boolean} value
+     */
+    writeFlag(flag, value) {
+        if (value) {
+            this.setFlag(flag);
+        } else {
+            this.clearFlag(flag);
+        }
+    }
+
+    /**
+     *
+     * @param {number|TerrainFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * Stand the terrain's live services up: the tile build worker starts and the height field is
+     * shipped to it.
+     *
+     * The renderer is not in it. Linking used to bind a three `ShaderMaterial` through the graphics
+     * engine's material manager, which is what made this a renderer entry point; drawing terrain is
+     * `TerrainSystem`'s, and it reads the component rather than being handed a material by it.
+     */
+    link() {
+
+        if (this.getFlag(TerrainFlags.Linked)) {
+            // already linked
+            return;
+        }
+
+        this.startBuildService();
+
+        this.setFlag(TerrainFlags.Linked);
+    }
+
+    /**
+     * disconnect the component, here all resources are released
+     */
+    unlink() {
+
+        if (!this.getFlag(TerrainFlags.Linked)) {
+            // not linked
+            return;
+        }
+
+        this.stopBuildService();
+
+        this.__tiles.dispose();
+
+        this.bvh.unlink();
+
+        this.clearFlag(TerrainFlags.Linked);
+    }
+
+    dispose() {
+        if (this.getFlag(TerrainFlags.Linked)) {
+            throw new IllegalStateException('component is linked, must be unlinked first');
+        }
+    }
+
+    update(timeDelta) {
+        this.clouds.update(timeDelta);
+    }
+
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {function} callback
+     * @param {function} missCallback
+     * @param {function} errorCallback
+     */
+    sampleHeight(x, y, callback, missCallback, errorCallback) {
+        assert.isFunction(callback, 'callback');
+        assert.isFunction(missCallback, 'missCallback');
+        assert.isFunction(errorCallback, 'errorCallback');
+
+        const hit = new SurfacePoint3();
+
+        if (this.raycastVerticalFirstSync(hit, x, y)) {
+            callback(hit.position.y);
+        } else {
+            missCallback();
+        }
+    }
+
+    /**
+     *
+     * @param {SurfacePoint3} result
+     * @param {number} originX
+     * @param {number} originY
+     * @param {number} originZ
+     * @param {number} directionX
+     * @param {number} directionY
+     * @param {number} directionZ
+     * @returns {boolean}
+     */
+    raycastFirstSync(
+        result,
+        originX, originY, originZ,
+        directionX, directionY, directionZ
+    ) {
+        return this.__tiles.raycastFirstSync(result, originX, originY, originZ, directionX, directionY, directionZ);
+    }
+
+    /**
+     *
+     * @param {SurfacePoint3} contact
+     * @param {number} x
+     * @param {number} y
+     * @return {boolean}
+     */
+    raycastVerticalFirstSync(contact, x, y) {
+        return this.__tiles.raycastVerticalFirstSync(contact, x, y);
+    }
+
+    /**
+     *
+     * @param {Array.<Vector3>} points3v points in world coordinate space
+     * @param {function} callback
+     * @param {function} errorCallback
+     */
+    projectPointsVertical(points3v, callback, errorCallback) {
+        /**
+         *
+         * @type {Terrain}
+         */
+        const terrain = this;
+
+        let mappedCount = 0;
+
+        const l = points3v.length;
+
+        const missedPoints = [];
+
+        function finalizePoint() {
+            if (++mappedCount >= l) {
+                mendMissedPoints(points3v, missedPoints);
+                callback(points3v);
+            }
+        }
+
+
+        function mapPoint(index) {
+            const p = points3v[index];
+
+            function missedCallback() {
+                //no mapping
+                missedPoints.push(index);
+
+                finalizePoint();
+            }
+
+            function hitCallback(y) {
+                p.y = y;
+
+                finalizePoint();
+            }
+
+            terrain.sampleHeight(p.x, p.z, hitCallback, missedCallback, errorCallback);
+        }
+
+        if (l === 0) {
+            callback(points3v);
+        } else {
+            for (let i = 0; i < l; i++) {
+                mapPoint(i);
+            }
+        }
+    }
+
+    /**
+     *
+     * @param {Array.<Vector2>} points2v
+     * @param {Vector3[]} result
+     * @param {function} callback
+     * @param {function} errorCallback
+     */
+    mapGridPoints(points2v, result, callback, errorCallback) {
+        const terrain = this;
+
+        const pointCount = points2v.length;
+
+        for (let i = 0; i < pointCount; i++) {
+            const v2 = points2v[i];
+
+            const v3 = result[i];
+
+            terrain.mapPointGrid2World(v2.x, v2.y, v3);
+        }
+
+        this.projectPointsVertical(result, callback, errorCallback);
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {Vector3} result
+     */
+    mapPointGrid2World(x, y, result) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+
+        assert.notNull(result,'result');
+        assert.defined(result, 'result');
+        assert.ok(result.isVector3, 'result is not Vector3');
+
+        const transform = this.gridTransform;
+
+        const _x = x * transform.scale_x + transform.offset_x;
+        const _z = y * transform.scale_y + transform.offset_y;
+
+        result.set(_x, result.y, _z);
+    }
+
+    /**
+     *
+     * @param {Vector3} v3
+     * @param {Vector2} result
+     */
+    mapPointWorld2Grid(v3, result) {
+        const transform = this.gridTransform;
+
+        const x = (v3.x - transform.offset_x) / transform.scale_x;
+        const y = (v3.z - transform.offset_y) / transform.scale_y;
+
+        result.set(x, y);
+    }
+
+    /**
+     *
+     * @return {Promise}
+     */
+    promiseAllTiles() {
+        /**
+         *
+         * @type {TerrainTileManager}
+         */
+        const tiles = this.__tiles;
+
+        const promisedTiles = [];
+
+        tiles.traverse(function (tile) {
+            const position = tile.gridPosition;
+
+            const x = position.x;
+            const y = position.y;
+
+            const tilePromise = tiles.obtain(x, y);
+
+            promisedTiles.push(tilePromise);
+        });
+
+        //promise all tiles
+        return Promise.all(promisedTiles);
+    }
+
+    /**
+     *
+     * @param {mat4|Float32Array|number[]} m4
+     */
+    set transform(m4) {
+        array_copy(m4, 0, this.__transform_matrix, 0, 16);
+
+        this.__tiles.transform = m4;
+    }
+
+    /**
+     *
+     * @return {Float32Array}
+     */
+    get transform() {
+        return this.__transform_matrix;
+    }
+
+    /**
+     *
+     * @param {TerrainLayer} layer
+     */
+    addLayer(layer) {
+        const layers = this.layers;
+        const index = layers.addLayer(layer);
+
+        // expand splat
+        this.splat.addWeightLayer();
+
+        if (this.getFlag(TerrainFlags.Built)) {
+            // terrain is built, need to do a few updates
+
+            layers.buildTexture();
+
+            layer.loadTextureData(this.__assetManager).then(() => {
+                // verify that layer is still present
+                if (layers.get(index) !== layer) {
+                    return;
+                }
+
+                layers.writeLayerDataIntoTexture(index);
+            });
+        }
+
+        return index;
+    }
+
+    /**
+     * Replace the terrain's layer set.
+     *
+     * Rebuilds only what a change of layers actually reaches: the splat map's depth and the layer
+     * texture array. Distinct from {@link Terrain#build}, which registers layers as one step of
+     * standing a terrain up from nothing -- grid transform, build-worker snapshot and a fresh set
+     * of tiles. A terrain that is already built needs none of that to take new layers, and paying
+     * for it throws away tile geometry that is still good.
+     *
+     * @param {TerrainLayer[]} layers
+     * @param {AssetManager} assetManager
+     * @returns {Promise} settles once every layer's texture data has been written into the array
+     */
+    replaceLayers(layers, assetManager) {
+        assert.defined(assetManager, 'assetManager');
+        assert.notNull(assetManager, 'assetManager');
+        assert.equal(assetManager.isAssetManager, true, '.isAssetManager !== true');
+
+        this.__assetManager = assetManager;
+
+        const terrain_layers = this.layers;
+
+        terrain_layers.clear();
+
+        const layer_count = layers.length;
+
+        for (let i = 0; i < layer_count; i++) {
+            terrain_layers.addLayer(layers[i]);
+        }
+
+        // the splat map carries one weight channel per layer; `Terrain#addLayer` keeps the two in
+        // step one layer at a time, this does it for the whole set at once
+        this.splat.resize(this.splat.size.x, this.splat.size.y, layer_count);
+
+        terrain_layers.buildTexture();
+
+        return terrain_layers.loadTextureData(assetManager);
+    }
+
+    /**
+     * Should be called after modifying heights to actualize changes
+     * @returns {Promise<void>}
+     */
+    async updateHeights() {
+        await this.updateWorkerHeights();
+    }
+
+    startBuildService() {
+        this.__buildWorker.start();
+        this.updateWorkerHeights();
+    }
+
+    /**
+     * Ship the current height field to the build worker, which builds tile geometry from a copy of
+     * it and is otherwise blind to main-thread height writes.
+     *
+     * @returns {Promise<void>}
+     */
+    async updateWorkerHeights() {
+        const s = this.samplerHeight;
+        const worker = this.__buildWorker;
+
+        const version = s.version;
+
+        const pending = worker.setHeightSampler(s.data, s.itemSize, s.width, s.height);
+
+        // Claim the snapshot for every tile build submitted from here on -- the worker serves
+        // requests in order, so they all see these heights -- and retire the tiles that describe
+        // an earlier one. Deliberately not awaited: waiting would leave a window in which builds
+        // are already reading the new heights while tiles still claim to hold the old.
+        this.__tiles.setHeightVersion(version);
+
+        await pending;
+
+        return await worker.computeHeightRange()
+            .then(({ min, max }) => {
+                this.__tiles.setHeightRange(min, max);
+            });
+    }
+
+    stopBuildService() {
+        this.__buildWorker.stop();
+    }
+
+    buildGridTransform() {
+        if (this.gridTransformKind === GridTransformKind.Legacy) {
+            this.gridTransform.scale_x = (this.size.x / (this.size.x - 1)) * this.gridScale;
+            this.gridTransform.scale_y = (this.size.y / (this.size.y - 1)) * this.gridScale;
+
+            this.gridTransform.offset_x = 0;
+            this.gridTransform.offset_y = 0;
+
+        } else if (this.gridTransformKind === GridTransformKind.Direct) {
+            this.gridTransform.scale_x = this.gridScale;
+            this.gridTransform.scale_y = this.gridScale;
+
+            this.gridTransform.offset_x = this.gridScale / 2;
+            this.gridTransform.offset_y = this.gridScale / 2;
+        }
+    }
+
+    buildNonVisual() {
+
+        this.buildGridTransform();
+
+        this.bvh.resize(0, 0, 0, 0, 0, 0);
+
+        //
+        this.overlay.size.copy(this.size);
+
+        this.__tiles.totalSize.copy(this.size);
+        this.__tiles.scale.set(this.gridScale, this.gridScale);
+        this.__tiles.resolution.set(this.resolution);
+
+        this.updateWorkerHeights();
+
+    }
+
+    /**
+     *
+     * @param {AssetManager} assetManager
+     */
+    build(assetManager) {
+        if (this.getFlag(TerrainFlags.Built)) {
+            // already built
+            console.warn('already built, if you want rebuild to occur, clear this flag first');
+            return;
+        }
+
+        assert.defined(assetManager, 'assetManager');
+        assert.notNull(assetManager, 'assetManager');
+        assert.equal(assetManager.isAssetManager, true, '.isAssetManager !== true');
+
+        this.__assetManager = assetManager;
+
+        this.buildNonVisual();
+
+        this.layers.buildTexture();
+
+        this.layers.loadTextureData(assetManager);
+
+        /**
+         *
+         * @type {Promise<TerrainTileManager>}
+         * @deprecated
+         */
+        this.pTiles = Promise.resolve(this.__tiles);
+
+        this.__tiles.initialize();
+
+        this.setFlag(TerrainFlags.Built);
+    }
+
+    /**
+     * Note: For advanced users only. You can seriously mess up how things look and function with respect to terrain here
+     * @return {TerrainTileManager}
+     */
+    get tiles() {
+        return this.__tiles;
+    }
+
+    /**
+     * Bake this terrain's ambient-occlusion lightmap onto its material.
+     *
+     * **Retired (D38, 2026-08-20). Calling this throws.** See {@link buildLightTexture} for what it
+     * did and what it cost: a second WebGL context per generated level, tracing a Monte-Carlo AO map
+     * into a texture that only the three-based terrain material ever sampled. Terrain shading under
+     * Shade is U3b's virtual-texture path, and its ambient occlusion is the renderer's own GTAO.
+     *
+     * @deprecated retired by D38 — terrain AO is not baked, and this throws if called
+     * @throws {Error} always
+     */
+    buildLightMap() {
+        buildLightTexture();
+    }
+
+    /**
+     *
+     * @param opt
+     * @param {Engine} engine
+     */
+    fromJSON({
+                 resolution = 4,
+                 preview,
+                 size = 1,
+                 scale = 1,
+                 material,
+                 heights,
+                 layers,
+                 splat,
+                 overlayTileImage
+             } = {}, engine) {
+        // mark as needing rebuilding
+        this.clearFlag(TerrainFlags.Built);
+
+        if (preview !== undefined) {
+            this.preview.fromJSON(preview);
+        }
+
+        this.resolution = resolution;
+
+        this.size.fromJSON(size);
+
+        this.gridScale = scale;
+        //
+
+        this.materialDesc = material;
+
+        if (heights !== undefined) {
+            this.samplerHeight.fromJSON(heights);
+        } else {
+            this.samplerHeight.data = new Float32Array(1);
+            this.samplerHeight.width = 1;
+            this.samplerHeight.height = 1;
+            this.samplerHeight.itemSize = 1;
+            this.samplerHeight.version++;
+        }
+
+        this.layers.fromJSON(layers);
+        this.splat.fromJSON(splat);
+
+        if (overlayTileImage !== undefined) {
+            this.overlay.baseTileImage = overlayTileImage;
+        } else {
+            this.overlay.baseTileImage = WHITE_PIXEL_DATA_URL;
+        }
+
+
+        // debugSamplers(this);
+        this.build(engine.assetManager);
+    }
+
+    toJSON() {
+
+        const result = {
+            size: this.size.toJSON(),
+            scale: this.gridScale,
+            resolution: this.resolution,
+            material: this.materialDesc,
+            preview: this.preview.toJSON(),
+            heights: this.samplerHeight.toJSON(),
+            layers: this.layers.toJSON(),
+            splat: this.splat.toJSON(),
+            overlayTileImage: this.overlay.baseTileImage
+        };
+
+        return result;
+    }
+}
+
+Terrain.typeName = "Terrain";
+
+/**
+ *
+ * @param {Vector3[]} points
+ * @param {number[]} missIndices
+ */
+function mendMissedPoints(points, missIndices) {
+    const numPoints = points.length;
+    const lastPointIndex = numPoints - 1;
+
+    const numMisses = missIndices.length;
+
+    for (let i = 0; i < numMisses; i++) {
+        const index = missIndices[i];
+
+        let heightSum = 0;
+        let sampleCount = 0;
+
+        if (index > 0) {
+            heightSum += points[index - 1].y;
+            sampleCount++;
+        }
+
+        if (index < lastPointIndex) {
+            heightSum += points[index + 1].y;
+            sampleCount++;
+        }
+
+        if (sampleCount > 0) {
+            points[index].y = heightSum / sampleCount;
+        }
+    }
+}
+
+
+export default Terrain;
+