@woosh/meep-engine 2.167.0 → 2.168.1

package/src/engine/graphics/ecs/trail3d/Trail3DSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3DSystem.js"],"names":[],"mappings":";AAyBA;IAiCI;;;OAGG;IACH,4BAkBC;IAtDD,oDAAoC;IAEpC,+DAEE;IAEF;;OAEG;IACH,WAFU,0BAA0B,CAES;IAiB7C;;;OAGG;IACH,YAAgB;IAeZ;;OAEG;IACH,UAFU,cAAc,CAEO;IAE/B;;OAEG;IACH,aAFU,cAAY,IAAI,CAEH;IAG3B,2CAmBC;IAED,4CAIC;IA2DD;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,YACT,MAAM,QAgBhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAkCnB;IAED,6BAWC;;CACJ;uBAlPsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}
+{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3DSystem.js"],"names":[],"mappings":";AAsDA;IAiCI;;;OAGG;IACH,4BAkBC;IAtDD,oDAAoC;IAEpC,+DAEE;IAEF;;OAEG;IACH,WAFU,0BAA0B,CAES;IAiB7C;;;OAGG;IACH,YAAgB;IAeZ;;OAEG;IACH,UAFU,cAAc,CAEO;IAE/B;;OAEG;IACH,aAFU,cAAY,IAAI,CAEH;IAG3B,2CAmBC;IAED,4CAIC;IA4DD;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,YACT,MAAM,QAgBhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAiCnB;IAED,6BAWC;;CACJ;uBA/QsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}

package/src/engine/graphics/ecs/trail3d/Trail3DSystem.js

@@ -1,253 +1,282 @@
-import { assert } from "../../../../core/assert.js";
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import { bvh_query_depth_range_in_frustum } from "../../../../core/bvh2/bvh3/query/bvh_query_depth_range_in_frustum.js";
-import Vector3 from '../../../../core/geom/Vector3.js';
-import { clamp } from "../../../../core/math/clamp.js";
-import { max2 } from "../../../../core/math/max2.js";
-import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
-import { System } from '../../../ecs/System.js';
-import { Transform } from '../../../ecs/transform/Transform.js';
-import { Reference } from "../../../reference/v2/Reference.js";
-import { GraphicsEngine } from "../../GraphicsEngine.js";
-import { make_bvh_visibility_builder } from "../../render/make_bvh_visibility_builder.js";
-import {
-    TUBE_ATTRIBUTE_ADDRESS_AGE,
-    TUBE_ATTRIBUTE_ADDRESS_UV_V
-} from "../../trail/tube/tube_attributes_spec.js";
-import { TubeXFixedPhysicsSimulator } from "../../trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
-import { TubeXPlugin } from "../../trail/tube/TubeXPlugin.js";
-
-import Trail3D from './Trail3D.js';
-import { Trail3DFlags } from "./Trail3DFlags.js";
-
-const v3Temp1 = new Vector3();
-
-class Trail3DSystem extends System {
-    dependencies = [Trail3D, Transform];
-
-    components_used = [
-        ResourceAccessSpecification.from(Trail3D, ResourceAccessKind.Write)
-    ];
-
-    /**
-     * @type {TubeXFixedPhysicsSimulator}
-     */
-    simulator = new TubeXFixedPhysicsSimulator();
-
-    /**
-     * @type {Reference<TubeXPlugin>}
-     */
-    #tube_plugin = Reference.NULL;
-
-    /**
-     * @type {number}
-     */
-    #timeDelta = 0;
-
-    /**
-     * @type {Engine}
-     */
-    #engine = null;
-
-    /**
-     * @private
-     * @type {BVH}
-     */
-    bvh = new BVH();
-
-    /**
-     * @param {Engine} engine
-     * @constructor
-     */
-    constructor(engine) {
-        super();
-
-        assert.defined(engine, 'engine');
-        assert.notNull(engine, 'engine');
-        assert.equal(engine.isEngine, true, 'engine.isEngine !== true');
-
-        this.#engine = engine;
-
-        /**
-         * @type {GraphicsEngine}
-         */
-        this.graphics = engine.graphics;
-
-        /**
-         * @type {RenderLayer|null}
-         */
-        this.renderLayer = null;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.renderLayer = this.graphics.layers.create('trail-3d-system');
-
-        this.renderLayer.buildVisibleSet = make_bvh_visibility_builder(
-            this.entityManager, this.bvh,
-            (destination, offset, entity, ecd) => {
-                destination[offset] = ecd.getComponent(entity, Trail3D).mesh
-                return 1;
-            }
-        );
-
-        const bvh = this.bvh;
-        this.renderLayer.compute_depth_range = (result, frustum, nx, ny, nz, c) => {
-            bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, c);
-        };
-
-        this.#tube_plugin = await this.#engine.plugins.acquire(TubeXPlugin);
-    }
-
-    async shutdown(entityManager) {
-        this.graphics.layers.remove(this.renderLayer);
-
-        this.#tube_plugin.release();
-    }
-
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     */
-    #build_trail(trail, transform) {
-        const segmentsPerSecond = 60;
-        const maxSegments = 1024;
-
-        const segment_count = Math.ceil(clamp(trail.maxAge * segmentsPerSecond, 2, maxSegments));
-
-        trail.build(segment_count);
-
-        const tube = trail.tube;
-
-        const tubes = this.#tube_plugin.getValue();
-
-        const material = tubes.obtain_material_x(trail.material);
-
-        trail.mesh.material = material;
-
-        trail.time = 0;
-        trail.trailingIndex = 0;
-        trail.timeSinceLastUpdate = 0;
-        trail.distanceSinceLastUpdate = 0;
-
-        const trail_offset = trail.offset;
-        const transform_position = transform.position;
-
-        const position_x = trail_offset.x + transform_position.x;
-        const position_y = trail_offset.y + transform_position.y;
-        const position_z = trail_offset.z + transform_position.z;
-
-        const color = trail.color;
-
-        // initialize knots. setCount has already seeded a valid default frame on every
-        // knot, so the freshly built (collapsed) tube is well-formed — a zero-length,
-        // invisible point — until the head starts moving and supplies real tangents.
-        for (let i = 0; i < segment_count; i++) {
-            const f = i / (segment_count - 1);
-
-            tube.setKnotColor(i, color.x * 255, color.y * 255, color.z * 255);
-            tube.setKnotPosition(i, position_x, position_y, position_z);
-            tube.setKnotThickness(i, trail.width);
-            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
-            // seeded age = maxAge means "already expired", so alpha follows the fade law: 0
-            tube.setKnotAlpha(i, 0);
-            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, trail.maxAge);
-        }
-
-        trail.bvh.resize(
-            position_x, position_y, position_z,
-            position_x, position_y, position_z
-        );
-
-        trail.setFlag(Trail3DFlags.Built);
-    }
-
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     * @param {number} entityId
-     */
-    link(trail, transform, entityId) {
-        // Trail3DFlags.Lit is final by link time — bake it into the material spec
-        // (the material cache key) so lit and unlit trails obtain distinct materials
-        trail.material.lit = trail.getFlag(Trail3DFlags.Lit);
-
-        if (!trail.getFlag(Trail3DFlags.Built)) {
-            this.#build_trail(trail, transform);
-        } else {
-
-            const material = this.#tube_plugin.getValue().obtain_material_x(trail.material);
-            trail.mesh.material = material;
-        }
-
-        trail.bvh.link(this.bvh, entityId);
-    }
-
-    /**
-     * @param {Trail3D} component
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(component, transform, entity) {
-
-        component.bvh.unlink();
-
-        // release resources
-        component.dispose();
-    }
-
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     */
-    updateTrailEntity(trail, transform) {
-        const timeDelta = this.#timeDelta;
-
-        /**
-         * @type {TubeX|null}
-         */
-        const tube = trail.tube;
-
-        const newPosition = v3Temp1;
-
-        newPosition.copy(trail.offset);
-        newPosition.applyMatrix4(transform.matrix);
-
-        trail.timeSinceLastUpdate += timeDelta;
-        trail.time += timeDelta;
-
-        const ageOffset = max2(0, trail.maxAge - trail.time);
-
-        this.simulator.update(tube, trail.maxAge, timeDelta, trail.color.w);
-
-        if (trail.getFlag(Trail3DFlags.Spawning)) {
-            trail.updateHead(newPosition.x, newPosition.y, newPosition.z, ageOffset);
-        }
-
-        if (trail.getFlag(Trail3DFlags.BoundsNeedUpdate)) {
-            const bvh = trail.bvh;
-
-            tube.computeBoundingBox(bvh.bounds);
-            bvh.write_bounds();
-
-            trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
-        }
-    }
-
-    update(timeDelta) {
-
-        const em = this.entityManager;
-
-        const dataset = em.dataset;
-
-        this.#timeDelta = timeDelta;
-
-        if (dataset !== null) {
-            dataset.traverseEntities([Trail3D, Transform], this.updateTrailEntity, this);
-        }
-    }
-}
-
-export default Trail3DSystem;
+import { assert } from "../../../../core/assert.js";
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { bvh_query_depth_range_in_frustum } from "../../../../core/bvh2/bvh3/query/bvh_query_depth_range_in_frustum.js";
+import Vector3 from '../../../../core/geom/Vector3.js';
+import { clamp } from "../../../../core/math/clamp.js";
+import { max2 } from "../../../../core/math/max2.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from '../../../ecs/System.js';
+import { Transform } from '../../../ecs/transform/Transform.js';
+import { Reference } from "../../../reference/v2/Reference.js";
+import { GraphicsEngine } from "../../GraphicsEngine.js";
+import { make_bvh_visibility_builder } from "../../render/make_bvh_visibility_builder.js";
+import {
+    TUBE_ATTRIBUTE_ADDRESS_AGE,
+    TUBE_ATTRIBUTE_ADDRESS_UV_V
+} from "../../trail/tube/tube_attributes_spec.js";
+import { TubeXFixedPhysicsSimulator } from "../../trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
+import { TubeXPlugin } from "../../trail/tube/TubeXPlugin.js";
+
+import Trail3D from './Trail3D.js';
+import { Trail3DFlags } from "./Trail3DFlags.js";
+
+const v3Temp1 = new Vector3();
+
+/**
+ * Separate from {@link v3Temp1}: the build path runs from `link`, the head path
+ * from `update`, and sharing one scratch across the two would couple them for no
+ * gain.
+ * @type {Vector3}
+ */
+const v3_build_position = new Vector3();
+
+/**
+ * World point the trail's head tracks: the component's {@link Trail3D#offset},
+ * which lives in the entity's LOCAL frame, carried through the entity's full
+ * transform — so it rides the entity's rotation and scales with it.
+ *
+ * Build-time seeding and the per-frame head update must agree on this. If they
+ * disagree, the freshly built tube sits collapsed somewhere the head never
+ * visits, and the head's first move draws a segment bridging the two — a
+ * one-frame streak as long as the disagreement, in a direction fixed by the
+ * offset rather than by travel.
+ *
+ * @param {Vector3} result
+ * @param {Trail3D} trail
+ * @param {Transform} transform
+ * @returns {void}
+ */
+function compute_head_position(result, trail, transform) {
+    result.copy(trail.offset);
+    result.applyMatrix4(transform.matrix);
+}
+
+class Trail3DSystem extends System {
+    dependencies = [Trail3D, Transform];
+
+    components_used = [
+        ResourceAccessSpecification.from(Trail3D, ResourceAccessKind.Write)
+    ];
+
+    /**
+     * @type {TubeXFixedPhysicsSimulator}
+     */
+    simulator = new TubeXFixedPhysicsSimulator();
+
+    /**
+     * @type {Reference<TubeXPlugin>}
+     */
+    #tube_plugin = Reference.NULL;
+
+    /**
+     * @type {number}
+     */
+    #timeDelta = 0;
+
+    /**
+     * @type {Engine}
+     */
+    #engine = null;
+
+    /**
+     * @private
+     * @type {BVH}
+     */
+    bvh = new BVH();
+
+    /**
+     * @param {Engine} engine
+     * @constructor
+     */
+    constructor(engine) {
+        super();
+
+        assert.defined(engine, 'engine');
+        assert.notNull(engine, 'engine');
+        assert.equal(engine.isEngine, true, 'engine.isEngine !== true');
+
+        this.#engine = engine;
+
+        /**
+         * @type {GraphicsEngine}
+         */
+        this.graphics = engine.graphics;
+
+        /**
+         * @type {RenderLayer|null}
+         */
+        this.renderLayer = null;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.renderLayer = this.graphics.layers.create('trail-3d-system');
+
+        this.renderLayer.buildVisibleSet = make_bvh_visibility_builder(
+            this.entityManager, this.bvh,
+            (destination, offset, entity, ecd) => {
+                destination[offset] = ecd.getComponent(entity, Trail3D).mesh
+                return 1;
+            }
+        );
+
+        const bvh = this.bvh;
+        this.renderLayer.compute_depth_range = (result, frustum, nx, ny, nz, c) => {
+            bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, c);
+        };
+
+        this.#tube_plugin = await this.#engine.plugins.acquire(TubeXPlugin);
+    }
+
+    async shutdown(entityManager) {
+        this.graphics.layers.remove(this.renderLayer);
+
+        this.#tube_plugin.release();
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     */
+    #build_trail(trail, transform) {
+        const segmentsPerSecond = 60;
+        const maxSegments = 1024;
+
+        const segment_count = Math.ceil(clamp(trail.maxAge * segmentsPerSecond, 2, maxSegments));
+
+        trail.build(segment_count);
+
+        const tube = trail.tube;
+
+        const tubes = this.#tube_plugin.getValue();
+
+        const material = tubes.obtain_material_x(trail.material);
+
+        trail.mesh.material = material;
+
+        trail.time = 0;
+        trail.trailingIndex = 0;
+        trail.timeSinceLastUpdate = 0;
+        trail.distanceSinceLastUpdate = 0;
+
+        // seed exactly where updateTrailEntity will place the head, or the first
+        // head move bridges the gap with a visible segment
+        compute_head_position(v3_build_position, trail, transform);
+
+        const position_x = v3_build_position.x;
+        const position_y = v3_build_position.y;
+        const position_z = v3_build_position.z;
+
+        const color = trail.color;
+
+        // initialize knots. setCount has already seeded a valid default frame on every
+        // knot, so the freshly built (collapsed) tube is well-formed — a zero-length,
+        // invisible point — until the head starts moving and supplies real tangents.
+        for (let i = 0; i < segment_count; i++) {
+            const f = i / (segment_count - 1);
+
+            tube.setKnotColor(i, color.x * 255, color.y * 255, color.z * 255);
+            tube.setKnotPosition(i, position_x, position_y, position_z);
+            tube.setKnotThickness(i, trail.width);
+            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
+            // seeded age = maxAge means "already expired", so alpha follows the fade law: 0
+            tube.setKnotAlpha(i, 0);
+            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, trail.maxAge);
+        }
+
+        trail.bvh.resize(
+            position_x, position_y, position_z,
+            position_x, position_y, position_z
+        );
+
+        trail.setFlag(Trail3DFlags.Built);
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entityId
+     */
+    link(trail, transform, entityId) {
+        // Trail3DFlags.Lit is final by link time — bake it into the material spec
+        // (the material cache key) so lit and unlit trails obtain distinct materials
+        trail.material.lit = trail.getFlag(Trail3DFlags.Lit);
+
+        if (!trail.getFlag(Trail3DFlags.Built)) {
+            this.#build_trail(trail, transform);
+        } else {
+
+            const material = this.#tube_plugin.getValue().obtain_material_x(trail.material);
+            trail.mesh.material = material;
+        }
+
+        trail.bvh.link(this.bvh, entityId);
+    }
+
+    /**
+     * @param {Trail3D} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component, transform, entity) {
+
+        component.bvh.unlink();
+
+        // release resources
+        component.dispose();
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     */
+    updateTrailEntity(trail, transform) {
+        const timeDelta = this.#timeDelta;
+
+        /**
+         * @type {TubeX|null}
+         */
+        const tube = trail.tube;
+
+        const newPosition = v3Temp1;
+
+        compute_head_position(newPosition, trail, transform);
+
+        trail.timeSinceLastUpdate += timeDelta;
+        trail.time += timeDelta;
+
+        const ageOffset = max2(0, trail.maxAge - trail.time);
+
+        this.simulator.update(tube, trail.maxAge, timeDelta, trail.color.w);
+
+        if (trail.getFlag(Trail3DFlags.Spawning)) {
+            trail.updateHead(newPosition.x, newPosition.y, newPosition.z, ageOffset);
+        }
+
+        if (trail.getFlag(Trail3DFlags.BoundsNeedUpdate)) {
+            const bvh = trail.bvh;
+
+            tube.computeBoundingBox(bvh.bounds);
+            bvh.write_bounds();
+
+            trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
+        }
+    }
+
+    update(timeDelta) {
+
+        const em = this.entityManager;
+
+        const dataset = em.dataset;
+
+        this.#timeDelta = timeDelta;
+
+        if (dataset !== null) {
+            dataset.traverseEntities([Trail3D, Transform], this.updateTrailEntity, this);
+        }
+    }
+}
+
+export default Trail3DSystem;