@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/ecs/terrain/tiles/TerrainTileManager.js

@@ -1,896 +1,896 @@
-import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
-import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
-import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.js";
-import { array_copy } from "../../../../core/collection/array/array_copy.js";
-import { assert } from "../../../../core/assert.js";
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import { bvh_query_leaves_ray } from "../../../../core/bvh2/bvh3/query/bvh_query_leaves_ray.js";
-import { isArrayEqualStrict } from "../../../../core/collection/array/isArrayEqualStrict.js";
-import Signal from '../../../../core/events/signal/Signal.js';
-import { aabb2_intersects_aabb2 } from "../../../../core/geom/2d/aabb/aabb2_intersects_aabb2.js";
-import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";
-import Vector2 from '../../../../core/geom/Vector2.js';
-import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
-import { max2 } from "../../../../core/math/max2.js";
-import { min2 } from "../../../../core/math/min2.js";
-import ObservedInteger from "../../../../core/model/ObservedInteger.js";
-
-import TerrainTile from './TerrainTile.js';
-
-/**
- *
- * @type {number[]}
- */
-const scratch_array = [];
-const scratch_contact = new SurfacePoint3();
-
-/**
- * Largest whole number of grid cells that fits inside a per-tile vertex budget along one tile edge,
- * never more than the requested edge and never less than a single cell.
- *
- * A single grid cell is the smallest tile there is, so a resolution fine enough that one cell alone
- * blows the budget cannot be honoured and the budget is exceeded.
- *
- * @param {number} max_edge largest acceptable edge, in grid cells
- * @param {number} resolution vertices per grid cell along one axis
- * @param {number} max_vertex_count budget for the whole tile
- * @returns {number} edge length in grid cells
- */
-function tile_edge(max_edge, resolution, max_vertex_count) {
-    const budget_edge = Math.floor(Math.sqrt(max_vertex_count) / resolution);
-
-    return max2(1, min2(max_edge, budget_edge));
-}
-
-class TerrainTileManager {
-    /**
-     *
-     * @type {TerrainTile[]}
-     */
-    tiles = [];
-
-    on = {
-        tileBuilt: new Signal(),
-        tileDestroyed: new Signal()
-    };
-
-    /**
-     * Largest tile edge, in grid cells. Tiles are the unit of frustum culling, seam stitching and
-     * rebuild-on-paint, so a coarse value is preferable -- but only up to the point where a single
-     * tile's geometry stops fitting {@link TerrainTileManager#maxTileVertexCount}, past which tiles
-     * are subdivided further. See {@link TerrainTileManager#tileEdgeX}.
-     *
-     * The last row and column of the grid are whatever is left over, so this is an upper bound and
-     * not a divisor of {@link TerrainTileManager#totalSize}.
-     *
-     * @type {Vector2}
-     */
-    maxTileSize = new Vector2(10, 10);
-
-    /**
-     * Upper bound on the number of vertices in a single tile.
-     *
-     * A tile is built in one shot -- the whole grid is allocated, sampled, normal-fitted and fed to
-     * a BVH build with no chunking anywhere -- so an unbounded tile is an unbounded allocation. At
-     * a resolution of 64 a 32x32 terrain would otherwise land in a single 4.19M-vertex tile, which
-     * costs upwards of 800MB to build and kills the renderer process outright.
-     *
-     * 65536 is the largest count that keeps the index array 16-bit
-     * (see {@link UintArrayForCount}), which caps a built tile at roughly 9MB of geometry and BVH.
-     *
-     * @type {number}
-     */
-    maxTileVertexCount = 65536;
-
-    /**
-     *
-     * @type {Vector2}
-     */
-    totalSize = new Vector2(1, 1);
-    /**
-     * Number of subdivisions per single grid cell
-     * @type {ObservedInteger}
-     */
-    resolution = new ObservedInteger(4);
-
-    /**
-     * 2D Scale of the terrain
-     * @type {Vector2}
-     */
-    scale = new Vector2(1, 1);
-
-
-    /**
-     *
-     * @type {Float32Array}
-     * @private
-     */
-    __transform = new Float32Array(16);
-
-    /**
-     * @readonly
-     * @type {BVH}
-     */
-    bvh = new BVH();
-
-    /**
-     *
-     * @type {NumericInterval}
-     */
-    heightRange = new NumericInterval(0, 0);
-
-    /**
-     * Version of the height snapshot {@link TerrainTileManager#buildWorker} currently holds, as
-     * handed over by {@link TerrainTileManager#setHeightVersion}. `-1` until the first snapshot is
-     * shipped, at which point no tile can have been built yet.
-     *
-     * The worker builds tiles from its own copy of the height field, so main-thread height writes
-     * are invisible to it until a new snapshot is sent. This is what a built tile is measured
-     * against to tell "built from the heights that are current" from "built from whatever the
-     * worker happened to hold at the time".
-     *
-     * @type {number}
-     */
-    heightVersion = -1;
-
-    /**
-     * The manager owns tile geometry and the streaming that keeps it current; how a tile is shaded
-     * is the renderer's. It used to hold a material and push it onto every tile's mesh, which is
-     * what made a tile grid something only one renderer could draw.
-     *
-     * @param {WorkerProxy} buildWorker
-     */
-    constructor(
-        {
-            buildWorker
-        }
-    ) {
-        /**
-         *
-         * @type {WorkerProxy}
-         */
-        this.buildWorker = buildWorker;
-    }
-
-    set transform(m4) {
-        if (isArrayEqualStrict(m4, this.__transform)) {
-            // no change
-            return;
-        }
-
-        array_copy(m4, 0, this.__transform, 0, 16);
-
-        this.traverse(t => {
-            t.transform = m4;
-        });
-    }
-
-    get transform() {
-        return this.__transform;
-    }
-
-    /**
-     * Record the height snapshot the build worker has just been handed, and drop every tile whose
-     * geometry describes an older one.
-     *
-     * Invalidated tiles keep their identity, position and place in the BVH -- only their geometry
-     * is stale -- so they are marked unbuilt rather than destroyed, and the ordinary build paths
-     * ({@link TerrainTileManager#obtain}, the renderer's visible-tile sweep) bring them back with
-     * the current heights.
-     *
-     * Must be called at the point the snapshot is *submitted* to the worker, not when the worker
-     * acknowledges it: the worker serves requests in submission order, so every tile build
-     * submitted from here on already sees the new heights.
-     *
-     * @param {number} version
-     */
-    setHeightVersion(version) {
-        assert.isNumber(version, 'version');
-
-        if (version === this.heightVersion) {
-            // worker already holds this snapshot, every built tile is measured against it
-            return;
-        }
-
-        this.heightVersion = version;
-
-        const tiles = this.tiles;
-
-        const n = tiles.length;
-
-        for (let i = 0; i < n; i++) {
-            const tile = tiles[i];
-
-            if (tile.isBuilt && tile.heightVersion !== version) {
-                tile.isBuilt = false;
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {number} min_height
-     * @param {number} max_height
-     */
-    setHeightRange(min_height, max_height) {
-        assert.isNumber(min_height, 'min_height');
-        assert.notNaN(min_height, 'min_height');
-
-        assert.isNumber(max_height, 'max_height');
-        assert.notNaN(max_height, 'max_height');
-
-        this.heightRange.set(min_height, max_height);
-
-        const tiles = this.tiles;
-
-        const n = tiles.length;
-
-        for (let i = 0; i < n; i++) {
-            const terrainTile = tiles[i];
-
-            if (
-                !terrainTile.isBuilt
-                && !terrainTile.isBuildInProgress
-            ) {
-
-                const bb = terrainTile.external_bvh;
-
-                bb.bounds[1] = min_height;
-                bb.bounds[4] = max_height;
-
-                bb.write_bounds();
-
-            }
-
-        }
-    }
-
-    initialize() {
-        this.destroyTiles();
-
-        this.initializeTiles();
-    }
-
-    /**
-     *
-     * @param {(tile: TerrainTile) => void} callback
-     * @param {*} [thisArg]
-     */
-    traverse(callback, thisArg) {
-        const tiles = this.tiles;
-        let tile;
-        let i = 0;
-        const il = tiles.length;
-        for (; i < il; i++) {
-            tile = tiles[i];
-            callback.call(thisArg, tile);
-        }
-    }
-
-    destroyTiles() {
-
-        //destroy all existing tiles
-        const tiles = this.tiles;
-        const tile_count = tiles.length;
-
-        console.warn(`#destroyTiles tile_count=${tile_count}`);
-
-        for (let i = 0; i < tile_count; i++) {
-            const tile = tiles[i];
-
-            tile.external_bvh.unlink();
-            tile.dispose();
-
-        }
-
-        tiles.splice(0, tile_count);
-
-        //clear out BVH
-        this.bvh.release_all();
-
-    }
-
-    /**
-     * Rebuild all tiles
-     */
-    rebuild() {
-        this.destroyTiles();
-
-        this.initializeTiles();
-    }
-
-    /**
-     * Rebuild tiles that overlap rectangular region of the overall terrain defined by normalized coordinates (UV space)
-     * @param {number} u0
-     * @param {number} v0
-     * @param {number} u1
-     * @param {number} v1
-     */
-    rebuildTilesByUV(
-        u0, v0,
-        u1, v1
-    ) {
-
-        const size = this.totalSize;
-
-        const tx0 = u0 * size.x;
-        const tx1 = u1 * size.x;
-
-        const ty0 = v0 * size.y;
-        const ty1 = v1 * size.y;
-
-        const dirty_tiles = this.getRawTilesOverlappingRectangle(tx0 - 1, ty0 - 1, tx1 + 1, ty1 + 1);
-
-        const dirty_count = dirty_tiles.length;
-
-        for (let i = 0; i < dirty_count; i++) {
-            const tile = dirty_tiles[i];
-            tile.isBuilt = false;
-        }
-    }
-
-
-    /**
-     *
-     * @param {number} x0
-     * @param {number} y0
-     * @param {number} x1
-     * @param {number} y1
-     * @returns {TerrainTile[]}
-     */
-    getRawTilesOverlappingRectangle(x0, y0, x1, y1) {
-        /**
-         *
-         * @type {TerrainTile[]}
-         */
-        const result = [];
-
-        const terrainTiles = this.tiles;
-
-        const n = terrainTiles.length;
-
-        for (let i = 0; i < n; i++) {
-            const tile = terrainTiles[i];
-
-            const tx0 = tile.position.x;
-            const ty0 = tile.position.y;
-
-            const tx1 = tx0 + tile.size.x;
-            const ty1 = ty0 + tile.size.y;
-            if (
-                aabb2_intersects_aabb2(
-                    x0, y0, x1, y1,
-                    tx0, ty0, tx1, ty1
-                )
-            ) {
-                result.push(tile);
-            }
-        }
-
-        return result;
-    }
-
-    initializeTiles() {
-        const total_size = this.totalSize;
-
-        const tile_size_x = this.tileEdgeX;
-        const tile_size_y = this.tileEdgeY;
-
-        const tiles = this.tiles;
-
-        if (tiles.length > 0) {
-            throw new Error(`There are already ${tiles.length} initialized tiles, those must be destroyed before initialization can happen`);
-        }
-
-        //populate tiles
-        const tile_resolution_y = this.gridHeight;
-        const tile_resolution_x = this.gridWidth;
-
-        for (let y = 0; y < tile_resolution_y; y++) {
-
-            const tY = y < tile_resolution_y - 1 ? tile_size_y : (total_size.y - tile_size_y * y);
-
-            for (let x = 0; x < tile_resolution_x; x++) {
-
-                const tX = x < tile_resolution_x - 1 ? tile_size_x : (total_size.x - tile_size_x * x);
-
-                const tile = new TerrainTile();
-                const index = y * tile_resolution_x + x;
-                tiles[index] = tile;
-
-                tile.gridPosition.set(x, y);
-
-                tile.size.set(tX, tY);
-                tile.position.set(tile_size_x * x, tile_size_y * y);
-                tile.scale.copy(this.scale);
-                tile.resolution.copy(this.resolution);
-
-                tile.setInitialHeightBounds(this.heightRange.min, this.heightRange.max);
-                tile.computeBoundingBox();
-
-                tile.external_bvh.link(this.bvh, index);
-            }
-        }
-
-    }
-
-    /**
-     *
-     * @param {number} x Tile X coordinate
-     * @param {number} y Tile Y coordinate
-     * @returns {number}
-     */
-    computeTileIndex(x, y) {
-        assert.isNonNegativeInteger(x, 'x');
-        assert.isNonNegativeInteger(y, 'y');
-
-        const w = this.gridWidth;
-
-        assert.ok(x < w, `x(=${x}) must be less than than width(=${w})`);
-        assert.ok(y < this.gridHeight, `y(=${y}) must be less than than height(=${this.gridHeight})`);
-
-        return y * w + x;
-    }
-
-    /**
-     * Tile edge along X, in grid cells. Derived rather than stored so that it always reflects the
-     * current {@link TerrainTileManager#resolution}; a terrain rebuilt at a coarser resolution goes
-     * back to coarser tiles.
-     *
-     * PRECONDITION, shared by {@link TerrainTileManager#gridWidth},
-     * {@link TerrainTileManager#gridHeight} and {@link TerrainTileManager#getRawTileByPosition}:
-     * these describe the grid the *current configuration* asks for, which is the grid held in
-     * {@link TerrainTileManager#tiles} only for as long as that configuration is unchanged. Writing
-     * `totalSize`, `maxTileSize`, `resolution` or `maxTileVertexCount` after tiles exist leaves the
-     * two disagreeing, and a tile lookup then reads the wrong index. Follow any such write with
-     * {@link TerrainTileManager#rebuild}.
-     *
-     * @returns {number}
-     */
-    get tileEdgeX() {
-        return tile_edge(this.maxTileSize.x, this.resolution.getValue(), this.maxTileVertexCount);
-    }
-
-    /**
-     * Tile edge along Y, in grid cells.
-     * @returns {number}
-     */
-    get tileEdgeY() {
-        return tile_edge(this.maxTileSize.y, this.resolution.getValue(), this.maxTileVertexCount);
-    }
-
-    /**
-     * Number of tiles along X. A terrain whose size is not a whole multiple of
-     * the tile size ends in a partial tile, and that tile is real, so this
-     * rounds up. Every consumer must agree on this or edge tiles fall outside
-     * whatever grid the consumer imagined.
-     * @returns {number}
-     */
-    get gridWidth() {
-        return Math.ceil(this.totalSize.x / this.tileEdgeX);
-    }
-
-    /**
-     * Number of tiles along Y.
-     * @returns {number}
-     */
-    get gridHeight() {
-        return Math.ceil(this.totalSize.y / this.tileEdgeY);
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @returns {TerrainTile|undefined}
-     */
-    getRaw(x, y) {
-        if (
-            x < 0
-            || x >= this.gridWidth
-            || y < 0
-        ) {
-            return undefined;
-        }
-
-        const tileIndex = this.computeTileIndex(x, y);
-
-        assert.ok(tileIndex >= 0, `tileIndex(=${tileIndex}) must be >= 0`);
-        assert.ok(tileIndex <= this.tiles.length, `tileIndex(=${tileIndex}) must be <= tileCount(=${this.tiles.length})`);
-
-        return this.tiles[tileIndex];
-    }
-
-    /**
-     *
-     * @param {number} x Grid X coordinate
-     * @param {number} y Grid Y coordinate
-     * @returns {TerrainTile}
-     */
-    getRawTileByPosition(x, y) {
-        assert.isNumber(x, 'x');
-        assert.notNaN(x, 'x');
-
-        assert.isNumber(y, 'y');
-        assert.notNaN(y, 'y');
-
-        const tileX = Math.floor(x / this.tileEdgeX);
-        const tileY = Math.floor(y / this.tileEdgeY);
-
-        return this.getRaw(tileX, tileY);
-    }
-
-    /**
-     * Given world coordinates in top-down plane, where X runs along X axis and Y runs along Z axis, returns terrain tile that overlaps that 2d region
-     * @param {number} x
-     * @param {number} y
-     * @return {TerrainTile|undefined}
-     */
-    getTileByWorldPosition2D(x, y) {
-        const v3 = Float32Array.of(x, 0, y);
-
-        const world_inverse = m4_allocate();
-
-        m4_invert(world_inverse, this.transform);
-
-
-        v3_matrix4_multiply(v3, 0, v3, 0, world_inverse);
-
-        // v3 was built as (x, 0, z): index 1 is the vertical axis, which is not
-        // a grid row. The top-down plane is X/Z.
-        //
-        // getRawTileByPosition takes *grid* coordinates, and `transform` does
-        // not carry the grid scale -- tiles apply it themselves (see
-        // assignTileScale). Divide it out here, matching Terrain's own
-        // mapPointWorld2Grid.
-        return this.getRawTileByPosition(v3[0] / this.scale.x, v3[2] / this.scale.y);
-    }
-
-    /**
-     * Builds and returns the tile from world coordinates
-     * @param {number} x
-     * @param {number} y
-     * @returns {Promise<TerrainTile>}
-     */
-    obtainTileAtWorldPosition2D(x, y) {
-        assert.isNumber(x, 'x')
-        assert.notNaN(x, 'x')
-
-        assert.isNumber(y, 'y')
-        assert.notNaN(y, 'y')
-
-        const tile = this.getTileByWorldPosition2D(x, y);
-
-        return this.obtain(tile.gridPosition.x, tile.gridPosition.y);
-    }
-
-    /**
-     *
-     * @param {number} x coordinate
-     * @param {number} y coordinate
-     * @returns {Promise<TerrainTile>}
-     * @throws if no tile exists at given coordinates
-     */
-    obtain(x, y) {
-        const tile = this.getRaw(x, y);
-
-        if (tile === undefined) {
-            throw new Error(`No tile found at x=${x},y=${y}`);
-        }
-
-        tile.referenceCount++;
-
-        if (tile.isBuilt) {
-            return Promise.resolve(tile);
-
-        } else {
-
-            if (!tile.isBuildInProgress) {
-                return new Promise((resolve, reject) => this.build(x, y, resolve, reject));
-            } else {
-                return new Promise((resolve, reject) => {
-                    tile.onBuilt.addOne(resolve);
-                    tile.onDestroyed.addOne(reject);
-                });
-            }
-
-        }
-
-    }
-
-    /**
-     *
-     * @param {TerrainTile} tile
-     */
-    release(tile) {
-        if (tile.referenceCount <= 0) {
-            console.warn('Tile already has no references');
-        }
-
-        tile.referenceCount--;
-
-        if (tile.referenceCount <= 0) {
-            //potential garbage
-            tile.dispose();
-        }
-
-    }
-
-    dispose() {
-        const tiles = this.tiles;
-
-        const n = tiles.length;
-
-        for (let i = 0; i < n; i++) {
-            const t = tiles[i];
-            t.dispose();
-        }
-    }
-
-    /**
-     * Fix normals along the seams of the tile
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {TerrainTile} tile
-     */
-    stitchTile(x, y, tile) {
-
-        const n = this.collectTileNeighbours(x, y);
-
-        tile.stitchNormals(
-            n.top, n.bottom, n.left, n.right,
-            n.topLeft, n.topRight, n.bottomLeft, n.bottomRight
-        );
-    }
-
-    /**
-     * The eight tiles surrounding a grid cell, each undefined where the cell sits
-     * on the edge of the grid.
-     *
-     * Partial edge tiles are real tiles, so the neighbour grid must round up
-     * exactly as tile creation and getRaw do. Flooring it -- as this did until
-     * recently -- leaves the last row and column believing they have no
-     * neighbour on the outward side, so their seams are never stitched.
-     *
-     * @param {number} x Tile X coordinate
-     * @param {number} y Tile Y coordinate
-     * @returns {Object<string,TerrainTile|undefined>}
-     */
-    collectTileNeighbours(x, y) {
-        const gridWidth = this.gridWidth;
-        const gridHeight = this.gridHeight;
-
-        const result = {
-            top: undefined,
-            bottom: undefined,
-            left: undefined,
-            right: undefined,
-            topLeft: undefined,
-            topRight: undefined,
-            bottomLeft: undefined,
-            bottomRight: undefined
-        };
-
-        if (y > 0) {
-            result.top = this.getRaw(x, y - 1);
-
-            if (x > 0) {
-                result.topLeft = this.getRaw(x - 1, y - 1);
-            }
-
-            if (x < gridWidth - 1) {
-                result.topRight = this.getRaw(x + 1, y - 1);
-            }
-        }
-
-        if (y < gridHeight - 1) {
-            result.bottom = this.getRaw(x, y + 1);
-
-            if (x > 0) {
-                result.bottomLeft = this.getRaw(x - 1, y + 1);
-            }
-
-            if (x < gridWidth - 1) {
-                result.bottomRight = this.getRaw(x + 1, y + 1);
-            }
-        }
-
-        if (x > 0) {
-            result.left = this.getRaw(x - 1, y);
-        }
-
-        if (x < gridWidth - 1) {
-            result.right = this.getRaw(x + 1, y);
-        }
-
-        return result;
-    }
-
-    /**
-     *
-     * @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
-    ) {
-
-        const hit_count = bvh_query_leaves_ray(
-            scratch_array, 0,
-            this.bvh,
-            this.bvh.root,
-            originX, originY, originZ,
-            directionX, directionY, directionZ
-        );
-
-        let closest_hit_distance = Number.POSITIVE_INFINITY;
-        let hit_found = false;
-
-        for (let i = 0; i < hit_count; i++) {
-            const node_id = scratch_array[i];
-
-            const tile_index = this.bvh.node_get_user_data(node_id);
-
-            const tile = this.tiles[tile_index];
-
-            if (!tile.isBuilt) {
-                continue;
-            }
-
-            const tile_hit_found = tile.raycastFirstSync(
-                scratch_contact,
-                originX, originY, originZ,
-                directionX, directionY, directionZ
-            );
-
-            if (!tile_hit_found) {
-                continue;
-            }
-
-            hit_found = true;
-
-            const distance_sqr = scratch_contact.position._distanceSqrTo(originX, originY, originZ);
-
-            if (distance_sqr < closest_hit_distance) {
-                closest_hit_distance = distance_sqr;
-                result.copy(scratch_contact);
-            }
-        }
-
-        return hit_found;
-    }
-
-    /**
-     * TODO untested
-     * @param {SurfacePoint3} contact
-     * @param {number} x
-     * @param {number} y
-     * @return {boolean}
-     */
-    raycastVerticalFirstSync(contact, x, y) {
-        // console.log('+ raycastVerticalFirstSync');
-        const r = this.raycastFirstSync(contact, x, -10000, y, 0, 1, 0);
-        // console.log('- raycastVerticalFirstSync');
-        return r;
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {(tile: TerrainTile) => void} resolve
-     * @param {(reason: *) => void} reject
-     */
-    build(x, y, resolve, reject) {
-
-        assert.isFunction(resolve, 'resolve');
-        assert.isFunction(reject, 'reject');
-
-        const tile_index = this.computeTileIndex(x, y);
-
-        const tile = this.tiles[tile_index];
-
-        if (tile.isBuildInProgress) {
-            throw new Error('Tile is already in process of being built');
-        }
-
-        const start_version = tile.version;
-        const start_height_version = this.heightVersion;
-
-        tile.isBuilt = false;
-        tile.isBuildInProgress = true;
-
-        const tile_resolution = tile.resolution.getValue();
-
-        this.buildWorker.buildTile(
-            tile.position.toJSON(),
-            tile.size.toJSON(),
-            tile.scale.toJSON(),
-            this.totalSize.toJSON(),
-            tile_resolution
-        ).then((tileData) => {
-
-            //check that the tile under index is still the same tile
-            if (this.tiles[tile_index] !== tile) {
-                //the original tile was destroyed
-                reject('Original tile was destroyed during build process');
-                return;
-            }
-
-            if (tile.version !== start_version) {
-                reject(`Tile version changed, likely due to concurrent build request. Expected version ${start_version}, actual version ${tile.version}`);
-                return;
-            }
-
-            if (!tile.isBuildInProgress) {
-                if (tile.isBuilt) {
-                    // tile already built
-                    resolve(tile);
-                    return;
-                } else {
-
-                    reject('Build request has been cancelled');
-                    return;
-                }
-            }
-
-            if (this.heightVersion !== start_height_version) {
-                // heights moved on while this tile was in the worker, so the geometry that came
-                // back describes a height field that no longer exists. Build it again; the worker
-                // now holds the current snapshot, so the next attempt lands on the right heights.
-                tile.isBuildInProgress = false;
-
-                this.build(x, y, resolve, reject);
-                return;
-            }
-
-            // const processName = 'building tile x = ' + x + ", y = " + y;
-            // console.time(processName);
-
-            tile.build(tileData);
-            tile.heightVersion = start_height_version;
-
-            assert.equal(tile.resolution.getValue(), tile_resolution, 'tile resolution has changed');
-
-            this.stitchTile(x, y, tile);
-
-            //refit the bvh
-            tile.external_bvh.write_bounds();
-
-            tile.isBuilt = true;
-            tile.isBuildInProgress = false;
-
-            //invoke callbacks
-            tile.onBuilt.send1(tile);
-
-            // console.timeEnd(processName);
-
-            this.on.tileBuilt.send1(tile);
-
-            resolve(tile);
-        }, (reason) => {
-
-            tile.isBuilt = false;
-            tile.isBuildInProgress = false;
-
-            reject(reason);
-
-        });
-    }
-}
-
-export default TerrainTileManager;
-
+import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
+import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.js";
+import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { assert } from "../../../../core/assert.js";
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { bvh_query_leaves_ray } from "../../../../core/bvh2/bvh3/query/bvh_query_leaves_ray.js";
+import { isArrayEqualStrict } from "../../../../core/collection/array/isArrayEqualStrict.js";
+import Signal from '../../../../core/events/signal/Signal.js';
+import { aabb2_intersects_aabb2 } from "../../../../core/geom/2d/aabb/aabb2_intersects_aabb2.js";
+import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";
+import Vector2 from '../../../../core/geom/Vector2.js';
+import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
+import { max2 } from "../../../../core/math/max2.js";
+import { min2 } from "../../../../core/math/min2.js";
+import ObservedInteger from "../../../../core/model/ObservedInteger.js";
+
+import TerrainTile from './TerrainTile.js';
+
+/**
+ *
+ * @type {number[]}
+ */
+const scratch_array = [];
+const scratch_contact = new SurfacePoint3();
+
+/**
+ * Largest whole number of grid cells that fits inside a per-tile vertex budget along one tile edge,
+ * never more than the requested edge and never less than a single cell.
+ *
+ * A single grid cell is the smallest tile there is, so a resolution fine enough that one cell alone
+ * blows the budget cannot be honoured and the budget is exceeded.
+ *
+ * @param {number} max_edge largest acceptable edge, in grid cells
+ * @param {number} resolution vertices per grid cell along one axis
+ * @param {number} max_vertex_count budget for the whole tile
+ * @returns {number} edge length in grid cells
+ */
+function tile_edge(max_edge, resolution, max_vertex_count) {
+    const budget_edge = Math.floor(Math.sqrt(max_vertex_count) / resolution);
+
+    return max2(1, min2(max_edge, budget_edge));
+}
+
+class TerrainTileManager {
+    /**
+     *
+     * @type {TerrainTile[]}
+     */
+    tiles = [];
+
+    on = {
+        tileBuilt: new Signal(),
+        tileDestroyed: new Signal()
+    };
+
+    /**
+     * Largest tile edge, in grid cells. Tiles are the unit of frustum culling, seam stitching and
+     * rebuild-on-paint, so a coarse value is preferable -- but only up to the point where a single
+     * tile's geometry stops fitting {@link TerrainTileManager#maxTileVertexCount}, past which tiles
+     * are subdivided further. See {@link TerrainTileManager#tileEdgeX}.
+     *
+     * The last row and column of the grid are whatever is left over, so this is an upper bound and
+     * not a divisor of {@link TerrainTileManager#totalSize}.
+     *
+     * @type {Vector2}
+     */
+    maxTileSize = new Vector2(10, 10);
+
+    /**
+     * Upper bound on the number of vertices in a single tile.
+     *
+     * A tile is built in one shot -- the whole grid is allocated, sampled, normal-fitted and fed to
+     * a BVH build with no chunking anywhere -- so an unbounded tile is an unbounded allocation. At
+     * a resolution of 64 a 32x32 terrain would otherwise land in a single 4.19M-vertex tile, which
+     * costs upwards of 800MB to build and kills the renderer process outright.
+     *
+     * 65536 is the largest count that keeps the index array 16-bit
+     * (see {@link UintArrayForCount}), which caps a built tile at roughly 9MB of geometry and BVH.
+     *
+     * @type {number}
+     */
+    maxTileVertexCount = 65536;
+
+    /**
+     *
+     * @type {Vector2}
+     */
+    totalSize = new Vector2(1, 1);
+    /**
+     * Number of subdivisions per single grid cell
+     * @type {ObservedInteger}
+     */
+    resolution = new ObservedInteger(4);
+
+    /**
+     * 2D Scale of the terrain
+     * @type {Vector2}
+     */
+    scale = new Vector2(1, 1);
+
+
+    /**
+     *
+     * @type {Float32Array}
+     * @private
+     */
+    __transform = new Float32Array(16);
+
+    /**
+     * @readonly
+     * @type {BVH}
+     */
+    bvh = new BVH();
+
+    /**
+     *
+     * @type {NumericInterval}
+     */
+    heightRange = new NumericInterval(0, 0);
+
+    /**
+     * Version of the height snapshot {@link TerrainTileManager#buildWorker} currently holds, as
+     * handed over by {@link TerrainTileManager#setHeightVersion}. `-1` until the first snapshot is
+     * shipped, at which point no tile can have been built yet.
+     *
+     * The worker builds tiles from its own copy of the height field, so main-thread height writes
+     * are invisible to it until a new snapshot is sent. This is what a built tile is measured
+     * against to tell "built from the heights that are current" from "built from whatever the
+     * worker happened to hold at the time".
+     *
+     * @type {number}
+     */
+    heightVersion = -1;
+
+    /**
+     * The manager owns tile geometry and the streaming that keeps it current; how a tile is shaded
+     * is the renderer's. It used to hold a material and push it onto every tile's mesh, which is
+     * what made a tile grid something only one renderer could draw.
+     *
+     * @param {WorkerProxy} buildWorker
+     */
+    constructor(
+        {
+            buildWorker
+        }
+    ) {
+        /**
+         *
+         * @type {WorkerProxy}
+         */
+        this.buildWorker = buildWorker;
+    }
+
+    set transform(m4) {
+        if (isArrayEqualStrict(m4, this.__transform)) {
+            // no change
+            return;
+        }
+
+        array_copy(m4, 0, this.__transform, 0, 16);
+
+        this.traverse(t => {
+            t.transform = m4;
+        });
+    }
+
+    get transform() {
+        return this.__transform;
+    }
+
+    /**
+     * Record the height snapshot the build worker has just been handed, and drop every tile whose
+     * geometry describes an older one.
+     *
+     * Invalidated tiles keep their identity, position and place in the BVH -- only their geometry
+     * is stale -- so they are marked unbuilt rather than destroyed, and the ordinary build paths
+     * ({@link TerrainTileManager#obtain}, the renderer's visible-tile sweep) bring them back with
+     * the current heights.
+     *
+     * Must be called at the point the snapshot is *submitted* to the worker, not when the worker
+     * acknowledges it: the worker serves requests in submission order, so every tile build
+     * submitted from here on already sees the new heights.
+     *
+     * @param {number} version
+     */
+    setHeightVersion(version) {
+        assert.isNumber(version, 'version');
+
+        if (version === this.heightVersion) {
+            // worker already holds this snapshot, every built tile is measured against it
+            return;
+        }
+
+        this.heightVersion = version;
+
+        const tiles = this.tiles;
+
+        const n = tiles.length;
+
+        for (let i = 0; i < n; i++) {
+            const tile = tiles[i];
+
+            if (tile.isBuilt && tile.heightVersion !== version) {
+                tile.isBuilt = false;
+            }
+        }
+    }
+
+    /**
+     *
+     * @param {number} min_height
+     * @param {number} max_height
+     */
+    setHeightRange(min_height, max_height) {
+        assert.isNumber(min_height, 'min_height');
+        assert.notNaN(min_height, 'min_height');
+
+        assert.isNumber(max_height, 'max_height');
+        assert.notNaN(max_height, 'max_height');
+
+        this.heightRange.set(min_height, max_height);
+
+        const tiles = this.tiles;
+
+        const n = tiles.length;
+
+        for (let i = 0; i < n; i++) {
+            const terrainTile = tiles[i];
+
+            if (
+                !terrainTile.isBuilt
+                && !terrainTile.isBuildInProgress
+            ) {
+
+                const bb = terrainTile.external_bvh;
+
+                bb.bounds[1] = min_height;
+                bb.bounds[4] = max_height;
+
+                bb.write_bounds();
+
+            }
+
+        }
+    }
+
+    initialize() {
+        this.destroyTiles();
+
+        this.initializeTiles();
+    }
+
+    /**
+     *
+     * @param {(tile: TerrainTile) => void} callback
+     * @param {*} [thisArg]
+     */
+    traverse(callback, thisArg) {
+        const tiles = this.tiles;
+        let tile;
+        let i = 0;
+        const il = tiles.length;
+        for (; i < il; i++) {
+            tile = tiles[i];
+            callback.call(thisArg, tile);
+        }
+    }
+
+    destroyTiles() {
+
+        //destroy all existing tiles
+        const tiles = this.tiles;
+        const tile_count = tiles.length;
+
+        console.warn(`#destroyTiles tile_count=${tile_count}`);
+
+        for (let i = 0; i < tile_count; i++) {
+            const tile = tiles[i];
+
+            tile.external_bvh.unlink();
+            tile.dispose();
+
+        }
+
+        tiles.splice(0, tile_count);
+
+        //clear out BVH
+        this.bvh.release_all();
+
+    }
+
+    /**
+     * Rebuild all tiles
+     */
+    rebuild() {
+        this.destroyTiles();
+
+        this.initializeTiles();
+    }
+
+    /**
+     * Rebuild tiles that overlap rectangular region of the overall terrain defined by normalized coordinates (UV space)
+     * @param {number} u0
+     * @param {number} v0
+     * @param {number} u1
+     * @param {number} v1
+     */
+    rebuildTilesByUV(
+        u0, v0,
+        u1, v1
+    ) {
+
+        const size = this.totalSize;
+
+        const tx0 = u0 * size.x;
+        const tx1 = u1 * size.x;
+
+        const ty0 = v0 * size.y;
+        const ty1 = v1 * size.y;
+
+        const dirty_tiles = this.getRawTilesOverlappingRectangle(tx0 - 1, ty0 - 1, tx1 + 1, ty1 + 1);
+
+        const dirty_count = dirty_tiles.length;
+
+        for (let i = 0; i < dirty_count; i++) {
+            const tile = dirty_tiles[i];
+            tile.isBuilt = false;
+        }
+    }
+
+
+    /**
+     *
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     * @returns {TerrainTile[]}
+     */
+    getRawTilesOverlappingRectangle(x0, y0, x1, y1) {
+        /**
+         *
+         * @type {TerrainTile[]}
+         */
+        const result = [];
+
+        const terrainTiles = this.tiles;
+
+        const n = terrainTiles.length;
+
+        for (let i = 0; i < n; i++) {
+            const tile = terrainTiles[i];
+
+            const tx0 = tile.position.x;
+            const ty0 = tile.position.y;
+
+            const tx1 = tx0 + tile.size.x;
+            const ty1 = ty0 + tile.size.y;
+            if (
+                aabb2_intersects_aabb2(
+                    x0, y0, x1, y1,
+                    tx0, ty0, tx1, ty1
+                )
+            ) {
+                result.push(tile);
+            }
+        }
+
+        return result;
+    }
+
+    initializeTiles() {
+        const total_size = this.totalSize;
+
+        const tile_size_x = this.tileEdgeX;
+        const tile_size_y = this.tileEdgeY;
+
+        const tiles = this.tiles;
+
+        if (tiles.length > 0) {
+            throw new Error(`There are already ${tiles.length} initialized tiles, those must be destroyed before initialization can happen`);
+        }
+
+        //populate tiles
+        const tile_resolution_y = this.gridHeight;
+        const tile_resolution_x = this.gridWidth;
+
+        for (let y = 0; y < tile_resolution_y; y++) {
+
+            const tY = y < tile_resolution_y - 1 ? tile_size_y : (total_size.y - tile_size_y * y);
+
+            for (let x = 0; x < tile_resolution_x; x++) {
+
+                const tX = x < tile_resolution_x - 1 ? tile_size_x : (total_size.x - tile_size_x * x);
+
+                const tile = new TerrainTile();
+                const index = y * tile_resolution_x + x;
+                tiles[index] = tile;
+
+                tile.gridPosition.set(x, y);
+
+                tile.size.set(tX, tY);
+                tile.position.set(tile_size_x * x, tile_size_y * y);
+                tile.scale.copy(this.scale);
+                tile.resolution.copy(this.resolution);
+
+                tile.setInitialHeightBounds(this.heightRange.min, this.heightRange.max);
+                tile.computeBoundingBox();
+
+                tile.external_bvh.link(this.bvh, index);
+            }
+        }
+
+    }
+
+    /**
+     *
+     * @param {number} x Tile X coordinate
+     * @param {number} y Tile Y coordinate
+     * @returns {number}
+     */
+    computeTileIndex(x, y) {
+        assert.isNonNegativeInteger(x, 'x');
+        assert.isNonNegativeInteger(y, 'y');
+
+        const w = this.gridWidth;
+
+        assert.ok(x < w, `x(=${x}) must be less than than width(=${w})`);
+        assert.ok(y < this.gridHeight, `y(=${y}) must be less than than height(=${this.gridHeight})`);
+
+        return y * w + x;
+    }
+
+    /**
+     * Tile edge along X, in grid cells. Derived rather than stored so that it always reflects the
+     * current {@link TerrainTileManager#resolution}; a terrain rebuilt at a coarser resolution goes
+     * back to coarser tiles.
+     *
+     * PRECONDITION, shared by {@link TerrainTileManager#gridWidth},
+     * {@link TerrainTileManager#gridHeight} and {@link TerrainTileManager#getRawTileByPosition}:
+     * these describe the grid the *current configuration* asks for, which is the grid held in
+     * {@link TerrainTileManager#tiles} only for as long as that configuration is unchanged. Writing
+     * `totalSize`, `maxTileSize`, `resolution` or `maxTileVertexCount` after tiles exist leaves the
+     * two disagreeing, and a tile lookup then reads the wrong index. Follow any such write with
+     * {@link TerrainTileManager#rebuild}.
+     *
+     * @returns {number}
+     */
+    get tileEdgeX() {
+        return tile_edge(this.maxTileSize.x, this.resolution.getValue(), this.maxTileVertexCount);
+    }
+
+    /**
+     * Tile edge along Y, in grid cells.
+     * @returns {number}
+     */
+    get tileEdgeY() {
+        return tile_edge(this.maxTileSize.y, this.resolution.getValue(), this.maxTileVertexCount);
+    }
+
+    /**
+     * Number of tiles along X. A terrain whose size is not a whole multiple of
+     * the tile size ends in a partial tile, and that tile is real, so this
+     * rounds up. Every consumer must agree on this or edge tiles fall outside
+     * whatever grid the consumer imagined.
+     * @returns {number}
+     */
+    get gridWidth() {
+        return Math.ceil(this.totalSize.x / this.tileEdgeX);
+    }
+
+    /**
+     * Number of tiles along Y.
+     * @returns {number}
+     */
+    get gridHeight() {
+        return Math.ceil(this.totalSize.y / this.tileEdgeY);
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {TerrainTile|undefined}
+     */
+    getRaw(x, y) {
+        if (
+            x < 0
+            || x >= this.gridWidth
+            || y < 0
+        ) {
+            return undefined;
+        }
+
+        const tileIndex = this.computeTileIndex(x, y);
+
+        assert.ok(tileIndex >= 0, `tileIndex(=${tileIndex}) must be >= 0`);
+        assert.ok(tileIndex <= this.tiles.length, `tileIndex(=${tileIndex}) must be <= tileCount(=${this.tiles.length})`);
+
+        return this.tiles[tileIndex];
+    }
+
+    /**
+     *
+     * @param {number} x Grid X coordinate
+     * @param {number} y Grid Y coordinate
+     * @returns {TerrainTile}
+     */
+    getRawTileByPosition(x, y) {
+        assert.isNumber(x, 'x');
+        assert.notNaN(x, 'x');
+
+        assert.isNumber(y, 'y');
+        assert.notNaN(y, 'y');
+
+        const tileX = Math.floor(x / this.tileEdgeX);
+        const tileY = Math.floor(y / this.tileEdgeY);
+
+        return this.getRaw(tileX, tileY);
+    }
+
+    /**
+     * Given world coordinates in top-down plane, where X runs along X axis and Y runs along Z axis, returns terrain tile that overlaps that 2d region
+     * @param {number} x
+     * @param {number} y
+     * @return {TerrainTile|undefined}
+     */
+    getTileByWorldPosition2D(x, y) {
+        const v3 = Float32Array.of(x, 0, y);
+
+        const world_inverse = m4_allocate();
+
+        m4_invert(world_inverse, this.transform);
+
+
+        v3_matrix4_multiply(v3, 0, v3, 0, world_inverse);
+
+        // v3 was built as (x, 0, z): index 1 is the vertical axis, which is not
+        // a grid row. The top-down plane is X/Z.
+        //
+        // getRawTileByPosition takes *grid* coordinates, and `transform` does
+        // not carry the grid scale -- tiles apply it themselves (see
+        // assignTileScale). Divide it out here, matching Terrain's own
+        // mapPointWorld2Grid.
+        return this.getRawTileByPosition(v3[0] / this.scale.x, v3[2] / this.scale.y);
+    }
+
+    /**
+     * Builds and returns the tile from world coordinates
+     * @param {number} x
+     * @param {number} y
+     * @returns {Promise<TerrainTile>}
+     */
+    obtainTileAtWorldPosition2D(x, y) {
+        assert.isNumber(x, 'x')
+        assert.notNaN(x, 'x')
+
+        assert.isNumber(y, 'y')
+        assert.notNaN(y, 'y')
+
+        const tile = this.getTileByWorldPosition2D(x, y);
+
+        return this.obtain(tile.gridPosition.x, tile.gridPosition.y);
+    }
+
+    /**
+     *
+     * @param {number} x coordinate
+     * @param {number} y coordinate
+     * @returns {Promise<TerrainTile>}
+     * @throws if no tile exists at given coordinates
+     */
+    obtain(x, y) {
+        const tile = this.getRaw(x, y);
+
+        if (tile === undefined) {
+            throw new Error(`No tile found at x=${x},y=${y}`);
+        }
+
+        tile.referenceCount++;
+
+        if (tile.isBuilt) {
+            return Promise.resolve(tile);
+
+        } else {
+
+            if (!tile.isBuildInProgress) {
+                return new Promise((resolve, reject) => this.build(x, y, resolve, reject));
+            } else {
+                return new Promise((resolve, reject) => {
+                    tile.onBuilt.addOne(resolve);
+                    tile.onDestroyed.addOne(reject);
+                });
+            }
+
+        }
+
+    }
+
+    /**
+     *
+     * @param {TerrainTile} tile
+     */
+    release(tile) {
+        if (tile.referenceCount <= 0) {
+            console.warn('Tile already has no references');
+        }
+
+        tile.referenceCount--;
+
+        if (tile.referenceCount <= 0) {
+            //potential garbage
+            tile.dispose();
+        }
+
+    }
+
+    dispose() {
+        const tiles = this.tiles;
+
+        const n = tiles.length;
+
+        for (let i = 0; i < n; i++) {
+            const t = tiles[i];
+            t.dispose();
+        }
+    }
+
+    /**
+     * Fix normals along the seams of the tile
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {TerrainTile} tile
+     */
+    stitchTile(x, y, tile) {
+
+        const n = this.collectTileNeighbours(x, y);
+
+        tile.stitchNormals(
+            n.top, n.bottom, n.left, n.right,
+            n.topLeft, n.topRight, n.bottomLeft, n.bottomRight
+        );
+    }
+
+    /**
+     * The eight tiles surrounding a grid cell, each undefined where the cell sits
+     * on the edge of the grid.
+     *
+     * Partial edge tiles are real tiles, so the neighbour grid must round up
+     * exactly as tile creation and getRaw do. Flooring it -- as this did until
+     * recently -- leaves the last row and column believing they have no
+     * neighbour on the outward side, so their seams are never stitched.
+     *
+     * @param {number} x Tile X coordinate
+     * @param {number} y Tile Y coordinate
+     * @returns {Object<string,TerrainTile|undefined>}
+     */
+    collectTileNeighbours(x, y) {
+        const gridWidth = this.gridWidth;
+        const gridHeight = this.gridHeight;
+
+        const result = {
+            top: undefined,
+            bottom: undefined,
+            left: undefined,
+            right: undefined,
+            topLeft: undefined,
+            topRight: undefined,
+            bottomLeft: undefined,
+            bottomRight: undefined
+        };
+
+        if (y > 0) {
+            result.top = this.getRaw(x, y - 1);
+
+            if (x > 0) {
+                result.topLeft = this.getRaw(x - 1, y - 1);
+            }
+
+            if (x < gridWidth - 1) {
+                result.topRight = this.getRaw(x + 1, y - 1);
+            }
+        }
+
+        if (y < gridHeight - 1) {
+            result.bottom = this.getRaw(x, y + 1);
+
+            if (x > 0) {
+                result.bottomLeft = this.getRaw(x - 1, y + 1);
+            }
+
+            if (x < gridWidth - 1) {
+                result.bottomRight = this.getRaw(x + 1, y + 1);
+            }
+        }
+
+        if (x > 0) {
+            result.left = this.getRaw(x - 1, y);
+        }
+
+        if (x < gridWidth - 1) {
+            result.right = this.getRaw(x + 1, y);
+        }
+
+        return result;
+    }
+
+    /**
+     *
+     * @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
+    ) {
+
+        const hit_count = bvh_query_leaves_ray(
+            scratch_array, 0,
+            this.bvh,
+            this.bvh.root,
+            originX, originY, originZ,
+            directionX, directionY, directionZ
+        );
+
+        let closest_hit_distance = Number.POSITIVE_INFINITY;
+        let hit_found = false;
+
+        for (let i = 0; i < hit_count; i++) {
+            const node_id = scratch_array[i];
+
+            const tile_index = this.bvh.node_get_user_data(node_id);
+
+            const tile = this.tiles[tile_index];
+
+            if (!tile.isBuilt) {
+                continue;
+            }
+
+            const tile_hit_found = tile.raycastFirstSync(
+                scratch_contact,
+                originX, originY, originZ,
+                directionX, directionY, directionZ
+            );
+
+            if (!tile_hit_found) {
+                continue;
+            }
+
+            hit_found = true;
+
+            const distance_sqr = scratch_contact.position._distanceSqrTo(originX, originY, originZ);
+
+            if (distance_sqr < closest_hit_distance) {
+                closest_hit_distance = distance_sqr;
+                result.copy(scratch_contact);
+            }
+        }
+
+        return hit_found;
+    }
+
+    /**
+     * TODO untested
+     * @param {SurfacePoint3} contact
+     * @param {number} x
+     * @param {number} y
+     * @return {boolean}
+     */
+    raycastVerticalFirstSync(contact, x, y) {
+        // console.log('+ raycastVerticalFirstSync');
+        const r = this.raycastFirstSync(contact, x, -10000, y, 0, 1, 0);
+        // console.log('- raycastVerticalFirstSync');
+        return r;
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {(tile: TerrainTile) => void} resolve
+     * @param {(reason: *) => void} reject
+     */
+    build(x, y, resolve, reject) {
+
+        assert.isFunction(resolve, 'resolve');
+        assert.isFunction(reject, 'reject');
+
+        const tile_index = this.computeTileIndex(x, y);
+
+        const tile = this.tiles[tile_index];
+
+        if (tile.isBuildInProgress) {
+            throw new Error('Tile is already in process of being built');
+        }
+
+        const start_version = tile.version;
+        const start_height_version = this.heightVersion;
+
+        tile.isBuilt = false;
+        tile.isBuildInProgress = true;
+
+        const tile_resolution = tile.resolution.getValue();
+
+        this.buildWorker.buildTile(
+            tile.position.toJSON(),
+            tile.size.toJSON(),
+            tile.scale.toJSON(),
+            this.totalSize.toJSON(),
+            tile_resolution
+        ).then((tileData) => {
+
+            //check that the tile under index is still the same tile
+            if (this.tiles[tile_index] !== tile) {
+                //the original tile was destroyed
+                reject('Original tile was destroyed during build process');
+                return;
+            }
+
+            if (tile.version !== start_version) {
+                reject(`Tile version changed, likely due to concurrent build request. Expected version ${start_version}, actual version ${tile.version}`);
+                return;
+            }
+
+            if (!tile.isBuildInProgress) {
+                if (tile.isBuilt) {
+                    // tile already built
+                    resolve(tile);
+                    return;
+                } else {
+
+                    reject('Build request has been cancelled');
+                    return;
+                }
+            }
+
+            if (this.heightVersion !== start_height_version) {
+                // heights moved on while this tile was in the worker, so the geometry that came
+                // back describes a height field that no longer exists. Build it again; the worker
+                // now holds the current snapshot, so the next attempt lands on the right heights.
+                tile.isBuildInProgress = false;
+
+                this.build(x, y, resolve, reject);
+                return;
+            }
+
+            // const processName = 'building tile x = ' + x + ", y = " + y;
+            // console.time(processName);
+
+            tile.build(tileData);
+            tile.heightVersion = start_height_version;
+
+            assert.equal(tile.resolution.getValue(), tile_resolution, 'tile resolution has changed');
+
+            this.stitchTile(x, y, tile);
+
+            //refit the bvh
+            tile.external_bvh.write_bounds();
+
+            tile.isBuilt = true;
+            tile.isBuildInProgress = false;
+
+            //invoke callbacks
+            tile.onBuilt.send1(tile);
+
+            // console.timeEnd(processName);
+
+            this.on.tileBuilt.send1(tile);
+
+            resolve(tile);
+        }, (reason) => {
+
+            tile.isBuilt = false;
+            tile.isBuildInProgress = false;
+
+            reject(reason);
+
+        });
+    }
+}
+
+export default TerrainTileManager;
+