@woosh/meep-engine 3.60.3 → 3.60.4

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

@@ -34,6 +34,9 @@ export class Trail3DEditor extends ObjectEditor {
             flags: {
                 editor: BitFlagsEditor;
             };
+            fade: {
+                editor: import("../../TypeEditor.js").TypeEditor<any>;
+            };
         };
     };
 }

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":"AAIA;IACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAsCC;CACJ;6BA1C4B,8BAA8B;+BAD5B,6BAA6B"}
+{"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"}

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

@@ -1,5 +1,6 @@
 import { Trail3DFlags } from "../../../../../src/engine/graphics/ecs/trail3d/Trail3DFlags.js";
 import { BitFlagsEditor } from "../common/BitFlagsEditor.js";
+import { noEditor } from "../common/noEditor.js";
 import { ObjectEditor } from "../primitive/ObjectEditor.js";
 
 export class Trail3DEditor extends ObjectEditor {
@@ -38,6 +39,11 @@ export class Trail3DEditor extends ObjectEditor {
                 },
                 flags: {
                     editor: new BitFlagsEditor(Trail3DFlags)
+                },
+                fade: {
+                    // the default is one frozen curve every trail shares, which a generic object
+                    // editor would write into; there is no curve field editor to clone it first yet
+                    editor: noEditor()
                 }
             }
         };

package/package.json

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

package/src/engine/ecs/ik/PLAN.md

@@ -143,7 +143,7 @@ Each stage is red-then-green.
 - [A] Aristidou, Chrysanthou, Lasenby, *Extending FABRIK with model constraints*, CAVW 2016
 - [C] Aristidou, Lasenby, *FABRIK*, Graphical Models 73, 2011
 - [D] Baerlocher, Boulic, *Parametrization and range of motion of the ball-and-socket joint*, 2001
-- [G] UE 5.4 source: `Plugins/Experimental/FullBodyIK/Source/PBIK/`, `AnimNode_FootPlacement`
+- [G] Unreal Engine FullBodyIK (PBIK) and Foot Placement documentation
 - [N] ozz-animation `ik_two_bone_job.h`, `samples/foot_ik/sample_foot_ik.cc`
 
 ## 9. After implementation (2026-10-06)

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js

@@ -55,8 +55,7 @@ export const ShadedGeometryFlags = {
      * clipmap's GI — see it, unless its material is transparent. Without it the primitive is drawn
      * by the camera and invisible to those rays: it occludes nothing, emits nothing and bounces
      * nothing into GI, which is what it is for — a primitive too small or too busy to be worth its
-     * place there. On by default, as {@link CastShadow} is. Unreal's
-     * `bAffectDistanceFieldLighting` is the same switch.
+     * place there. On by default, as {@link CastShadow} is.
      */
     SDFWorld: 128,
 };

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

@@ -0,0 +1,14 @@
+/**
+ * The fade every {@link Trail3D} starts with: full opacity at birth, falling in a straight line to
+ * none at `maxAge`.
+ *
+ * **One instance, shared by every trail that has not been given a curve of its own**, so it is
+ * frozen all the way down — the curve, its key array and each key — and an edit in place throws
+ * rather than reshaping every default trail at once. To author a fade, assign a curve of your own;
+ * `clone()` of this one is an unfrozen copy to start from.
+ *
+ * @type {AnimationCurve}
+ */
+export const TRAIL3D_FADE_LINEAR: AnimationCurve;
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+//# sourceMappingURL=TRAIL3D_FADE_LINEAR.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TRAIL3D_FADE_LINEAR.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/TRAIL3D_FADE_LINEAR.js"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,kCAFU,cAAc,CAEgC;+BArBzB,4CAA4C"}

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

@@ -0,0 +1,22 @@
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+
+const curve = AnimationCurve.linear(0, 1, 1, 0);
+
+for (const key of curve.keys) {
+    Object.freeze(key);
+}
+
+Object.freeze(curve.keys);
+
+/**
+ * The fade every {@link Trail3D} starts with: full opacity at birth, falling in a straight line to
+ * none at `maxAge`.
+ *
+ * **One instance, shared by every trail that has not been given a curve of its own**, so it is
+ * frozen all the way down — the curve, its key array and each key — and an edit in place throws
+ * rather than reshaping every default trail at once. To author a fade, assign a curve of your own;
+ * `clone()` of this one is an unfrozen copy to start from.
+ *
+ * @type {AnimationCurve}
+ */
+export const TRAIL3D_FADE_LINEAR = Object.freeze(curve);

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

@@ -54,14 +54,25 @@ declare class Trail3D {
      */
     distanceSinceLastUpdate: number;
     /**
-     * RGB tints the tube; alpha is the trail's base opacity, which the
-     * age-driven fade scales down to zero.
+     * RGB tints the tube; alpha is the trail's base opacity, which {@link fade}
+     * scales as each knot ages.
      *
      * Linear color space.
      * @readonly
      * @type {Color}
      */
     readonly color: Color;
+    /**
+     * Opacity over a knot's life. The curve's time is the knot's age over {@link maxAge} — `0` at
+     * birth, `1` when the knot disappears — and its value multiplies {@link color}'s alpha. The
+     * opacity meant is the trail's as seen, whatever the renderer has to do to the tube's faces to
+     * show it.
+     *
+     * Every trail starts on {@link TRAIL3D_FADE_LINEAR}, one shared instance, frozen — assign a
+     * curve of your own to reshape a trail's fade rather than editing that one.
+     * @type {AnimationCurve}
+     */
+    fade: AnimationCurve;
     /**
      * 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
@@ -158,7 +169,7 @@ declare class Trail3D {
      * Clear the trail's geometry and reset its state.
      */
     clear(): void;
-    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, lightingEnabled, offset, color }: {
+    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, lightingEnabled, offset, color, fade }: {
         maxAge?: number;
         width?: number;
         radialSegments?: number;
@@ -174,6 +185,7 @@ declare class Trail3D {
             b: number;
             a: number;
         };
+        fade: any;
     }): void;
     toJSON(): {
         maxAge: number;
@@ -187,6 +199,9 @@ declare class Trail3D {
             b: number;
             a: number;
         };
+        fade: {
+            keys: any[];
+        };
         textureURL: string;
         depthWrite: boolean;
         lightingEnabled: boolean;
@@ -216,6 +231,7 @@ declare namespace Trail3D {
 }
 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";

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":";AAgCA;;;;;GAKG;AACH;IA8PI,oCAMC;IAlQD;;;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;;;;;;;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;;;;;;;;;;;;;;;;aAwBC;IAED;;;;;;;;;;;;;;;;;;;;MAaC;IAED;;OAEG;IACH,cAFW,OAAO,WAcjB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAiEnB;;CAEJ;;;;;+BArd8B,+BAA+B;sBANxC,iCAAiC;oBACnC,kCAAkC;sBAQhC,2BAA2B;kCACf,uCAAuC;0BAX/C,yCAAyC;6BAYtC,mBAAmB"}
+{"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"}

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

@@ -7,11 +7,13 @@ 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;
@@ -94,8 +96,8 @@ class Trail3D {
     distanceSinceLastUpdate = 0;
 
     /**
-     * RGB tints the tube; alpha is the trail's base opacity, which the
-     * age-driven fade scales down to zero.
+     * RGB tints the tube; alpha is the trail's base opacity, which {@link fade}
+     * scales as each knot ages.
      *
      * Linear color space.
      * @readonly
@@ -103,6 +105,18 @@ class Trail3D {
      */
     color = new Color(1, 1, 1, 1);
 
+    /**
+     * Opacity over a knot's life. The curve's time is the knot's age over {@link maxAge} — `0` at
+     * birth, `1` when the knot disappears — and its value multiplies {@link color}'s alpha. The
+     * opacity meant is the trail's as seen, whatever the renderer has to do to the tube's faces to
+     * show it.
+     *
+     * Every trail starts on {@link TRAIL3D_FADE_LINEAR}, one shared instance, frozen — assign a
+     * curve of your own to reshape a trail's fade rather than editing that one.
+     * @type {AnimationCurve}
+     */
+    fade = TRAIL3D_FADE_LINEAR;
+
     /**
      * 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
@@ -308,7 +322,8 @@ class Trail3D {
                  depthWrite = false,
                  lightingEnabled = false,
                  offset = Vector3.zero,
-                 color = { r: 1, g: 1, b: 1, a: 1 }
+                 color = { r: 1, g: 1, b: 1, a: 1 },
+                 fade
              }) {
 
         this.maxAge = maxAge;
@@ -322,6 +337,16 @@ class Trail3D {
 
         this.offset.fromJSON(offset);
         this.color.fromJSON(color);
+
+        if (fade === undefined) {
+            this.fade = TRAIL3D_FADE_LINEAR;
+        } else {
+            const curve = new AnimationCurve();
+
+            curve.fromJSON(fade);
+
+            this.fade = curve;
+        }
     }
 
     toJSON() {
@@ -332,6 +357,7 @@ class Trail3D {
             spawnMode: this.spawnMode,
             spawnDistance: this.spawnDistance,
             color: this.color.toJSON(),
+            fade: this.fade.toJSON(),
             textureURL: this.textureURL,
             depthWrite: this.depthWrite,
             lightingEnabled: this.lightingEnabled,
@@ -352,6 +378,7 @@ class Trail3D {
             && this.spawnMode === other.spawnMode
             && this.spawnDistance === other.spawnDistance
             && this.color.equals(other.color)
+            && this.fade.equals(other.fade)
             && this.offset.equals(other.offset)
             ;
     }
@@ -470,7 +497,7 @@ class Trail3D {
         // 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.setKnotAlpha(head_index, this.fade.evaluate(clamp01(head_age / maxAge)) * this.color.w);
         tube.setKnotThickness(head_index, this.width);
 
         return head_position_changed;

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

@@ -34,7 +34,7 @@ export function advance_trail(trail, transform, timeDelta, simulator) {
 
     const age_offset = max2(0, trail.maxAge - trail.time);
 
-    simulator.update(tube, trail.maxAge, timeDelta, trail.color.w);
+    simulator.update(tube, trail.maxAge, timeDelta, trail.color.w, trail.fade);
 
     if (trail.getFlag(Trail3DFlags.Spawning)) {
         trail.updateHead(v3_head.x, v3_head.y, v3_head.z, age_offset);

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.d.ts

@@ -1,16 +1,16 @@
 /**
  * Fixed-function simulation for {@link TubeX} tubes — the 3D analogue of
- * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, fades its alpha from
- * `alpha` to zero as it approaches `max_age`, and flows the along-tube UV
- * coordinate with age.
+ * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, sets its alpha to `alpha` times the `fade`
+ * curve at its age relative to `max_age`, and flows the along-tube UV coordinate with age.
  */
 export class TubeXFixedPhysicsSimulator {
     /**
      * @param {TubeX} tube
      * @param {number} max_age
      * @param {number} timeDelta
-     * @param {number} [alpha] base alpha of an age-0 knot; the age fade scales it
+     * @param {number} alpha base alpha of a knot; the fade scales it
+     * @param {AnimationCurve} fade opacity over the knot's age relative to `max_age`, `0..1`
      */
-    update(tube: TubeX, max_age: number, timeDelta: number, alpha?: number): void;
+    update(tube: TubeX, max_age: number, timeDelta: number, alpha: number, fade: AnimationCurve): void;
 }
 //# sourceMappingURL=TubeXFixedPhysicsSimulator.d.ts.map

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TubeXFixedPhysicsSimulator.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IAEI;;;;;OAKG;IACH,6BAJW,MAAM,aACN,MAAM,UACN,MAAM,QAiBhB;CACJ"}
+{"version":3,"file":"TubeXFixedPhysicsSimulator.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IAEI;;;;;;OAMG;IACH,6BALW,MAAM,aACN,MAAM,SACN,MAAM,8BAkBhB;CACJ"}

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js

@@ -3,9 +3,8 @@ import { TUBE_ATTRIBUTE_ADDRESS_AGE, TUBE_ATTRIBUTE_ADDRESS_UV_V } from "../tube
 
 /**
  * Fixed-function simulation for {@link TubeX} tubes — the 3D analogue of
- * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, fades its alpha from
- * `alpha` to zero as it approaches `max_age`, and flows the along-tube UV
- * coordinate with age.
+ * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, sets its alpha to `alpha` times the `fade`
+ * curve at its age relative to `max_age`, and flows the along-tube UV coordinate with age.
  */
 export class TubeXFixedPhysicsSimulator {
 
@@ -13,9 +12,10 @@ export class TubeXFixedPhysicsSimulator {
      * @param {TubeX} tube
      * @param {number} max_age
      * @param {number} timeDelta
-     * @param {number} [alpha] base alpha of an age-0 knot; the age fade scales it
+     * @param {number} alpha base alpha of a knot; the fade scales it
+     * @param {AnimationCurve} fade opacity over the knot's age relative to `max_age`, `0..1`
      */
-    update(tube, max_age, timeDelta, alpha = 1) {
+    update(tube, max_age, timeDelta, alpha, fade) {
 
         const n = tube.getCount();
 
@@ -25,7 +25,7 @@ export class TubeXFixedPhysicsSimulator {
             const relative_age = clamp01(age / max_age);
 
             // fade out with age
-            tube.setKnotAlpha(i, (1.0 - relative_age) * alpha);
+            tube.setKnotAlpha(i, fade.evaluate(relative_age) * alpha);
 
             // flow the along-tube UV with age
             tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, relative_age);

package/src/engine/graphics3/trail/trail_tube_write_geometry.d.ts

@@ -20,6 +20,16 @@
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *
+ * **A knot's alpha is the opacity of the tube as seen, not of one face of it.** The tube is a closed
+ * hull drawn from both sides, so a line of sight through it crosses two faces, and the transparency
+ * pipeline composes their transmittances: written as is, an alpha of 0.5 would cover 0.75, and a
+ * linear fade would hold near solid for most of the trail's life and collapse at its tail. Each face
+ * therefore takes half the optical depth, `1 - √(1 - α)`, and the two together cover exactly `α`.
+ * This is the one place that knows the hull is crossed twice, so it is the one place that splits it;
+ * a ray through a bend crosses the tube twice over, and that overlap is real and reads denser. The
+ * alpha is clamped to `0..1` first, the range an opacity has — an authored fade curve may overshoot
+ * it, and the square root has no answer above one.
+ *
  * @param {Geometry} geometry
  * @param {TubeX} tube
  * @returns {void}

package/src/engine/graphics3/trail/trail_tube_write_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trail_tube_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/trail/trail_tube_write_geometry.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,4EAFa,IAAI,CAgEhB"}
+{"version":3,"file":"trail_tube_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/trail/trail_tube_write_geometry.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,4EAFa,IAAI,CAiEhB"}

package/src/engine/graphics3/trail/trail_tube_write_geometry.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { clamp01 } from "../../../core/math/clamp01.js";
 import {
     geometry_obtain_attribute,
     geometry_obtain_index
@@ -38,6 +39,16 @@ const TWO_PI = Math.PI * 2;
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *
+ * **A knot's alpha is the opacity of the tube as seen, not of one face of it.** The tube is a closed
+ * hull drawn from both sides, so a line of sight through it crosses two faces, and the transparency
+ * pipeline composes their transmittances: written as is, an alpha of 0.5 would cover 0.75, and a
+ * linear fade would hold near solid for most of the trail's life and collapse at its tail. Each face
+ * therefore takes half the optical depth, `1 - √(1 - α)`, and the two together cover exactly `α`.
+ * This is the one place that knows the hull is crossed twice, so it is the one place that splits it;
+ * a ray through a bend crosses the tube twice over, and that overlap is real and reads denser. The
+ * alpha is clamped to `0..1` first, the range an opacity has — an authored fade curve may overshoot
+ * it, and the square root has no answer above one.
+ *
  * @param {Geometry} geometry
  * @param {TubeX} tube
  * @returns {void}
@@ -94,7 +105,8 @@ export function trail_tube_write_geometry(geometry, tube) {
         colors[o] = halves[h];
         colors[o + 1] = halves[h + 1];
         colors[o + 2] = halves[h + 2];
-        colors[o + 3] = floats[f + TUBE_ATTRIBUTE_ADDRESS_ALPHA];
+        // half the optical depth: the face behind this one carries the other half
+        colors[o + 3] = 1 - Math.sqrt(1 - clamp01(floats[f + TUBE_ATTRIBUTE_ADDRESS_ALPHA]));
     }
 
     const source_indices = tube.indices;

package/src/engine/physics/cloth/ecs/cloth_geodesic.d.ts

@@ -14,8 +14,8 @@ export function cloth_edge_incidence(node_count: number, edge: Int32Array): {
  * Distance from every node to the nearest of a set of source nodes, along the
  * edges, and which source that is.
  *
- * A node marked in `blocked` can be reached but is never passed through. That is
- * Chaos Cloth's rule for its long-range attachments (`ClothTetherData.cpp`):
+ * A node marked in `blocked` can be reached but is never passed through.
+ * That is Chaos Cloth's rule for its long-range attachments:
  * a path from one island of held particles does not run through another, because
  * the far side of another island is that island's business.
  *

package/src/engine/physics/cloth/ecs/cloth_geodesic.js

@@ -65,8 +65,8 @@ export function cloth_edge_incidence(node_count, edge) {
  * Distance from every node to the nearest of a set of source nodes, along the
  * edges, and which source that is.
  *
- * A node marked in `blocked` can be reached but is never passed through. That is
- * Chaos Cloth's rule for its long-range attachments (`ClothTetherData.cpp`):
+ * A node marked in `blocked` can be reached but is never passed through.
+ * That is Chaos Cloth's rule for its long-range attachments:
  * a path from one island of held particles does not run through another, because
  * the far side of another island is that island's business.
  *

package/src/shade/playground/probe_clipmap/README.md

@@ -23,6 +23,7 @@ has the two lines that put it there. Another scene loads with `?scene=/some/othe
 | Indirect light | the probe clipmap, or IBL to compare against |
 | Debug view | the brick clipmap as the probes' rays see it; the geometry caches' mesh SDF; the hits' albedo from the cards |
 | Path tracer (P) | the accumulating path tracer's image in place of the rasterized one, as ground truth; TAA is off while it is on and comes back after |
+| Re-sampling (R) | each probe update pools its rays with what four of its neighbours have already seen, where their depth confirms it (`ProbeClipmapSettings.resampling`); off by default, and measured slower to converge and a few per cent brighter on Sponza (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8) |
 | Sun height, Sun turn | where the sun stands |
 | Point lights | eight shadowed point lights along the scene's long axis, which the probes' hits take as local lights |
 | TAA | the resolve the probe pick's noise is meant for |

package/src/shade/playground/probe_clipmap/index.html

@@ -108,6 +108,11 @@
         <span>Path tracer <span class="hint">— ground truth; P flips it</span></span>
     </label>
 
+    <label>
+        <input type="checkbox" id="resampling">
+        <span>Re-sampling <span class="hint">— probes take their neighbours' radiance; R flips it</span></span>
+    </label>
+
     <hr>
 
     <label>

package/src/shade/playground/probe_clipmap/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/probe_clipmap/main.js"],"names":[],"mappings":"AA0FA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CA8QzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/probe_clipmap/main.js"],"names":[],"mappings":"AA0FA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CA4RzB"}

package/src/shade/playground/probe_clipmap/main.js

@@ -282,12 +282,26 @@ export async function start() {
 
     path_tracing_toggle.addEventListener('change', event => set_path_tracing(event.target.checked));
 
+    const resampling_toggle = element('resampling');
+
+    resampling_toggle.checked = renderer.probe_clipmap.resampling;
+    resampling_toggle.addEventListener('change', event => {
+        renderer.probe_clipmap.resampling = event.target.checked;
+    });
+
     document.addEventListener('keydown', event => {
-        // not while typing a number, nor in a select, where P picks an option
+        // not while typing a number, nor in a select, where P and R pick an option
         const typing = event.target === bake_budget || event.target instanceof HTMLSelectElement;
 
-        if (event.code === 'KeyP' && event.repeat === false && typing === false) {
+        if (event.repeat || typing) {
+            return;
+        }
+
+        if (event.code === 'KeyP') {
             set_path_tracing(!renderer.feature_path_tracing_enabled);
+        } else if (event.code === 'KeyR') {
+            resampling_toggle.checked = !resampling_toggle.checked;
+            renderer.probe_clipmap.resampling = resampling_toggle.checked;
         }
     });
 

package/src/shade/playground/vgeo_scene/README.md

@@ -273,7 +273,7 @@ every vertex shader over a meshlet emits that instance's triangle corners in the
 `triangle_list_reverse_winding`. The draw is non-indexed and the vertex shader resolves its own
 index, so which corner lands where is already the shader's choice; reversing it costs a `select`,
 no second pipeline, and no fourth field in the bucket key. It is what Nanite does for the same
-reason (`FInstanceSceneData::DeterminantSign`, read in `HWRasterizeVS`), and what the glTF spec
+reason, and what the glTF spec
 requires of a conformant renderer. The tangent frame's handedness flips with it.
 
 The parameters remain, and now read as diagnostics rather than as fixes:

package/src/shade/renderer/atmosphere/MULTISCATTER_LUT_CONFIG.d.ts

@@ -1,21 +1,19 @@
 /**
  * Directions are drawn on an 8x8 grid, stratified in azimuth and in the cosine of the polar
- * angle. Matches Hillaire's `SQRTSAMPLECOUNT`.
+ * angle.
  * @type {number}
  */
 export const MULTISCATTER_LUT_SQRT_SAMPLES: number;
 /**
  * One thread integrates one direction, so this is also the workgroup size.
  *
- * 64 is Hillaire's `[numthreads(1,1,64)]` count. It is a multiple of every legal subgroup
- * size up to 64, and the reduction handles a subgroup wider than the workgroup, so no
- * hardware needs a different number here.
+ * 64 is a multiple of every legal subgroup size up to 64, and the reduction handles a
+ * subgroup wider than the workgroup, so no hardware needs a different number here.
  * @type {number}
  */
 export const MULTISCATTER_LUT_DIRECTION_COUNT: number;
 /**
- * Ray-march steps per direction. Hillaire's `SampleCountIni` for this LUT; the comment there
- * reads "a minimum set of step is required for accuracy unfortunately".
+ * Ray-march steps per direction for this LUT.
  *
  * Compile-time on purpose: as a uniform the inner loop cannot be unrolled and the trip count
  * has to be re-tested against an f32 every iteration.

package/src/shade/renderer/atmosphere/MULTISCATTER_LUT_CONFIG.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MULTISCATTER_LUT_CONFIG.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/MULTISCATTER_LUT_CONFIG.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;GAOG;AACH,+CAFU,MAAM,CAE8F;AAE9G;;;;;;;GAOG;AACH,qCAFU,MAAM,CAEyB;AAEzC;;;;;;;GAOG;AACH,qDAFU,MAAM,CAE2E"}
+{"version":3,"file":"MULTISCATTER_LUT_CONFIG.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/MULTISCATTER_LUT_CONFIG.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;GAMG;AACH,+CAFU,MAAM,CAE8F;AAE9G;;;;;;GAMG;AACH,qCAFU,MAAM,CAEyB;AAEzC;;;;;;;GAOG;AACH,qDAFU,MAAM,CAE2E"}

package/src/shade/renderer/atmosphere/MULTISCATTER_LUT_CONFIG.js

@@ -1,36 +1,34 @@
-/**
- * Directions are drawn on an 8x8 grid, stratified in azimuth and in the cosine of the polar
- * angle. Matches Hillaire's `SQRTSAMPLECOUNT`.
- * @type {number}
- */
-export const MULTISCATTER_LUT_SQRT_SAMPLES = 8;
-
-/**
- * One thread integrates one direction, so this is also the workgroup size.
- *
- * 64 is Hillaire's `[numthreads(1,1,64)]` count. It is a multiple of every legal subgroup
- * size up to 64, and the reduction handles a subgroup wider than the workgroup, so no
- * hardware needs a different number here.
- * @type {number}
- */
-export const MULTISCATTER_LUT_DIRECTION_COUNT = MULTISCATTER_LUT_SQRT_SAMPLES * MULTISCATTER_LUT_SQRT_SAMPLES;
-
-/**
- * Ray-march steps per direction. Hillaire's `SampleCountIni` for this LUT; the comment there
- * reads "a minimum set of step is required for accuracy unfortunately".
- *
- * Compile-time on purpose: as a uniform the inner loop cannot be unrolled and the trip count
- * has to be re-tested against an f32 every iteration.
- * @type {number}
- */
-export const MULTISCATTER_LUT_STEPS = 20;
-
-/**
- * Upper bound on the number of subgroups in one workgroup, which is how many partial sums
- * the cross-subgroup reduction has to combine.
- *
- * WGSL pins the subgroup size to a power of two in [4, 128], so the worst case is
- * {@link MULTISCATTER_LUT_DIRECTION_COUNT} / 4.
- * @type {number}
- */
-export const MULTISCATTER_LUT_MAX_SUBGROUP_PARTIALS = MULTISCATTER_LUT_DIRECTION_COUNT / 4;
+/**
+ * Directions are drawn on an 8x8 grid, stratified in azimuth and in the cosine of the polar
+ * angle.
+ * @type {number}
+ */
+export const MULTISCATTER_LUT_SQRT_SAMPLES = 8;
+
+/**
+ * One thread integrates one direction, so this is also the workgroup size.
+ *
+ * 64 is a multiple of every legal subgroup size up to 64, and the reduction handles a
+ * subgroup wider than the workgroup, so no hardware needs a different number here.
+ * @type {number}
+ */
+export const MULTISCATTER_LUT_DIRECTION_COUNT = MULTISCATTER_LUT_SQRT_SAMPLES * MULTISCATTER_LUT_SQRT_SAMPLES;
+
+/**
+ * Ray-march steps per direction for this LUT.
+ *
+ * Compile-time on purpose: as a uniform the inner loop cannot be unrolled and the trip count
+ * has to be re-tested against an f32 every iteration.
+ * @type {number}
+ */
+export const MULTISCATTER_LUT_STEPS = 20;
+
+/**
+ * Upper bound on the number of subgroups in one workgroup, which is how many partial sums
+ * the cross-subgroup reduction has to combine.
+ *
+ * WGSL pins the subgroup size to a power of two in [4, 128], so the worst case is
+ * {@link MULTISCATTER_LUT_DIRECTION_COUNT} / 4.
+ * @type {number}
+ */
+export const MULTISCATTER_LUT_MAX_SUBGROUP_PARTIALS = MULTISCATTER_LUT_DIRECTION_COUNT / 4;

package/src/shade/renderer/atmosphere/chunk_get_multiscatter_values.d.ts

@@ -6,7 +6,7 @@
  * mean, which is what the paper's uniform phase p_u = 1/(4*PI) reduces to.
  *
  * Splitting one direction out of the loop is what lets `shader_multiscatter_lut` put a
- * thread on each of the 64 directions, the way Hillaire's `NewMultiScattCS` does.
+ * thread on each of the 64 directions.
  *
  * `pos` is assumed to be inside the atmosphere and at or above the surface, which is what
  * makes the far root of the outer sphere the atmosphere exit.

package/src/shade/renderer/atmosphere/chunk_get_multiscatter_values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_get_multiscatter_values.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_get_multiscatter_values.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;GAgBG;AACH,4CAFU,SAAS,CA4HlB;0BAjJyB,iCAAiC"}
+{"version":3,"file":"chunk_get_multiscatter_values.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_get_multiscatter_values.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;GAgBG;AACH,4CAFU,SAAS,CA2HlB;0BAhJyB,iCAAiC"}