@woosh/meep-engine 3.68.0 → 3.69.0

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

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

@@ -3,18 +3,12 @@
  * @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).
+     * The head follows the entity and lays knots down behind it. Clear it to stop the trail where it
+     * is and let it fade out; a stroke ({@link seed_trail_stroke}) clears it, having its whole shape at
+     * birth.
      */
-    Reseed: 16,
+    Spawning: 1,
 
     /**
      * The tube processes standard scene lighting (receive-only — it never casts

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

@@ -1,18 +1,21 @@
 /**
  * Lay a trail down as a fixed stroke between two world points.
  *
- * **This is the other kind of trail.** {@link seed_trail_tube} collapses every knot onto the head
- * and lets the entity's travel draw the shape — a wake. A stroke has its whole shape at birth and
- * only ages: a beam leaves its source and arrives at its target inside one frame, so there is no
- * travel to lay it down with. Both are the same tube afterwards, aged by the same simulator and
- * drawn by the same renderer, which is what keeps the game to one trail mechanism (D19/I-6c).
+ * **This is the other kind of trail.** A wake collapses onto the head and lets the entity's travel draw
+ * the shape. A stroke has its whole shape at birth and only ages: a beam leaves its source and arrives at
+ * its target inside one frame, so there is no travel to lay it down with. Both are the same tube
+ * afterwards, aged and drawn by the same system, which is what keeps the game to one trail mechanism
+ * (D19/I-6c).
  *
- * The two ends carry their own starting age, and that is the whole of the gradient: the simulator
- * fades a knot's alpha as it approaches `maxAge`, so an end seeded older thins out first. A beam
- * whose source end starts most of the way through its life reads as retracting towards its target.
+ * The two ends carry their own starting age, and that is the whole of the gradient: a knot fades as it
+ * approaches `maxAge`, so an end seeded older thins out first. A beam whose source end starts most of the
+ * way through its life reads as retracting towards its target.
  *
- * **The caller must clear {@link Trail3DFlags.Spawning}**, or the per-frame update will drag the
- * head onto the entity and the stroke will grow a tail towards it.
+ * **The caller must clear {@link Trail3DFlags.Spawning}**, or the head will follow the entity and the
+ * stroke will grow a tail towards it.
+ *
+ * The knots go into {@link Trail3D#knots}, the authored layout the system uploads when the trail is
+ * registered.
  *
  * @param {Trail3D} trail
  * @param {Vector3} from world position the stroke starts at

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

@@ -1 +1 @@
-{"version":3,"file":"seed_trail_stroke.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/seed_trail_stroke.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wFAJW,MAAM,UACN,MAAM,GACJ,IAAI,CAqDhB"}
+{"version":3,"file":"seed_trail_stroke.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/seed_trail_stroke.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wFAJW,MAAM,UACN,MAAM,GACJ,IAAI,CA0ChB"}

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

@@ -3,8 +3,7 @@ import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
 import {
     v3_orthonormal_matrix_from_normal
 } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
-import { TUBE_ATTRIBUTE_ADDRESS_AGE, TUBE_ATTRIBUTE_ADDRESS_UV_V } from "../../trail/tube/tube_attributes_spec.js";
-import { Trail3DFlags } from "./Trail3DFlags.js";
+import { TrailKnots } from "../../trail/TrailKnots.js";
 
 /**
  * The frame every knot of a straight stroke shares.
@@ -16,18 +15,21 @@ const frame = new Float64Array(9);
 /**
  * Lay a trail down as a fixed stroke between two world points.
  *
- * **This is the other kind of trail.** {@link seed_trail_tube} collapses every knot onto the head
- * and lets the entity's travel draw the shape — a wake. A stroke has its whole shape at birth and
- * only ages: a beam leaves its source and arrives at its target inside one frame, so there is no
- * travel to lay it down with. Both are the same tube afterwards, aged by the same simulator and
- * drawn by the same renderer, which is what keeps the game to one trail mechanism (D19/I-6c).
+ * **This is the other kind of trail.** A wake collapses onto the head and lets the entity's travel draw
+ * the shape. A stroke has its whole shape at birth and only ages: a beam leaves its source and arrives at
+ * its target inside one frame, so there is no travel to lay it down with. Both are the same tube
+ * afterwards, aged and drawn by the same system, which is what keeps the game to one trail mechanism
+ * (D19/I-6c).
  *
- * The two ends carry their own starting age, and that is the whole of the gradient: the simulator
- * fades a knot's alpha as it approaches `maxAge`, so an end seeded older thins out first. A beam
- * whose source end starts most of the way through its life reads as retracting towards its target.
+ * The two ends carry their own starting age, and that is the whole of the gradient: a knot fades as it
+ * approaches `maxAge`, so an end seeded older thins out first. A beam whose source end starts most of the
+ * way through its life reads as retracting towards its target.
  *
- * **The caller must clear {@link Trail3DFlags.Spawning}**, or the per-frame update will drag the
- * head onto the entity and the stroke will grow a tail towards it.
+ * **The caller must clear {@link Trail3DFlags.Spawning}**, or the head will follow the entity and the
+ * stroke will grow a tail towards it.
+ *
+ * The knots go into {@link Trail3D#knots}, the authored layout the system uploads when the trail is
+ * registered.
  *
  * @param {Trail3D} trail
  * @param {Vector3} from world position the stroke starts at
@@ -50,41 +52,30 @@ export function seed_trail_stroke(trail, from, to, age_from, age_to) {
 
     assert.greaterThan(length, 0, 'a stroke needs two distinct ends');
 
-    const segment_count = 2;
-
-    trail.build(segment_count);
-
-    const tube = trail.tube;
-
-    trail.time = 0;
-    trail.trailingIndex = 0;
-    trail.timeSinceLastUpdate = 0;
-    trail.distanceSinceLastUpdate = 0;
+    const knot_count = 2;
 
     const inv = 1 / length;
 
+    // the stroke is straight, so every ring shares one frame and no transport is needed
     v3_orthonormal_matrix_from_normal(frame, 0, dx * inv, dy * inv, dz * inv);
 
-    const color = trail.color;
-
     const max_age = trail.maxAge;
 
-    for (let i = 0; i < segment_count; i++) {
-        const f = i / (segment_count - 1);
-
-        const age = (age_from + (age_to - age_from) * f) * max_age;
+    const knots = new TrailKnots();
 
-        tube.setKnotPosition(i, from.x + dx * f, from.y + dy * f, from.z + dz * f);
+    knots.setCount(knot_count);
 
-        // the stroke is straight, so every ring shares one frame and no transport is needed
-        tube.setKnotFrame(i, frame[0], frame[1], frame[2], frame[3], frame[4], frame[5]);
+    for (let i = 0; i < knot_count; i++) {
+        const f = i / (knot_count - 1);
 
-        tube.setKnotColor(i, color.x, color.y, color.z);
-        tube.setKnotThickness(i, trail.width);
-        tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
-        tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, age);
-        tube.setKnotAlpha(i, (1 - age / max_age) * color.w);
+        knots.setKnot(
+            i,
+            from.x + dx * f, from.y + dy * f, from.z + dz * f,
+            frame[0], frame[1], frame[2], frame[3], frame[4], frame[5],
+            trail.width,
+            (age_from + (age_to - age_from) * f) * max_age
+        );
     }
 
-    trail.setFlag(Trail3DFlags.Built);
+    trail.knots = knots;
 }

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

@@ -0,0 +1,10 @@
+/**
+ * Knots a trail that lasts `max_age` seconds lays down: one per sixtieth of a second, never fewer than 2
+ * nor more than 1,024. A trail's knots are a ring of fixed capacity, so this is what turns an age into a
+ * length.
+ *
+ * @param {number} max_age seconds
+ * @returns {number}
+ */
+export function trail_knot_count(max_age: number): number;
+//# sourceMappingURL=trail_knot_count.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trail_knot_count.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/trail_knot_count.js"],"names":[],"mappings":"AAgBA;;;;;;;GAOG;AACH,0CAHW,MAAM,GACJ,MAAM,CAIlB"}

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

@@ -0,0 +1,27 @@
+import { clamp } from "../../../../core/math/clamp.js";
+
+/**
+ * Knots laid down per second of trail life.
+ *
+ * @type {number}
+ */
+const KNOTS_PER_SECOND = 60;
+
+/**
+ * The most knots a trail's ring holds.
+ *
+ * @type {number}
+ */
+const MAX_KNOTS = 1024;
+
+/**
+ * Knots a trail that lasts `max_age` seconds lays down: one per sixtieth of a second, never fewer than 2
+ * nor more than 1,024. A trail's knots are a ring of fixed capacity, so this is what turns an age into a
+ * length.
+ *
+ * @param {number} max_age seconds
+ * @returns {number}
+ */
+export function trail_knot_count(max_age) {
+    return Math.ceil(clamp(max_age * KNOTS_PER_SECOND, 2, MAX_KNOTS));
+}