@woosh/meep-engine 2.168.0 → 2.169.0

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

@@ -1,476 +1,488 @@
-import { assert } from "../../../../core/assert.js";
-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;
-
-    /**
-     * RGB tints the tube; alpha is the trail's base opacity, which the
-     * age-driven fade scales down to zero.
-     * @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;
-    }
-
-    /**
-     * Whether the trail's tube processes standard scene lighting. When enabled the
-     * tube shades as a matte (Lambert) surface under the scene's ambient /
-     * hemisphere / light-probe / directional / point / spot lights and receives
-     * shadows; it never casts them. Under the Forward+ pipeline the material is
-     * additionally rewritten by the renderer's material manager, so clustered
-     * point lights and decals apply as well. When disabled (default) the tube
-     * renders unlit.
-     *
-     * Stored in {@link Trail3DFlags.Lit}. This is a build-time option — it selects
-     * the compiled material and the mesh's shadow settings — so it must be set
-     * before the trail is built / registered with the system, and cannot change
-     * afterwards.
-     *
-     * @returns {boolean}
-     */
-    get lightingEnabled() {
-        return this.getFlag(Trail3DFlags.Lit);
-    }
-
-    /**
-     * @param {boolean} v
-     */
-    set lightingEnabled(v) {
-        if (v === this.lightingEnabled) {
-            return;
-        }
-
-        assert.notOk(this.getFlag(Trail3DFlags.Built), "lightingEnabled cannot change after the trail is built");
-
-        this.writeFlag(Trail3DFlags.Lit, 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);
-
-        // receive-only lighting: castShadow stays false. The geometry's `position`
-        // attribute holds ring CENTRES (the surface is extruded in the material's
-        // vertex stage), so a stock depth pass would render a degenerate line anyway.
-        mesh.receiveShadow = this.getFlag(Trail3DFlags.Lit);
-
-        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,
-                 lightingEnabled = 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.lightingEnabled = lightingEnabled;
-
-        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,
-            lightingEnabled: this.lightingEnabled,
-            offset: this.offset.toJSON()
-        };
-    }
-
-    /**
-     * @param {Trail3D} other
-     */
-    equals(other) {
-        return this.textureURL === other.textureURL
-            && this.depthWrite === other.depthWrite
-            && this.lightingEnabled === other.lightingEnabled
-            && 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; alpha follows the same fade law the simulator
-        // applies every tick, so the knot doesn't pop when it stops being the head
-        tube.setKnotAttribute_Scalar(head_index, TUBE_ATTRIBUTE_ADDRESS_AGE, head_age);
-        tube.setKnotAlpha(head_index, (1 - clamp01(head_age / maxAge)) * this.color.w);
-        tube.setKnotThickness(head_index, this.width);
-
-        return head_position_changed;
-    }
-
-}
-
-Trail3D.typeName = "Trail3D";
-
-Trail3D.serializable = false;
-
-export default Trail3D;
+import { assert } from "../../../../core/assert.js";
+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;
+
+    /**
+     * RGB tints the tube; alpha is the trail's base opacity, which the
+     * age-driven fade scales down to zero.
+     * @readonly
+     * @type {Color}
+     */
+    color = new Color(1, 1, 1, 1);
+
+    /**
+     * Where the trail's head sits relative to the entity, in the entity's LOCAL
+     * frame: {@link Trail3DSystem} carries it through the entity's transform, so
+     * the offset rotates and scales with the entity rather than being a fixed
+     * world-space displacement.
+     * @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;
+
+        // The mesh's geometry died with the tube, so the component must stop
+        // claiming to be built: link() would otherwise take its "already built"
+        // branch, hang a material on the dead mesh and leave the tube null, and the
+        // first update would hand that null to the simulator. Dropping Built makes a
+        // re-link rebuild instead. The material is owned by the tube plugin's cache,
+        // so it is not ours to dispose — only to forget.
+        this.mesh = null;
+        this.clearFlag(Trail3DFlags.Built);
+    }
+
+    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;
+    }
+
+    /**
+     * Whether the trail's tube processes standard scene lighting. When enabled the
+     * tube shades as a matte (Lambert) surface under the scene's ambient /
+     * hemisphere / light-probe / directional / point / spot lights and receives
+     * shadows; it never casts them. Under the Forward+ pipeline the material is
+     * additionally rewritten by the renderer's material manager, so clustered
+     * point lights and decals apply as well. When disabled (default) the tube
+     * renders unlit.
+     *
+     * Stored in {@link Trail3DFlags.Lit}. This is a build-time option — it selects
+     * the compiled material and the mesh's shadow settings — so it must be set
+     * before the trail is built / registered with the system, and cannot change
+     * afterwards.
+     *
+     * @returns {boolean}
+     */
+    get lightingEnabled() {
+        return this.getFlag(Trail3DFlags.Lit);
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set lightingEnabled(v) {
+        if (v === this.lightingEnabled) {
+            return;
+        }
+
+        assert.notOk(this.getFlag(Trail3DFlags.Built), "lightingEnabled cannot change after the trail is built");
+
+        this.writeFlag(Trail3DFlags.Lit, 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);
+
+        // receive-only lighting: castShadow stays false. The geometry's `position`
+        // attribute holds ring CENTRES (the surface is extruded in the material's
+        // vertex stage), so a stock depth pass would render a degenerate line anyway.
+        mesh.receiveShadow = this.getFlag(Trail3DFlags.Lit);
+
+        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,
+                 lightingEnabled = 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.lightingEnabled = lightingEnabled;
+
+        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,
+            lightingEnabled: this.lightingEnabled,
+            offset: this.offset.toJSON()
+        };
+    }
+
+    /**
+     * @param {Trail3D} other
+     */
+    equals(other) {
+        return this.textureURL === other.textureURL
+            && this.depthWrite === other.depthWrite
+            && this.lightingEnabled === other.lightingEnabled
+            && 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; alpha follows the same fade law the simulator
+        // applies every tick, so the knot doesn't pop when it stops being the head
+        tube.setKnotAttribute_Scalar(head_index, TUBE_ATTRIBUTE_ADDRESS_AGE, head_age);
+        tube.setKnotAlpha(head_index, (1 - clamp01(head_age / maxAge)) * this.color.w);
+        tube.setKnotThickness(head_index, this.width);
+
+        return head_position_changed;
+    }
+
+}
+
+Trail3D.typeName = "Trail3D";
+
+Trail3D.serializable = false;
+
+export default Trail3D;