@woosh/meep-engine 3.28.0 → 3.30.0

package/src/engine/ecs/terrain/ecs/cling/ClingToTerrainSystem.js

@@ -1,360 +1,366 @@
-import { assert } from "../../../../../core/assert.js";
-import { Deque } from "../../../../../core/collection/queue/Deque.js";
-import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
-import Quaternion from "../../../../../core/geom/Quaternion.js";
-
-import Vector3 from '../../../../../core/geom/Vector3.js';
-import { clamp01 } from "../../../../../core/math/clamp01.js";
-import { EPSILON } from "../../../../../core/math/EPSILON.js";
-import { min2 } from "../../../../../core/math/min2.js";
-import { ResourceAccessKind } from "../../../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../../../core/model/ResourceAccessSpecification.js";
-import { System } from '../../../System.js';
-import { Transform64 } from '../../../transform/Transform64.js';
-import { obtainTerrain } from "../../util/obtainTerrain.js";
-import Terrain from "../Terrain.js";
-
-import ClingToTerrain from './ClingToTerrain.js';
-import { TRANSFORM64_EVENT_CHANGE } from "../../../transform/TRANSFORM64_EVENT_CHANGE.js";
-import { t64_announce_change } from "../../../transform/t64_announce_change.js";
-import { t64_read_rotation } from "../../../transform/t64_read_rotation.js";
-import { t64_read_translation } from "../../../transform/t64_read_translation.js";
-
-
-/**
- *
- * @type {SurfacePoint3}
- */
-const temp_sp = new SurfacePoint3();
-
-/**
- * @param {{update:function,ecd:EntityComponentDataset,entity:number}} datum
- */
-function deregister(datum) {
-    datum.ecd.removeEntityEventListener(
-        datum.entity, TRANSFORM64_EVENT_CHANGE, datum.update
-    );
-}
-
-/**
- * How many entities can be updated in a single tick, this is useful for performance optimization.
- * If you have a large number of entities that need to be updated, updates can be executed over several ticks
- * @readonly
- * @type {number}
- */
-const DEFAULT_UPDATE_LIMIT = 1024;
-
-class ClingToTerrainSystem extends System {
-
-
-    dependencies = [ClingToTerrain, Transform64];
-
-
-    components_used = [
-        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
-        ResourceAccessSpecification.from(Terrain, ResourceAccessKind.Read)
-    ];
-
-    /**
-     *
-     * @type {Deque<number>}
-     */
-    updateQueue = new Deque();
-
-    data = [];
-
-    /**
-     * How many entities can be updated in a single tick, this is useful for performance optimization, if you have a large number of entities that need to be updated, updates can be executed over several ticks
-     * @type {number}
-     */
-    updateBatchLimit = DEFAULT_UPDATE_LIMIT;
-
-    /**
-     *
-     * @param {number} entity
-     */
-    requestUpdate(entity) {
-        if (!this.updateQueue.has(entity)) {
-            //queue up update
-            this.updateQueue.addLast(entity);
-        }
-    }
-
-    /**
-     *
-     * @param {Transform64} transform
-     * @param {ClingToTerrain} cling
-     * @param {number} entityId
-     */
-    link(cling, transform, entityId) {
-
-        const ecd = this.entityManager.dataset;
-
-        /*
-         The transform used to carry three signals and this listened to two of them. It carries
-         none now, so the interest is registered against the entity and the transform's own change
-         event: one listener where there were two, and it hears a write from anywhere - a spawner,
-         a script, a physics step - rather than only one that went through a sub-object.
-        */
-        const update = () => this.requestUpdate(entityId);
-
-        this.data[entityId] = {
-            update,
-            transform,
-            component: cling,
-            ecd,
-            entity: entityId
-        };
-
-        ecd.addEntityEventListener(entityId, TRANSFORM64_EVENT_CHANGE, update);
-
-        this.requestUpdate(entityId);
-    }
-
-    /**
-     *
-     * @param {Transform64} transform
-     * @param {ClingToTerrain} cling
-     * @param {number} entityId
-     */
-    unlink(cling, transform, entityId) {
-        const datum = this.data[entityId];
-
-        if (datum === undefined) {
-            console.error(`Tried to remove entity ${entityId}, but it was not registered. This is an inconsistency bug.`, transform, cling, `component dump:`, this.entityManager.getComponents(entityId));
-            return;
-        }
-
-        deregister(datum);
-
-        delete this.data[entityId];
-
-        //clear update request if one is pending
-        this.updateQueue.remove(entityId);
-    }
-
-    update(timeDelta) {
-        const em = this.entityManager;
-
-        /**
-         *
-         * @type {EntityComponentDataset}
-         */
-        const dataset = em.dataset;
-
-        if (dataset === null) {
-            //no dataset attached
-            return;
-        }
-
-        const updateCandidates = this.updateQueue;
-
-        const terrain = obtainTerrain(dataset);
-
-        if (terrain === null) {
-            return;
-        }
-
-        const batchSize = min2(
-            updateCandidates.size(),
-            this.updateBatchLimit
-        );
-
-        for (let i = 0; i < batchSize; i++) {
-            const entity = updateCandidates.removeFirst();
-
-            const c = this.data[entity];
-
-            if (c === undefined) {
-                /*
-                    this should never happen as update queue is cleaned up when component is removed
-                    the entity is gone
-                 */
-
-                //console.warn("ClingToTerrain component was in the update queue, but no data found. Skipping");
-                continue;
-            }
-
-            const position_updated = doCling(c, terrain, timeDelta);
-
-            if (!position_updated) {
-                // no change, move back to update candidates
-                this.requestUpdate(entity);
-            }
-        }
-    }
-}
-
-
-const v3_temp = new Vector3();
-const v3_forward = new Vector3();
-const v3_up = new Vector3();
-
-const q_temp = new Quaternion();
-
-/**
- * The pose of whichever entity is being clung right now, read out of its transform.
- *
- * @type {Vector3}
- */
-const scratch_position = new Vector3();
-
-/**
- * @type {Quaternion}
- */
-const scratch_rotation = new Quaternion();
-
-/**
- * TODO look into "swing-twist decomposition"
- * @param {Quaternion} rotation
- * @param {Vector3} direction
- * @param {number} angularLimit
- * @param up
- * @param forward
- */
-export function alignToVector(rotation, direction, angularLimit, up = Vector3.up, forward = Vector3.forward) {
-    assert.isNumber(angularLimit, 'angularLimit');
-    assert.notNaN(angularLimit, 'angularLimit');
-
-    //compute old facing direction vector
-    v3_forward.copy(forward);
-
-    v3_forward.applyQuaternion(rotation);
-
-    //compute perpendicular vector between old and desired alignment
-    v3_temp.crossVectors(direction, v3_forward);
-
-    //compute new facing vector that is perpendicular to alignment direction
-    v3_temp.crossVectors(v3_temp, direction);
-
-    q_temp.lookRotation(v3_temp, direction);
-
-    v3_up.copy(up);
-
-    v3_up.applyQuaternion(rotation);
-
-    const angle = v3_up.angleTo(direction);
-
-    assert.notNaN(angle, 'angle');
-
-    if (angle === 0) {
-        //no change
-        return;
-    }
-
-    const t = clamp01(angularLimit / angle);
-
-    // TODO Consider replacing this with slerp
-    rotation.lerp(q_temp, t);
-}
-
-
-/**
- *
- * @param {Vector3} point
- * @param {Transform64} t
- * @param {Vector3} normal
- * @param {ClingToTerrain} cling
- * @param {number} timeDelta
- */
-function processRaycastHit(point, t, normal, cling, timeDelta, el) {
-    assert.defined(point, 'point');
-    assert.equal(point.isVector3, true, 'point.isVector3 !== true');
-    assert.isNumber(timeDelta, 'timeDelta');
-
-    // filled by the caller, which had to read them to decide there was anything to do
-    const position = scratch_position;
-    const rotation = scratch_rotation;
-
-    const hitDistance = position.distanceTo(point);
-
-    //cache current position
-    cling.__lastPosition.copy(position);
-    cling.__lastRotation.copy(rotation);
-
-    let moved = false;
-
-    if (hitDistance > EPSILON) {
-        t.setTranslation(position.x, point.y, position.z);
-
-        moved = true;
-    }
-
-    let angularLimit;
-
-    if (Number.isFinite(cling.rotationSpeed)) {
-        angularLimit = cling.rotationSpeed * timeDelta;
-    } else {
-        angularLimit = Number.POSITIVE_INFINITY;
-    }
-
-    if (cling.normalAlign) {
-        alignToVector(rotation, normal, angularLimit);
-
-        if (
-            rotation.x !== t.rotation_x || rotation.y !== t.rotation_y
-            || rotation.z !== t.rotation_z || rotation.w !== t.rotation_w
-        ) {
-            t.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
-
-            // the rotation is the only write that leaves the matrix behind
-            t.updateMatrix();
-
-            moved = true;
-        }
-    }
-
-    /*
-     Announced only when something actually changed. The system is listening to this entity itself,
-     so an announcement it did not earn would queue the entity again, find nothing to do, and queue
-     it again - a spin that never settles.
-    */
-    if (moved) {
-        t64_announce_change(el.ecd, el.entity);
-    }
-}
-
-/**
- *
- * @param {{component:ClingToTerrain,transform:Transform}} el
- * @param {Terrain} terrain
- * @param {number} timeDelta
- * @returns {boolean} whether position was updated or not
- */
-function doCling(el, terrain, timeDelta) {
-    /**
-     * @type {ClingToTerrain}
-     */
-    const cling = el.component;
-
-    /**
-     *
-     * @type {Transform64}
-     */
-    const t = el.transform;
-
-    // read out once; the comparison, the cast and the write below all want the same numbers, and
-    // reading them through the component's view accessors would allocate two arrays per entity
-    t64_read_translation(scratch_position, t);
-    t64_read_rotation(scratch_rotation, t);
-
-    if (
-        cling.__lastPosition.roughlyEquals(scratch_position, 0.001)
-        && cling.__lastRotation.roughlyEquals(scratch_rotation, 0.0001)
-    ) {
-        //do nothing, cached position matches with existing position
-        return false;
-    }
-
-    const hit_found = terrain.raycastVerticalFirstSync(
-        temp_sp, scratch_position.x, scratch_position.z
-    );
-
-    if (hit_found) {
-        processRaycastHit(temp_sp.position, t, temp_sp.normal, cling, timeDelta, el);
-    }
-
-    return hit_found;
-}
-
-export default ClingToTerrainSystem;
+import { assert } from "../../../../../core/assert.js";
+import { Deque } from "../../../../../core/collection/queue/Deque.js";
+import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
+import Quaternion from "../../../../../core/geom/Quaternion.js";
+
+import Vector3 from '../../../../../core/geom/Vector3.js';
+import { clamp01 } from "../../../../../core/math/clamp01.js";
+import { EPSILON } from "../../../../../core/math/EPSILON.js";
+import { min2 } from "../../../../../core/math/min2.js";
+import { ResourceAccessKind } from "../../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../../core/model/ResourceAccessSpecification.js";
+import { System } from '../../../System.js';
+import { Transform64 } from '../../../transform/Transform64.js';
+import { obtainTerrain } from "../../util/obtainTerrain.js";
+import Terrain from "../Terrain.js";
+
+import ClingToTerrain from './ClingToTerrain.js';
+import { TRANSFORM64_EVENT_CHANGE } from "../../../transform/TRANSFORM64_EVENT_CHANGE.js";
+import { t64_announce_change } from "../../../transform/t64_announce_change.js";
+import { t64_read_rotation } from "../../../transform/t64_read_rotation.js";
+import { t64_read_translation } from "../../../transform/t64_read_translation.js";
+
+
+/**
+ *
+ * @type {SurfacePoint3}
+ */
+const temp_sp = new SurfacePoint3();
+
+/**
+ * @param {{update:function,ecd:EntityComponentDataset,entity:number}} datum
+ */
+function deregister(datum) {
+    datum.ecd.removeEntityEventListener(
+        datum.entity, TRANSFORM64_EVENT_CHANGE, datum.update
+    );
+}
+
+/**
+ * How many entities can be updated in a single tick, this is useful for performance optimization.
+ * If you have a large number of entities that need to be updated, updates can be executed over several ticks
+ * @readonly
+ * @type {number}
+ */
+const DEFAULT_UPDATE_LIMIT = 1024;
+
+class ClingToTerrainSystem extends System {
+
+
+    dependencies = [ClingToTerrain, Transform64];
+
+
+    components_used = [
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(Terrain, ResourceAccessKind.Read)
+    ];
+
+    /**
+     *
+     * @type {Deque<number>}
+     */
+    updateQueue = new Deque();
+
+    data = [];
+
+    /**
+     * How many entities can be updated in a single tick, this is useful for performance optimization, if you have a large number of entities that need to be updated, updates can be executed over several ticks
+     * @type {number}
+     */
+    updateBatchLimit = DEFAULT_UPDATE_LIMIT;
+
+    /**
+     *
+     * @param {number} entity
+     */
+    requestUpdate(entity) {
+        if (!this.updateQueue.has(entity)) {
+            //queue up update
+            this.updateQueue.addLast(entity);
+        }
+    }
+
+    /**
+     *
+     * @param {Transform64} transform
+     * @param {ClingToTerrain} cling
+     * @param {number} entityId
+     */
+    link(cling, transform, entityId) {
+
+        const ecd = this.entityManager.dataset;
+
+        /*
+         The transform used to carry three signals and this listened to two of them. It carries
+         none now, so the interest is registered against the entity and the transform's own change
+         event: one listener where there were two, and it hears a write from anywhere - a spawner,
+         a script, a physics step - rather than only one that went through a sub-object.
+        */
+        const update = () => this.requestUpdate(entityId);
+
+        this.data[entityId] = {
+            update,
+            transform,
+            component: cling,
+            ecd,
+            entity: entityId
+        };
+
+        ecd.addEntityEventListener(entityId, TRANSFORM64_EVENT_CHANGE, update);
+
+        this.requestUpdate(entityId);
+    }
+
+    /**
+     *
+     * @param {Transform64} transform
+     * @param {ClingToTerrain} cling
+     * @param {number} entityId
+     */
+    unlink(cling, transform, entityId) {
+        const datum = this.data[entityId];
+
+        if (datum === undefined) {
+            console.error(`Tried to remove entity ${entityId}, but it was not registered. This is an inconsistency bug.`, transform, cling, `component dump:`, this.entityManager.getComponents(entityId));
+            return;
+        }
+
+        deregister(datum);
+
+        delete this.data[entityId];
+
+        //clear update request if one is pending
+        this.updateQueue.remove(entityId);
+    }
+
+    update(timeDelta) {
+        const em = this.entityManager;
+
+        /**
+         *
+         * @type {EntityComponentDataset}
+         */
+        const dataset = em.dataset;
+
+        if (dataset === null) {
+            //no dataset attached
+            return;
+        }
+
+        const updateCandidates = this.updateQueue;
+
+        const terrain = obtainTerrain(dataset);
+
+        if (terrain === null) {
+            return;
+        }
+
+        const batchSize = min2(
+            updateCandidates.size(),
+            this.updateBatchLimit
+        );
+
+        for (let i = 0; i < batchSize; i++) {
+            const entity = updateCandidates.removeFirst();
+
+            const c = this.data[entity];
+
+            if (c === undefined) {
+                /*
+                    this should never happen as update queue is cleaned up when component is removed
+                    the entity is gone
+                 */
+
+                //console.warn("ClingToTerrain component was in the update queue, but no data found. Skipping");
+                continue;
+            }
+
+            const position_updated = doCling(c, terrain, timeDelta);
+
+            if (!position_updated) {
+                // no change, move back to update candidates
+                this.requestUpdate(entity);
+            }
+        }
+    }
+}
+
+
+const v3_temp = new Vector3();
+const v3_forward = new Vector3();
+const v3_up = new Vector3();
+
+const q_temp = new Quaternion();
+
+/**
+ * The pose of whichever entity is being clung right now, read out of its transform.
+ *
+ * @type {Vector3}
+ */
+const scratch_position = new Vector3();
+
+/**
+ * @type {Quaternion}
+ */
+const scratch_rotation = new Quaternion();
+
+/**
+ * TODO look into "swing-twist decomposition"
+ * @param {Quaternion} rotation
+ * @param {Vector3} direction
+ * @param {number} angularLimit
+ * @param up
+ * @param forward
+ */
+export function alignToVector(rotation, direction, angularLimit, up = Vector3.up, forward = Vector3.forward) {
+    assert.isNumber(angularLimit, 'angularLimit');
+    assert.notNaN(angularLimit, 'angularLimit');
+
+    //compute old facing direction vector
+    v3_forward.copy(forward);
+
+    v3_forward.applyQuaternion(rotation);
+
+    //compute perpendicular vector between old and desired alignment
+    v3_temp.crossVectors(direction, v3_forward);
+
+    //compute new facing vector that is perpendicular to alignment direction
+    v3_temp.crossVectors(v3_temp, direction);
+
+    q_temp.lookRotation(v3_temp, direction);
+
+    v3_up.copy(up);
+
+    v3_up.applyQuaternion(rotation);
+
+    const angle = v3_up.angleTo(direction);
+
+    assert.notNaN(angle, 'angle');
+
+    if (angle === 0) {
+        //no change
+        return;
+    }
+
+    const t = clamp01(angularLimit / angle);
+
+    /**
+   * `slerp` and not `lerp`: a componentwise lerp neither renormalises nor takes the shortest arc,
+   * and `Transform64#setRotation` states that the quaternion is expected to be of unit length and
+   * that nothing there normalises it. A short quaternion composes into a sheared, non-orthogonal
+   * basis that `updateComponents()` then decomposes into the entity's scale and carries down every
+   * attachment below it. Measured worst case here was |q| = 0.707, against a near-antipodal normal.
+   */
+    rotation.slerp(q_temp, t);
+}
+
+
+/**
+ *
+ * @param {Vector3} point
+ * @param {Transform64} t
+ * @param {Vector3} normal
+ * @param {ClingToTerrain} cling
+ * @param {number} timeDelta
+ */
+function processRaycastHit(point, t, normal, cling, timeDelta, el) {
+    assert.defined(point, 'point');
+    assert.equal(point.isVector3, true, 'point.isVector3 !== true');
+    assert.isNumber(timeDelta, 'timeDelta');
+
+    // filled by the caller, which had to read them to decide there was anything to do
+    const position = scratch_position;
+    const rotation = scratch_rotation;
+
+    const hitDistance = position.distanceTo(point);
+
+    //cache current position
+    cling.__lastPosition.copy(position);
+    cling.__lastRotation.copy(rotation);
+
+    let moved = false;
+
+    if (hitDistance > EPSILON) {
+        t.setTranslation(position.x, point.y, position.z);
+
+        moved = true;
+    }
+
+    let angularLimit;
+
+    if (Number.isFinite(cling.rotationSpeed)) {
+        angularLimit = cling.rotationSpeed * timeDelta;
+    } else {
+        angularLimit = Number.POSITIVE_INFINITY;
+    }
+
+    if (cling.normalAlign) {
+        alignToVector(rotation, normal, angularLimit);
+
+        if (
+            rotation.x !== t.rotation_x || rotation.y !== t.rotation_y
+            || rotation.z !== t.rotation_z || rotation.w !== t.rotation_w
+        ) {
+            t.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+
+            // the rotation is the only write that leaves the matrix behind
+            t.updateMatrix();
+
+            moved = true;
+        }
+    }
+
+    /*
+     Announced only when something actually changed. The system is listening to this entity itself,
+     so an announcement it did not earn would queue the entity again, find nothing to do, and queue
+     it again - a spin that never settles.
+    */
+    if (moved) {
+        t64_announce_change(el.ecd, el.entity);
+    }
+}
+
+/**
+ *
+ * @param {{component:ClingToTerrain,transform:Transform}} el
+ * @param {Terrain} terrain
+ * @param {number} timeDelta
+ * @returns {boolean} whether position was updated or not
+ */
+function doCling(el, terrain, timeDelta) {
+    /**
+     * @type {ClingToTerrain}
+     */
+    const cling = el.component;
+
+    /**
+     *
+     * @type {Transform64}
+     */
+    const t = el.transform;
+
+    // read out once; the comparison, the cast and the write below all want the same numbers, and
+    // reading them through the component's view accessors would allocate two arrays per entity
+    t64_read_translation(scratch_position, t);
+    t64_read_rotation(scratch_rotation, t);
+
+    if (
+        cling.__lastPosition.roughlyEquals(scratch_position, 0.001)
+        && cling.__lastRotation.roughlyEquals(scratch_rotation, 0.0001)
+    ) {
+        //do nothing, cached position matches with existing position
+        return false;
+    }
+
+    const hit_found = terrain.raycastVerticalFirstSync(
+        temp_sp, scratch_position.x, scratch_position.z
+    );
+
+    if (hit_found) {
+        processRaycastHit(temp_sp.position, t, temp_sp.normal, cling, timeDelta, el);
+    }
+
+    return hit_found;
+}
+
+export default ClingToTerrainSystem;