@woosh/meep-engine 3.68.0 → 3.69.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## Unreleased
 
+### Trails: `Trail3DSystem` simulates and extrudes them on the GPU
+
+- **Breaking:** `Trail3DSystem` takes the scene its entities are in, `new Trail3DSystem(graphics, scene)`, as
+  `ShadedGeometrySystem` and `GPUParticleEmitterSystem` do. It simulates every trail in compute and extrudes its
+  tube in the vertex stage, drawn inside the transparency pipeline as before. The CPU builds no geometry and
+  uploads only the trails whose fields changed: a frame costs a comparison of each trail's fields.
+- **Breaking:** a trail's head follows its entity's transform as the scene holds it, so a translation written by
+  hand moves the trail only once it is announced (`t64_announce_change`), as for meshes and particle emitters.
+  The system read `transform.matrix` every frame before.
+- **Breaking:** a trail's knots live on the GPU only. Removed from `Trail3D`: `tube`, `build()`, `updateHead()`,
+  `dispose()`, `time`, `timeSinceLastUpdate`, `distanceSinceLastUpdate`, `trailingIndex`, `mesh` and `bvh`; from
+  `Trail3DFlags`: `Aging`, `Built`, `BoundsNeedUpdate` and `Reseed` (`Spawning` and `Lit` keep their values);
+  `Trail3DSystem.batch`; and the modules `TubeX`, `TubeXFixedPhysicsSimulator`, `tube_attributes_spec`,
+  `trail_tube_write_geometry`, `seed_trail_tube`, `advance_trail` and `trail_head_position`. `trail_knot_count`
+  moves to `src/engine/graphics/ecs/trail3d/trail_knot_count.js`. `Trail3D` is not serializable, so no save is
+  affected.
+- **Changed:** `seed_trail_stroke` writes the stroke into `Trail3D.knots` alone. `make_gradient_stroke` is
+  unchanged.
+- **Added:** `Trail3D.warmup`, on by default: a new trail fades in over its first `maxAge` seconds, its head born as
+  old as the time left of that first life. Turn it off for a trail that must be whole from its first frame, a
+  tracer. It round-trips through JSON.
+- **Added:** `Trail3D.knots`, a `TrailKnots` of knots laid down whole (a stroke, a helix), drawn as they are, and
+  `Trail3D.clearCount`, which moves with every `clear()`.
+- Measured on an AMD RDNA2 iGPU (2 CUs) at 1258×566, 8 radial segments, every trail moving and in view, both
+  systems in one page: 100 trails of 2 s cost 22.8 ms of CPU a frame on the old system and 0.69 ms on this one;
+  1,000 trails of 2 s, 184 ms and 1.85 ms. Drawing them costs the GPU about the same, most of it in the vertex
+  stage: 0.70 against 0.81 ms at 100 trails, 6.3 against 7.2 ms at 1,000, the second figure including the
+  update and the cull. 10,000 trails of 2 s cost 10.8 ms of CPU, 4.5 ms of it moving and announcing the
+  transforms and 4.3 ms inside the render call, and 65.5 ms of GPU. One trail costs the GPU 25 µs a frame, where
+  it cost 9 µs: the update, the cull and the draw arguments are passes of their own however few trails there are.
+
+Migrating:
+
+- Pass the scene: `new Trail3DSystem(graphics, scene)`.
+- Announce every translation written to a trail's entity by hand (nekomancer's guide motes and speed ribbons).
+- A system subclass that scaled the tube's vertex colours after each update (nekomancer) puts the factor into
+  `trail.color` when the trail is made instead: colour is linear and unbounded, so the trail looks the same.
+- Code that seeded a tube and drove its head (meep-shooter's projectiles: `seed_trail_tube`, `updateHead`, the
+  writes to `time` and `timeSinceLastUpdate`, `system.update(0)` before rendering) drops all of it: the head
+  follows the announced transform. Where `time = maxAge` was written to show a tracer whole at once, set
+  `warmup = false`.
+- A shape written into `trail.tube` after `trail.build` (queep-3-arena's helix) goes into a `TrailKnots` on
+  `trail.knots` instead: `setCount`, then `setKnot` with each knot's position, frame, thickness and starting age.
+- A trail that only hangs on an entity (meep-demo-castle) needs nothing.
+
 ### Network: the render delay comes down by the clock, and starts over after a wait of the client's own (SW_303, SW_304)
 
 - **Breaking:** `AdaptiveRenderDelay`'s `decay_per_sample_ms` is replaced by `decay_rate`: milliseconds of delay shed

package/editor/ecs/component/editors/ecs/Trail3DEditor.d.ts

@@ -10,25 +10,10 @@ export class Trail3DEditor extends ObjectEditor {
             spawnDistance: {
                 description: string;
             };
-            time: {
+            knots: {
                 transient: boolean;
             };
-            trailingIndex: {
-                transient: boolean;
-            };
-            timeSinceLastUpdate: {
-                transient: boolean;
-            };
-            distanceSinceLastUpdate: {
-                transient: boolean;
-            };
-            tube: {
-                transient: boolean;
-            };
-            mesh: {
-                transient: boolean;
-            };
-            bvh: {
+            clearCount: {
                 transient: boolean;
             };
             flags: {

package/editor/ecs/component/editors/ecs/Trail3DEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail3DEditor.d.ts","sourceRoot":"","sources":["../../../../../../editor/ecs/component/editors/ecs/Trail3DEditor.js"],"names":[],"mappings":"AAKA;IACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2CC;CACJ;6BA/C4B,8BAA8B;+BAF5B,6BAA6B"}
+{"version":3,"file":"Trail3DEditor.d.ts","sourceRoot":"","sources":["../../../../../../editor/ecs/component/editors/ecs/Trail3DEditor.js"],"names":[],"mappings":"AAKA;IACI;;;;;;;;;;;;;;;;;;;;;;;;MA4BC;CACJ;6BAhC4B,8BAA8B;+BAF5B,6BAA6B"}

package/editor/ecs/component/editors/ecs/Trail3DEditor.js

@@ -11,30 +11,15 @@ export class Trail3DEditor extends ObjectEditor {
                     description: "How long does the trail persist in time"
                 },
                 radialSegments: {
-                    description: "Radial resolution of the tube (rebuild to take effect)"
+                    description: "Radial resolution of the tube (fixed when the trail is registered)"
                 },
                 spawnDistance: {
                     description: "Distance between segments when spawning by distance"
                 },
-                time: {
+                knots: {
                     transient: true
                 },
-                trailingIndex: {
-                    transient: true
-                },
-                timeSinceLastUpdate: {
-                    transient: true
-                },
-                distanceSinceLastUpdate: {
-                    transient: true
-                },
-                tube: {
-                    transient: true
-                },
-                mesh: {
-                    transient: true
-                },
-                bvh: {
+                clearCount: {
                     transient: true
                 },
                 flags: {

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.68.0",
+  "version": "3.69.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

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"}