@woosh/meep-engine 3.68.0 → 3.70.0

package/src/core/math/complex/complex_fft_radix2.js

@@ -0,0 +1,71 @@
+import { assert } from "../../assert.js";
+import { isPowerOfTwo } from "../isPowerOfTwo.js";
+
+/**
+ * The discrete Fourier transform of `n` complex values, in place, radix 2:
+ *
+ *     X_k = Σ_j x_j · e^(∓2πi·jk/n)
+ *
+ * the minus sign forward, the plus sign inverse. The inverse is not scaled: a forward transform
+ * then an inverse one multiplies every value by `n`.
+ *
+ * Iterative Cooley–Tukey, decimation in time: a bit-reversal permutation, then `log2(n)` stages of
+ * butterflies. Each stage's twiddles are taken from `Math.cos` and `Math.sin` directly, `n − 1` pairs
+ * over the transform, so the error does not grow along a recurrence. Allocates nothing.
+ *
+ * @param {Float64Array|Float32Array|number[]} re real parts, read and written at `0..n−1`
+ * @param {Float64Array|Float32Array|number[]} im imaginary parts, likewise
+ * @param {number} n a power of two
+ * @param {boolean} inverse
+ */
+export function complex_fft_radix2(re, im, n, inverse) {
+    assert.isPositiveInteger(n, 'n');
+    assert.ok(isPowerOfTwo(n), 'n is a power of two');
+
+    // bit-reversal permutation
+    for (let i = 1, j = 0; i < n; i++) {
+        let bit = n >> 1;
+
+        while ((j & bit) !== 0) {
+            j ^= bit;
+            bit >>= 1;
+        }
+
+        j ^= bit;
+
+        if (i < j) {
+            const r = re[i];
+            re[i] = re[j];
+            re[j] = r;
+
+            const m = im[i];
+            im[i] = im[j];
+            im[j] = m;
+        }
+    }
+
+    const sign = inverse ? 1 : -1;
+
+    for (let length = 2; length <= n; length <<= 1) {
+        const half = length >> 1;
+        const step = sign * 2 * Math.PI / length;
+
+        for (let k = 0; k < half; k++) {
+            const w_re = Math.cos(step * k);
+            const w_im = Math.sin(step * k);
+
+            for (let start = 0; start < n; start += length) {
+                const a = start + k;
+                const b = a + half;
+
+                const t_re = re[b] * w_re - im[b] * w_im;
+                const t_im = re[b] * w_im + im[b] * w_re;
+
+                re[b] = re[a] - t_re;
+                im[b] = im[a] - t_im;
+                re[a] += t_re;
+                im[a] += t_im;
+            }
+        }
+    }
+}

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

@@ -1,14 +1,18 @@
 export default Trail3D;
 /**
- * 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.
+ * A tube left behind an entity — the volumetric counterpart of {@link Trail2D}. The head follows the
+ * entity at {@link offset}; knots are laid down behind it as it travels, each with the frame its ring
+ * stands in, and fade by {@link fade} as they age towards {@link maxAge}.
+ *
+ * The component is the trail's description. Its knots live where {@link Trail3DSystem} simulates and
+ * draws them, on the GPU; a game writes these fields and the system picks the change up.
  */
 declare class Trail3D {
     static fromJSON(json: any): Trail3D;
     /**
-     * Age at which a trail knot disappears, in seconds.
+     * Age at which a trail knot disappears, in seconds. How many knots the trail holds is fixed when the
+     * system registers it: a later change moves the fade and how often a knot is laid down, not the
+     * length of the ring.
      * @type {number}
      */
     maxAge: number;
@@ -18,8 +22,8 @@ declare class Trail3D {
      */
     width: number;
     /**
-     * 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.
+     * Number of radial subdivisions around the tube. Higher = rounder tube. Fixed when the system
+     * registers the trail; re-add the component to change it.
      * @type {number}
      */
     radialSegments: number;
@@ -34,25 +38,6 @@ declare class Trail3D {
      * @type {number}
      */
     spawnDistance: number;
-    /**
-     * Current simulated time since trail birth.
-     * @type {number}
-     */
-    time: number;
-    /**
-     * @type {number}
-     */
-    trailingIndex: number;
-    /**
-     * Time elapsed since the last knot was committed.
-     * @type {number}
-     */
-    timeSinceLastUpdate: number;
-    /**
-     * Distance the head has travelled since the last knot was committed.
-     * @type {number}
-     */
-    distanceSinceLastUpdate: number;
     /**
      * RGB tints the tube; alpha is the trail's base opacity, which {@link fade}
      * scales as each knot ages.
@@ -83,35 +68,34 @@ declare class Trail3D {
      */
     readonly offset: Vector3;
     /**
-     * transient
-     * @type {TubeX|null}
+     * Whether a new trail fades in over its first {@link maxAge} seconds: its head is born
+     * `maxAge - t` old while the trail is `t` seconds old, so the stretch laid down first is the
+     * faintest. On by default; turn it off for a trail that must be fully visible from its first
+     * frame, a tracer.
+     * @type {boolean}
      */
-    tube: TubeX | null;
+    warmup: boolean;
     /**
-     * What the legacy renderer draws this tube through — a three mesh over
-     * {@link TubeXGeometry}'s views, built and owned by {@link Trail3DSystem}. The Shade path
-     * leaves it null and builds a dynamic mesh of its own from the same knots.
-     *
-     * transient
-     * @type {Mesh|null}
+     * Knots laid down whole by the author — a stroke, a helix — instead of by the entity's travel, or
+     * null for a trail the entity draws. See {@link TrailKnots}; {@link seed_trail_stroke} writes one.
+     * @type {import("../../trail/TrailKnots.js").TrailKnots|null}
      */
-    mesh: Mesh | null;
+    knots: import("../../trail/TrailKnots.js").TrailKnots | null;
+    /**
+     * Moved by every {@link clear}, so the system sees the request by comparing it.
+     * @type {number}
+     */
+    clearCount: number;
     /**
      * transient
      * @type {TubeXMaterialSpec}
      */
     material: TubeXMaterialSpec;
-    /**
-     * @readonly
-     * @type {BvhClient}
-     */
-    readonly bvh: BvhClient;
     /**
      * @private
      * @type {Trail3DFlags|number}
      */
     private flags;
-    dispose(): void;
     set textureURL(v: string);
     get textureURL(): string;
     set depthWrite(v: boolean);
@@ -131,8 +115,7 @@ declare class Trail3D {
      *
      * 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.
+     * before the trail is registered with the system.
      *
      * @returns {boolean}
      */
@@ -158,18 +141,12 @@ declare class Trail3D {
      */
     getFlag(flag: number | Trail3DFlags): boolean;
     /**
-     * Build the knots this trail lays down. What draws them is the registered renderer's system,
-     * which builds its own representation over these rows — the component holds the trail, not a
-     * picture of it.
-     *
-     * @param {number} segment_count
-     */
-    build(segment_count: number): void;
-    /**
-     * Clear the trail's geometry and reset its state.
+     * Erase the trail: at the next frame every knot expires and collapses onto the head where the entity
+     * stands, so nothing bridges what comes after to what went before (a teleport leaves no streak). The
+     * trail keeps its birth, so its warm-up does not run again.
      */
     clear(): void;
-    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, lightingEnabled, offset, color, fade }: {
+    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, lightingEnabled, warmup, offset, color, fade }: {
         maxAge?: number;
         width?: number;
         radialSegments?: number;
@@ -178,6 +155,7 @@ declare class Trail3D {
         textureURL: any;
         depthWrite?: boolean;
         lightingEnabled?: boolean;
+        warmup?: boolean;
         offset?: Vector3;
         color?: {
             r: number;
@@ -205,6 +183,7 @@ declare class Trail3D {
         textureURL: string;
         depthWrite: boolean;
         lightingEnabled: boolean;
+        warmup: boolean;
         offset: {
             x: number;
             y: number;
@@ -215,15 +194,6 @@ declare class Trail3D {
      * @param {Trail3D} other
      */
     equals(other: Trail3D): boolean;
-    /**
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} head_age
-     * @returns {boolean} whether the head position changed
-     */
-    updateHead(x: number, y: number, z: number, head_age: number): boolean;
-    #private;
 }
 declare namespace Trail3D {
     let typeName: string;
@@ -233,8 +203,6 @@ import { TrailSpawnMode } from "../../trail/TrailSpawnMode.js";
 import { Color } from "../../../../core/color/Color.js";
 import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
-import { TubeX } from "../../trail/tube/TubeX.js";
 import { TubeXMaterialSpec } from "../../trail/tube/TubeXMaterialSpec.js";
-import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
 import { Trail3DFlags } from "./Trail3DFlags.js";
 //# sourceMappingURL=Trail3D.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAkCA;;;;;GAKG;AACH;IA0QI,oCAMC;IA9QD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,gBAFU,MAAM,CAEyB;IAEzC;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;;;;;;OASG;IACH,MAFU,cAAc,CAEG;IAE3B;;;;;;;OAOG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,KAAK,GAAC,IAAI,CAER;IAEZ;;;;;;;OAOG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAgBC;IAMD,0BAEC;IAND,yBAEC;IAUD,2BAEC;IAND,0BAEC;IA0BD;;OAEG;IACH,gCAQC;IA/BD;;;;;;;;;;;;;;;OAeG;IACH,+BAEC;IAeD;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAShB;IAED;;OAEG;IACH,cAmBC;IAUD;;;;;;;;;;;;;;;;;aAmCC;IAED;;;;;;;;;;;;;;;;;;;;;;;MAcC;IAED;;OAEG;IACH,cAFW,OAAO,WAejB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAiEnB;;CAEJ;;;;;+BA/e8B,+BAA+B;sBAPxC,iCAAiC;+BAMxB,4CAA4C;oBALvD,kCAAkC;sBAShC,2BAA2B;kCACf,uCAAuC;0BAZ/C,yCAAyC;6BActC,mBAAmB"}
+{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAkBA;;;;;;;GAOG;AACH;IA6LI,oCAMC;IAjMD;;;;;OAKG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,gBAFU,MAAM,CAEyB;IAEzC;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;;;;;OAOG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;;;;;;OASG;IACH,MAFU,cAAc,CAEG;IAE3B;;;;;;;OAOG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;;;OAMG;IACH,QAFU,OAAO,CAEH;IAEd;;;;OAIG;IACH,OAFU,OAAO,2BAA2B,EAAE,UAAU,GAAC,IAAI,CAEhD;IAEb;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAAsB;IAMtB,0BAEC;IAND,yBAEC;IAUD,2BAEC;IAND,0BAEC;IAyBD;;OAEG;IACH,gCAEC;IAxBD;;;;;;;;;;;;;;OAcG;IACH,+BAEC;IASD;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;;OAIG;IACH,cAEC;IAUD;;;;;;;;;;;;;;;;;;aAqCC;IAED;;;;;;;;;;;;;;;;;;;;;;;;MAeC;IAED;;OAEG;IACH,cAFW,OAAO,WAgBjB;CACJ;;;;;+BAtS8B,+BAA+B;sBAHxC,iCAAiC;+BAExB,4CAA4C;oBADvD,kCAAkC;kCAGpB,uCAAuC;6BAE5C,mBAAmB"}

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

@@ -1,22 +1,12 @@
-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 { AnimationCurve } from "../../../animation/curve/AnimationCurve.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 { TRAIL3D_FADE_LINEAR } from "./TRAIL3D_FADE_LINEAR.js";
 import { Trail3DFlags } from "./Trail3DFlags.js";
 
-const DEFAULT_FLAGS = Trail3DFlags.Spawning | Trail3DFlags.Aging | Trail3DFlags.BoundsNeedUpdate;
+const DEFAULT_FLAGS = Trail3DFlags.Spawning;
 
 const DEFAULT_MAX_AGE = 5;
 
@@ -26,22 +16,20 @@ 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.
+ * A tube left behind an entity — the volumetric counterpart of {@link Trail2D}. The head follows the
+ * entity at {@link offset}; knots are laid down behind it as it travels, each with the frame its ring
+ * stands in, and fade by {@link fade} as they age towards {@link maxAge}.
+ *
+ * The component is the trail's description. Its knots live where {@link Trail3DSystem} simulates and
+ * draws them, on the GPU; a game writes these fields and the system picks the change up.
  */
 class Trail3D {
 
     /**
-     * Age at which a trail knot disappears, in seconds.
+     * Age at which a trail knot disappears, in seconds. How many knots the trail holds is fixed when the
+     * system registers it: a later change moves the fade and how often a knot is laid down, not the
+     * length of the ring.
      * @type {number}
      */
     maxAge = DEFAULT_MAX_AGE;
@@ -53,8 +41,8 @@ class Trail3D {
     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.
+     * Number of radial subdivisions around the tube. Higher = rounder tube. Fixed when the system
+     * registers the trail; re-add the component to change it.
      * @type {number}
      */
     radialSegments = DEFAULT_RADIAL_SEGMENTS;
@@ -72,29 +60,6 @@ class Trail3D {
      */
     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 {@link fade}
      * scales as each knot ages.
@@ -128,32 +93,32 @@ class Trail3D {
     offset = new Vector3();
 
     /**
-     * transient
-     * @type {TubeX|null}
+     * Whether a new trail fades in over its first {@link maxAge} seconds: its head is born
+     * `maxAge - t` old while the trail is `t` seconds old, so the stretch laid down first is the
+     * faintest. On by default; turn it off for a trail that must be fully visible from its first
+     * frame, a tracer.
+     * @type {boolean}
      */
-    tube = null;
+    warmup = true;
 
     /**
-     * What the legacy renderer draws this tube through — a three mesh over
-     * {@link TubeXGeometry}'s views, built and owned by {@link Trail3DSystem}. The Shade path
-     * leaves it null and builds a dynamic mesh of its own from the same knots.
-     *
-     * transient
-     * @type {Mesh|null}
+     * Knots laid down whole by the author — a stroke, a helix — instead of by the entity's travel, or
+     * null for a trail the entity draws. See {@link TrailKnots}; {@link seed_trail_stroke} writes one.
+     * @type {import("../../trail/TrailKnots.js").TrailKnots|null}
      */
-    mesh = null;
+    knots = null;
 
     /**
-     * transient
-     * @type {TubeXMaterialSpec}
+     * Moved by every {@link clear}, so the system sees the request by comparing it.
+     * @type {number}
      */
-    material = new TubeXMaterialSpec();
+    clearCount = 0;
 
     /**
-     * @readonly
-     * @type {BvhClient}
+     * transient
+     * @type {TubeXMaterialSpec}
      */
-    bvh = new BvhClient();
+    material = new TubeXMaterialSpec();
 
     /**
      * @private
@@ -161,24 +126,6 @@ class Trail3D {
      */
     flags = DEFAULT_FLAGS;
 
-    dispose() {
-        if (this.tube === null) {
-            // nothing to dispose
-            return;
-        }
-
-        this.tube = null;
-
-        // The knots the drawable was a view over are gone, 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. Whatever a renderer made of
-        // the tube is that renderer's to release; the material is owned by the tube plugin's
-        // cache, so neither is ours to dispose — only to forget.
-        this.mesh = null;
-        this.clearFlag(Trail3DFlags.Built);
-    }
-
     get textureURL() {
         return this.material.diffuse;
     }
@@ -206,8 +153,7 @@ class Trail3D {
      *
      * 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.
+     * before the trail is registered with the system.
      *
      * @returns {boolean}
      */
@@ -219,12 +165,6 @@ class Trail3D {
      * @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);
     }
 
@@ -265,43 +205,12 @@ class Trail3D {
     }
 
     /**
-     * Build the knots this trail lays down. What draws them is the registered renderer's system,
-     * which builds its own representation over these rows — the component holds the trail, not a
-     * picture of it.
-     *
-     * @param {number} segment_count
-     */
-    build(segment_count) {
-
-        const tube = new TubeX();
-
-        tube.setCount(segment_count, this.radialSegments);
-
-        this.tube = tube;
-    }
-
-    /**
-     * Clear the trail's geometry and reset its state.
+     * Erase the trail: at the next frame every knot expires and collapses onto the head where the entity
+     * stands, so nothing bridges what comes after to what went before (a teleport leaves no streak). The
+     * trail keeps its birth, so its warm-up does not run again.
      */
     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);
+        this.clearCount++;
     }
 
     static fromJSON(json) {
@@ -321,6 +230,7 @@ class Trail3D {
                  textureURL,
                  depthWrite = false,
                  lightingEnabled = false,
+                 warmup = true,
                  offset = Vector3.zero,
                  color = { r: 1, g: 1, b: 1, a: 1 },
                  fade
@@ -334,6 +244,7 @@ class Trail3D {
         this.textureURL = textureURL;
         this.depthWrite = depthWrite;
         this.lightingEnabled = lightingEnabled;
+        this.warmup = warmup;
 
         this.offset.fromJSON(offset);
         this.color.fromJSON(color);
@@ -361,6 +272,7 @@ class Trail3D {
             textureURL: this.textureURL,
             depthWrite: this.depthWrite,
             lightingEnabled: this.lightingEnabled,
+            warmup: this.warmup,
             offset: this.offset.toJSON()
         };
     }
@@ -372,6 +284,7 @@ class Trail3D {
         return this.textureURL === other.textureURL
             && this.depthWrite === other.depthWrite
             && this.lightingEnabled === other.lightingEnabled
+            && this.warmup === other.warmup
             && this.width === other.width
             && this.radialSegments === other.radialSegments
             && this.maxAge === other.maxAge
@@ -382,127 +295,6 @@ class Trail3D {
             && 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, this.fade.evaluate(clamp01(head_age / maxAge)) * this.color.w);
-        tube.setKnotThickness(head_index, this.width);
-
-        return head_position_changed;
-    }
-
 }
 
 Trail3D.typeName = "Trail3D";

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

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