@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +1,430 @@
+import { FLOAT32_MAX } from "../../../../core/binary/FLOAT32_MAX.js";
+import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
+import { Color } from "../../../../core/color/Color.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
+import { EPSILON } from "../../../../core/math/EPSILON.js";
+import ThreeFactory from "../../three/ThreeFactory.js";
+import { TrailSpawnMode } from "../../trail/TrailSpawnMode.js";
+import { TUBE_ATTRIBUTE_ADDRESS_AGE } from "../../trail/tube/tube_attributes_spec.js";
+import { tube_frame_transport } from "../../trail/tube/tube_frame.js";
+import { TubeX } from "../../trail/tube/TubeX.js";
+import { TubeXMaterialSpec } from "../../trail/tube/TubeXMaterialSpec.js";
+import { Trail3DFlags } from "./Trail3DFlags.js";
+
+const DEFAULT_FLAGS = Trail3DFlags.Spawning | Trail3DFlags.Aging | Trail3DFlags.BoundsNeedUpdate;
+
+const DEFAULT_MAX_AGE = 5;
+
+const DEFAULT_WIDTH = 1;
+
+const DEFAULT_RADIAL_SEGMENTS = 8;
+
+const DEFAULT_SPAWN_DISTANCE = 1;
+
+// module-static scratch — keeps updateHead allocation-free
+const v3_head_pos = new Float64Array(3);
+const v3_pred_pos = new Float64Array(3);
+const v3_pred_n = new Float64Array(3);
+const frame_out = new Float32Array(6);
+
+/**
+ * Tube-based 3D trail — the volumetric counterpart of {@link Trail2D}. Where
+ * Trail2D extrudes a screen-facing ribbon in the shader, Trail3D lays down a tube
+ * of {@link TubeX} knots, each carrying a tangent frame so the ring can be
+ * extruded around the centre-line in world space.
+ */
+class Trail3D {
+
+    /**
+     * Age at which a trail knot disappears, in seconds.
+     * @type {number}
+     */
+    maxAge = DEFAULT_MAX_AGE;
+
+    /**
+     * Tube diameter.
+     * @type {number}
+     */
+    width = DEFAULT_WIDTH;
+
+    /**
+     * Number of radial subdivisions around the tube. Higher = rounder tube. This is
+     * a build-time parameter; changing it after build has no effect until rebuilt.
+     * @type {number}
+     */
+    radialSegments = DEFAULT_RADIAL_SEGMENTS;
+
+    /**
+     * How new knots are committed behind the head.
+     * @type {TrailSpawnMode|number}
+     */
+    spawnMode = TrailSpawnMode.Time;
+
+    /**
+     * Distance the head must travel before committing a new knot, used only when
+     * {@link spawnMode} is {@link TrailSpawnMode.Distance}.
+     * @type {number}
+     */
+    spawnDistance = DEFAULT_SPAWN_DISTANCE;
+
+    /**
+     * Current simulated time since trail birth.
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * @type {number}
+     */
+    trailingIndex = 0;
+
+    /**
+     * Time elapsed since the last knot was committed.
+     * @type {number}
+     */
+    timeSinceLastUpdate = 0;
+
+    /**
+     * Distance the head has travelled since the last knot was committed.
+     * @type {number}
+     */
+    distanceSinceLastUpdate = 0;
+
+    /**
+     * @readonly
+     * @type {Color}
+     */
+    color = new Color(1, 1, 1, 1);
+
+    /**
+     * World offset.
+     * @readonly
+     * @type {Vector3}
+     */
+    offset = new Vector3();
+
+    /**
+     * transient
+     * @type {TubeX|null}
+     */
+    tube = null;
+
+    /**
+     * transient
+     * @type {Mesh|null}
+     */
+    mesh = null;
+
+    /**
+     * transient
+     * @type {TubeXMaterialSpec}
+     */
+    material = new TubeXMaterialSpec();
+
+    /**
+     * @readonly
+     * @type {BvhClient}
+     */
+    bvh = new BvhClient();
+
+    /**
+     * @private
+     * @type {Trail3DFlags|number}
+     */
+    flags = DEFAULT_FLAGS;
+
+    dispose() {
+        if (this.tube === null) {
+            // nothing to dispose
+            return;
+        }
+
+        this.tube.dispose();
+        this.tube = null;
+    }
+
+    get textureURL() {
+        return this.material.diffuse;
+    }
+
+    set textureURL(v) {
+        this.material.diffuse = v;
+    }
+
+    get depthWrite() {
+        return this.material.depthWrite;
+    }
+
+    set depthWrite(v) {
+        this.material.depthWrite = v;
+    }
+
+    /**
+     * @param {number|Trail3DFlags} flag
+     * @returns {void}
+     */
+    setFlag(flag) {
+        this.flags |= flag;
+    }
+
+    /**
+     * @param {number|Trail3DFlags} flag
+     * @returns {void}
+     */
+    clearFlag(flag) {
+        this.flags &= ~flag;
+    }
+
+    /**
+     * @param {number|Trail3DFlags} flag
+     * @param {boolean} value
+     */
+    writeFlag(flag, value) {
+        if (value) {
+            this.setFlag(flag);
+        } else {
+            this.clearFlag(flag);
+        }
+    }
+
+    /**
+     * @param {number|Trail3DFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * @param {number} segment_count
+     */
+    build(segment_count) {
+
+        const tube = new TubeX();
+
+        tube.buildGeometry();
+        tube.setCount(segment_count, this.radialSegments);
+
+        const geometry = tube.getGeometry();
+
+        const mesh = ThreeFactory.createMesh(geometry, null);
+
+        this.tube = tube;
+        this.mesh = mesh;
+    }
+
+    /**
+     * Clear the trail's geometry and reset its state.
+     */
+    clear() {
+        const tube = this.tube;
+
+        if (tube === null) {
+            // nothing to clear
+            return;
+        }
+
+        const n = tube.getCount();
+
+        for (let i = 0; i < n; i++) {
+            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, FLOAT32_MAX);
+            tube.setKnotAlpha(i, 0);
+        }
+
+        // Ages/alphas alone don't erase the tube: knot POSITIONS still trace the old
+        // path. Defer a geometry reset to the next updateHead() (the first code to
+        // know the post-clear position), which collapses the whole tube onto the head.
+        this.setFlag(Trail3DFlags.Reseed);
+    }
+
+    static fromJSON(json) {
+        const r = new Trail3D();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+
+    fromJSON({
+                 maxAge = DEFAULT_MAX_AGE,
+                 width = DEFAULT_WIDTH,
+                 radialSegments = DEFAULT_RADIAL_SEGMENTS,
+                 spawnMode = TrailSpawnMode.Time,
+                 spawnDistance = DEFAULT_SPAWN_DISTANCE,
+                 textureURL,
+                 depthWrite = false,
+                 offset = Vector3.zero,
+                 color = { r: 1, g: 1, b: 1, a: 1 }
+             }) {
+
+        this.maxAge = maxAge;
+        this.width = width;
+        this.radialSegments = radialSegments;
+        this.spawnMode = spawnMode;
+        this.spawnDistance = spawnDistance;
+        this.textureURL = textureURL;
+        this.depthWrite = depthWrite;
+
+        this.offset.fromJSON(offset);
+        this.color.fromJSON(color);
+    }
+
+    toJSON() {
+        return {
+            maxAge: this.maxAge,
+            width: this.width,
+            radialSegments: this.radialSegments,
+            spawnMode: this.spawnMode,
+            spawnDistance: this.spawnDistance,
+            color: this.color.toJSON(),
+            textureURL: this.textureURL,
+            depthWrite: this.depthWrite,
+            offset: this.offset.toJSON()
+        };
+    }
+
+    /**
+     * @param {Trail3D} other
+     */
+    equals(other) {
+        return this.textureURL === other.textureURL
+            && this.depthWrite === other.depthWrite
+            && this.width === other.width
+            && this.radialSegments === other.radialSegments
+            && this.maxAge === other.maxAge
+            && this.spawnMode === other.spawnMode
+            && this.spawnDistance === other.spawnDistance
+            && this.color.equals(other.color)
+            && this.offset.equals(other.offset)
+            ;
+    }
+
+    /**
+     * Orient the head knot's ring by parallel-transporting the frame from its
+     * predecessor (the last committed knot). No-op until the head has separated
+     * from its predecessor (e.g. right after build), preserving the existing frame.
+     * @param {number} head_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {void}
+     */
+    #updateHeadFrame(head_index, x, y, z) {
+        const tube = this.tube;
+
+        const predecessor_index = (head_index + 1) % tube.getCount();
+
+        tube.getKnotPosition(v3_pred_pos, predecessor_index);
+
+        let tx = x - v3_pred_pos[0];
+        let ty = y - v3_pred_pos[1];
+        let tz = z - v3_pred_pos[2];
+
+        const t_length = v3_length(tx, ty, tz);
+
+        if (t_length <= EPSILON) {
+            // head and predecessor coincide (no direction yet) — keep current frame
+            return;
+        }
+
+        const inv = 1 / t_length;
+        tx *= inv;
+        ty *= inv;
+        tz *= inv;
+
+        tube.getKnotNormal(v3_pred_n, predecessor_index);
+
+        tube_frame_transport(
+            frame_out, 0,
+            tx, ty, tz,
+            v3_pred_n[0], v3_pred_n[1], v3_pred_n[2]
+        );
+
+        tube.setKnotFrame(
+            head_index,
+            frame_out[0], frame_out[1], frame_out[2],
+            frame_out[3], frame_out[4], frame_out[5]
+        );
+    }
+
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} head_age
+     * @returns {boolean} whether the head position changed
+     */
+    updateHead(x, y, z, head_age) {
+        const tube = this.tube;
+
+        const maxAge = this.maxAge;
+
+        if (this.getFlag(Trail3DFlags.Reseed)) {
+            // post-clear() re-seed: collapse every knot onto the new head position so
+            // no segment bridges post-clear geometry to pre-clear history.
+            const n = tube.getCount();
+            for (let i = 0; i < n; i++) {
+                tube.setKnotPosition(i, x, y, z);
+            }
+            this.timeSinceLastUpdate = 0;
+            this.distanceSinceLastUpdate = 0;
+            this.clearFlag(Trail3DFlags.Reseed);
+        }
+
+        const refitTimeDelta = maxAge / tube.getCount();
+
+        let head_index = tube.getHeadIndex();
+        tube.getKnotPosition(v3_head_pos, head_index);
+
+        const head_position_changed = x !== v3_head_pos[0]
+            || y !== v3_head_pos[1]
+            || z !== v3_head_pos[2];
+
+        if (head_position_changed) {
+            this.distanceSinceLastUpdate += v3_distance(
+                v3_head_pos[0], v3_head_pos[1], v3_head_pos[2],
+                x, y, z
+            );
+        }
+
+        const should_spawn = this.spawnMode === TrailSpawnMode.Distance
+            ? this.distanceSinceLastUpdate >= this.spawnDistance
+            : this.timeSinceLastUpdate >= refitTimeDelta;
+
+        if (should_spawn && head_position_changed) {
+            // commit a new knot: both accumulators reset so a mid-life mode switch
+            // can't carry stale accumulation across.
+            this.timeSinceLastUpdate = 0;
+            this.distanceSinceLastUpdate = 0;
+
+            tube.rotate();
+
+            head_index = tube.getHeadIndex();
+        }
+
+        if (head_position_changed) {
+            this.#updateHeadFrame(head_index, x, y, z);
+
+            tube.setKnotPosition(head_index, x, y, z);
+
+            this.setFlag(Trail3DFlags.BoundsNeedUpdate);
+        }
+
+        // set head to fresh value
+        tube.setKnotAttribute_Scalar(head_index, TUBE_ATTRIBUTE_ADDRESS_AGE, head_age);
+        tube.setKnotAlpha(head_index, clamp01(head_age / maxAge));
+        tube.setKnotThickness(head_index, this.width);
+
+        return head_position_changed;
+    }
+
+}
+
+Trail3D.typeName = "Trail3D";
+
+Trail3D.serializable = false;
+
+export default Trail3D;

package/src/engine/graphics/ecs/trail3d/Trail3DFlags.d.ts

@@ -0,0 +1,9 @@
+export type Trail3DFlags = number;
+export namespace Trail3DFlags {
+    let Spawning: number;
+    let Aging: number;
+    let Built: number;
+    let BoundsNeedUpdate: number;
+    let Reseed: number;
+}
+//# sourceMappingURL=Trail3DFlags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Trail3DFlags.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3DFlags.js"],"names":[],"mappings":"2BAEU,MAAM"}

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

@@ -0,0 +1,18 @@
+/**
+ * @readonly
+ * @enum {number}
+ */
+export const Trail3DFlags = {
+    Spawning: 1,
+    Aging: 2,
+    Built: 4,
+    BoundsNeedUpdate: 8,
+
+    /**
+     * Set by Trail3D.clear(); consumed by the next updateHead(), which collapses
+     * the whole tube onto the new head position before resuming. Guarantees no
+     * segment can bridge post-clear geometry to pre-clear history (e.g. a long
+     * streak after teleporting the entity).
+     */
+    Reseed: 16
+};

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

@@ -0,0 +1,55 @@
+export default Trail3DSystem;
+declare class Trail3DSystem extends System<any, any, any, any, any> {
+    /**
+     * @param {Engine} engine
+     * @constructor
+     */
+    constructor(engine: Engine);
+    dependencies: (typeof Transform | typeof Trail3D)[];
+    components_used: ResourceAccessSpecification<typeof Trail3D>[];
+    /**
+     * @type {TubeXFixedPhysicsSimulator}
+     */
+    simulator: TubeXFixedPhysicsSimulator;
+    /**
+     * @private
+     * @type {BVH}
+     */
+    private bvh;
+    /**
+     * @type {GraphicsEngine}
+     */
+    graphics: GraphicsEngine;
+    /**
+     * @type {RenderLayer|null}
+     */
+    renderLayer: RenderLayer | null;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entityId
+     */
+    link(trail: Trail3D, transform: Transform, entityId: number): void;
+    /**
+     * @param {Trail3D} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component: Trail3D, transform: Transform, entity: number): void;
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     */
+    updateTrailEntity(trail: Trail3D, transform: Transform): void;
+    update(timeDelta: any): void;
+    #private;
+}
+import { System } from '../../../ecs/System.js';
+import { Transform } from '../../../ecs/transform/Transform.js';
+import Trail3D from './Trail3D.js';
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { TubeXFixedPhysicsSimulator } from "../../trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
+import { GraphicsEngine } from "../../GraphicsEngine.js";
+//# sourceMappingURL=Trail3DSystem.d.ts.map

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

@@ -0,0 +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;IA0DD;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,YACT,MAAM,QAYhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAkCnB;IAED,6BAWC;;CACJ;uBA7OsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}