@woosh/meep-engine 2.165.2 → 2.165.4

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.165.2",
+  "version": "2.165.4",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Convolve 3-band spherical harmonic coefficients with a zonal harmonic kernel.
+ *
+ * Convolution with a circularly-symmetric (zonal) kernel is a per-band scale: band 0 is scaled by
+ * `zh0`, band 1 by `zh1` and band 2 by `zh2`. The kernel coefficients are expected to already include
+ * the `sqrt(4*PI / (2l + 1))` convolution normalization (as e.g. {@link sh3_ggx_zh} does).
+ *
+ * Layout is coefficient-major with `dimensions` interleaved channels per coefficient, matching
+ * {@link sh3_vector_accumulate}. Safe to use in-place (`out === input` with equal offsets).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number} zh0 band 0 scale
+ * @param {number} zh1 band 1 scale
+ * @param {number} zh2 band 2 scale
+ * @param {number} dimensions number of interleaved channels per coefficient, e.g. 3 for RGB
+ */
+export function sh3_convolve_with_zh(out: number[] | Float32Array | Float64Array, out_offset: number, input: number[] | Float32Array | Float64Array, input_offset: number, zh0: number, zh1: number, zh2: number, dimensions: number): void;
+//# sourceMappingURL=sh3_convolve_with_zh.d.ts.map

package/src/core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh3_convolve_with_zh.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0CATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,cACN,MAAM,QAiChB"}

package/src/core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.js

@@ -0,0 +1,53 @@
+import { assert } from "../../../../assert.js";
+
+/**
+ * Convolve 3-band spherical harmonic coefficients with a zonal harmonic kernel.
+ *
+ * Convolution with a circularly-symmetric (zonal) kernel is a per-band scale: band 0 is scaled by
+ * `zh0`, band 1 by `zh1` and band 2 by `zh2`. The kernel coefficients are expected to already include
+ * the `sqrt(4*PI / (2l + 1))` convolution normalization (as e.g. {@link sh3_ggx_zh} does).
+ *
+ * Layout is coefficient-major with `dimensions` interleaved channels per coefficient, matching
+ * {@link sh3_vector_accumulate}. Safe to use in-place (`out === input` with equal offsets).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number} zh0 band 0 scale
+ * @param {number} zh1 band 1 scale
+ * @param {number} zh2 band 2 scale
+ * @param {number} dimensions number of interleaved channels per coefficient, e.g. 3 for RGB
+ */
+export function sh3_convolve_with_zh(
+    out, out_offset,
+    input, input_offset,
+    zh0, zh1, zh2,
+    dimensions
+) {
+    assert.isArrayLike(out, 'out');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isArrayLike(input, 'input');
+    assert.isNonNegativeInteger(input_offset, 'input_offset');
+    assert.isNumber(zh0, 'zh0');
+    assert.isNumber(zh1, 'zh1');
+    assert.isNumber(zh2, 'zh2');
+    assert.isNonNegativeInteger(dimensions, 'dimensions');
+
+    const band_1_end = 4 * dimensions;
+    const band_2_end = 9 * dimensions;
+
+    let i = 0;
+
+    for (; i < dimensions; i++) {
+        out[out_offset + i] = input[input_offset + i] * zh0;
+    }
+
+    for (; i < band_1_end; i++) {
+        out[out_offset + i] = input[input_offset + i] * zh1;
+    }
+
+    for (; i < band_2_end; i++) {
+        out[out_offset + i] = input[input_offset + i] * zh2;
+    }
+}

package/src/core/geom/3d/sphere/harmonics/sh3_ggx_zh.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Zonal harmonic coefficients approximating a GGX lobe of the given roughness.
+ *
+ * Convolving a radiance SH with these coefficients (see {@link sh3_convolve_with_zh}) low-passes it with
+ * a GGX-shaped cone: band 0 is preserved while bands 1 and 2 are attenuated progressively harder as
+ * `alpha` grows. Attenuating the directional bands tapers the SH reconstruction towards its mean,
+ * which suppresses ringing (negative lobes / light bleeding) at the cost of directional sharpness.
+ *
+ * The rational fit is from MJP's SH library.
+ *
+ * @see https://github.com/TheRealMJP/SHforHLSL/blob/e426058959123063e13d61a62df6217259b72cec/SH.hlsli#L394
+ *
+ * @param {number[]|Float32Array|Float64Array} out zonal coefficients [l0, l1, l2] are written here
+ * @param {number} out_offset
+ * @param {number} alpha GGX roughness (perceptual roughness squared) in [0, 1]; the fit is only valid in this range
+ */
+export function sh3_ggx_zh(out: number[] | Float32Array | Float64Array, out_offset: number, alpha: number): void;
+//# sourceMappingURL=sh3_ggx_zh.d.ts.map

package/src/core/geom/3d/sphere/harmonics/sh3_ggx_zh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh3_ggx_zh.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_ggx_zh.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,gCAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,MAAM,QAahB"}

package/src/core/geom/3d/sphere/harmonics/sh3_ggx_zh.js

@@ -0,0 +1,30 @@
+import { assert } from "../../../../assert.js";
+
+/**
+ * Zonal harmonic coefficients approximating a GGX lobe of the given roughness.
+ *
+ * Convolving a radiance SH with these coefficients (see {@link sh3_convolve_with_zh}) low-passes it with
+ * a GGX-shaped cone: band 0 is preserved while bands 1 and 2 are attenuated progressively harder as
+ * `alpha` grows. Attenuating the directional bands tapers the SH reconstruction towards its mean,
+ * which suppresses ringing (negative lobes / light bleeding) at the cost of directional sharpness.
+ *
+ * The rational fit is from MJP's SH library.
+ *
+ * @see https://github.com/TheRealMJP/SHforHLSL/blob/e426058959123063e13d61a62df6217259b72cec/SH.hlsli#L394
+ *
+ * @param {number[]|Float32Array|Float64Array} out zonal coefficients [l0, l1, l2] are written here
+ * @param {number} out_offset
+ * @param {number} alpha GGX roughness (perceptual roughness squared) in [0, 1]; the fit is only valid in this range
+ */
+export function sh3_ggx_zh(out, out_offset, alpha) {
+    assert.isArrayLike(out, 'out');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isNumber(alpha, 'alpha');
+    assert.notNaN(alpha, 'alpha');
+    assert.greaterThanOrEqual(alpha, 0, 'alpha');
+    assert.lessThanOrEqual(alpha, 1, 'alpha');
+
+    out[out_offset] = 1;
+    out[out_offset + 1] = 1.66711256633276 / (1.65715038133932 + alpha);
+    out[out_offset + 2] = 1.56127990596116 / (0.96989757593282 + alpha) - 0.599972342361123;
+}

package/src/engine/graphics/ecs/trail2d/Trail2D.d.ts

@@ -43,6 +43,8 @@ declare class Trail2D {
      */
     distanceSinceLastUpdate: number;
     /**
+     * RGB tints the ribbon; alpha is the trail's base opacity, which the
+     * age-driven fade scales down to zero.
      * @readonly
      * @type {Color}
      */

package/src/engine/graphics/ecs/trail2d/Trail2D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAwBA;IAgMI,oCAMC;IApMD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAGpB;;OAEG;IACH,cAsBC;IAUD;;;;;;;;;;;;;aAkBC;IAGD;;;;;;;;;;;;;;;;;MAUC;IAED;;;OAGG;IACH,cAFW,OAAO,WAWjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAkEnB;CAEJ;;;;;;+BAnV8B,+BAA+B;sBALxC,iCAAiC;oBACnC,kCAAkC;wBAM9B,0BAA0B;oCACd,sCAAsC;0BAThD,yCAAyC;6BAWtC,mBAAmB;kCADd,wBAAwB"}
+{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAwBA;IAkMI,oCAMC;IAtMD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAGpB;;OAEG;IACH,cAsBC;IAUD;;;;;;;;;;;;;aAkBC;IAGD;;;;;;;;;;;;;;;;;MAUC;IAED;;;OAGG;IACH,cAFW,OAAO,WAWjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAmEnB;CAEJ;;;;;;+BAtV8B,+BAA+B;sBALxC,iCAAiC;oBACnC,kCAAkC;wBAM9B,0BAA0B;oCACd,sCAAsC;0BAThD,yCAAyC;6BAWtC,mBAAmB;kCADd,wBAAwB"}

package/src/engine/graphics/ecs/trail2d/Trail2D.js

@@ -74,6 +74,8 @@ class Trail2D {
     distanceSinceLastUpdate = 0;
 
     /**
+     * RGB tints the ribbon; alpha is the trail's base opacity, which the
+     * age-driven fade scales down to zero.
      * @readonly
      * @type {Color}
      */
@@ -336,9 +338,10 @@ class Trail2D {
             this.setFlag(Trail2DFlags.BoundsNeedUpdate);
         }
 
-        // set head to fresh value
+        // set head to fresh value; alpha follows the same fade law the simulator
+        // applies every tick, so the point doesn't pop when it stops being the head
         ribbon.setPointAttribute_Scalar(head_index, RIBBON_ATTRIBUTE_ADDRESS_AGE, head_age);
-        ribbon.setPointAlpha(head_index, clamp01(head_age / maxAge));
+        ribbon.setPointAlpha(head_index, (1 - clamp01(head_age / maxAge)) * this.color.w);
         ribbon.setPointThickness(head_index, this.width);
 
         return head_position_changed;

package/src/engine/graphics/ecs/trail2d/Trail2DSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail2DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2DSystem.js"],"names":[],"mappings":";AA0BA;IAkCI;;;OAGG;IACH,4BA4BC;IAjED,oDAAoC;IAEpC,+DAEE;IAEF;;;OAGG;IACH,WAFU,4BAA4B,CAES;IAE/C;;;;OAIG;IACH,wBAAiC;IAGjC;;;;OAIG;IACH,oBAAgB;IAEhB;;;OAGG;IACH,YAAgB;IAcZ;;;;OAIG;IACH,iBAAsB;IAEtB;;;OAGG;IACH,UAFU,cAAc,CAEO;IAE/B;;;OAGG;IACH,aAFU,cAAY,IAAI,CAEH;IAK3B,2CAmBC;IAED,4CAIC;IAED;;;;;OAKG;IACH,sBAqDC;IAED;;;;;OAKG;IACH,YAHW,OAAO,aADP,SAAS,YAET,MAAM,QAahB;IAED;;;;;OAKG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAShB;IAED;;;;OAIG;IACH,yBAHW,OAAO,aACP,SAAS,QAoCnB;IAED,6BAWC;CACJ;uBArQsB,wBAAwB;0BACrB,qCAAqC;oBAY3C,cAAc;4CAdU,uDAAuD;6CAYtD,yDAAyD;+BARvE,yBAAyB"}
+{"version":3,"file":"Trail2DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2DSystem.js"],"names":[],"mappings":";AA0BA;IAkCI;;;OAGG;IACH,4BA4BC;IAjED,oDAAoC;IAEpC,+DAEE;IAEF;;;OAGG;IACH,WAFU,4BAA4B,CAES;IAE/C;;;;OAIG;IACH,wBAAiC;IAGjC;;;;OAIG;IACH,oBAAgB;IAEhB;;;OAGG;IACH,YAAgB;IAcZ;;;;OAIG;IACH,iBAAsB;IAEtB;;;OAGG;IACH,UAFU,cAAc,CAEO;IAE/B;;;OAGG;IACH,aAFU,cAAY,IAAI,CAEH;IAK3B,2CAmBC;IAED,4CAIC;IAED;;;;;OAKG;IACH,sBAsDC;IAED;;;;;OAKG;IACH,YAHW,OAAO,aADP,SAAS,YAET,MAAM,QAahB;IAED;;;;;OAKG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAShB;IAED;;;;OAIG;IACH,yBAHW,OAAO,aACP,SAAS,QAoCnB;IAED,6BAWC;CACJ;uBAtQsB,wBAAwB;0BACrB,qCAAqC;oBAY3C,cAAc;4CAdU,uDAAuD;6CAYtD,yDAAyD;+BARvE,yBAAyB"}

package/src/engine/graphics/ecs/trail2d/Trail2DSystem.js

@@ -167,7 +167,8 @@ class Trail2DSystem extends System {
             ribbon.setPointPosition(i, position_x, position_y, position_z);
             ribbon.setPointThickness(i, trail.width);
             ribbon.setPointAttribute_Scalar(i, RIBBON_ATTRIBUTE_ADDRESS_UV_OFFSET, f);
-            ribbon.setPointAlpha(i, color.w);
+            // seeded age = maxAge means "already expired", so alpha follows the fade law: 0
+            ribbon.setPointAlpha(i, 0);
             ribbon.setPointAttribute_Scalar(i, RIBBON_ATTRIBUTE_ADDRESS_AGE, trail.maxAge);
 
         }
@@ -238,7 +239,7 @@ class Trail2DSystem extends System {
 
         const ageOffset = max2(0, trail.maxAge - trail.time);
 
-        this.simulator.update(ribbon, trail.maxAge, timeDelta);
+        this.simulator.update(ribbon, trail.maxAge, timeDelta, trail.color.w);
 
         if (trail.getFlag(Trail2DFlags.Spawning)) {
             trail.updateHead(newPosition.x, newPosition.y, newPosition.z, ageOffset);

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

@@ -54,6 +54,8 @@ 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.
      * @readonly
      * @type {Color}
      */

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;IA4MI,oCAMC;IAhND;;;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;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,KAAK,GAAC,IAAI,CAER;IAEZ;;;OAGG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAUD,6BAEC;IAND,0BAEC;IAMD;;;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;;OAEG;IACH,qBAFW,MAAM,QAehB;IAED;;OAEG;IACH,cAmBC;IAUD;;;;;;;;;;;;;;;aAsBC;IAED;;;;;;;;;;;;;;;;;;;MAYC;IAED;;OAEG;IACH,cAFW,OAAO,WAajB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAgEnB;;CAEJ;;;;;+BA9Z8B,+BAA+B;sBAPxC,iCAAiC;oBACnC,kCAAkC;sBAShC,2BAA2B;kCACf,uCAAuC;0BAZ/C,yCAAyC;6BAatC,mBAAmB"}
+{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAgCA;;;;;GAKG;AACH;IA8MI,oCAMC;IAlND;;;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;;;;;OAKG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,KAAK,GAAC,IAAI,CAER;IAEZ;;;OAGG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAUD,6BAEC;IAND,0BAEC;IAMD;;;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;;OAEG;IACH,qBAFW,MAAM,QAehB;IAED;;OAEG;IACH,cAmBC;IAUD;;;;;;;;;;;;;;;aAsBC;IAED;;;;;;;;;;;;;;;;;;;MAYC;IAED;;OAEG;IACH,cAFW,OAAO,WAajB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAiEnB;;CAEJ;;;;;+BAja8B,+BAA+B;sBAPxC,iCAAiC;oBACnC,kCAAkC;sBAShC,2BAA2B;kCACf,uCAAuC;0BAZ/C,yCAAyC;6BAatC,mBAAmB"}

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

@@ -94,6 +94,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.
      * @readonly
      * @type {Color}
      */
@@ -413,9 +415,10 @@ class Trail3D {
             this.setFlag(Trail3DFlags.BoundsNeedUpdate);
         }
 
-        // set head to fresh value
+        // 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, clamp01(head_age / maxAge));
+        tube.setKnotAlpha(head_index, (1 - clamp01(head_age / maxAge)) * this.color.w);
         tube.setKnotThickness(head_index, this.width);
 
         return head_position_changed;

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

@@ -1 +1 @@
-{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3DSystem.js"],"names":[],"mappings":";AAyBA;IAiCI;;;OAGG;IACH,4BAkBC;IAtDD,oDAAoC;IAEpC,+DAEE;IAEF;;OAEG;IACH,WAFU,0BAA0B,CAES;IAiB7C;;;OAGG;IACH,YAAgB;IAeZ;;OAEG;IACH,UAFU,cAAc,CAEO;IAE/B;;OAEG;IACH,aAFU,cAAY,IAAI,CAEH;IAG3B,2CAmBC;IAED,4CAIC;IA0DD;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,YACT,MAAM,QAYhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAkCnB;IAED,6BAWC;;CACJ;uBA7OsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}
+{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3DSystem.js"],"names":[],"mappings":";AAyBA;IAiCI;;;OAGG;IACH,4BAkBC;IAtDD,oDAAoC;IAEpC,+DAEE;IAEF;;OAEG;IACH,WAFU,0BAA0B,CAES;IAiB7C;;;OAGG;IACH,YAAgB;IAeZ;;OAEG;IACH,UAFU,cAAc,CAEO;IAE/B;;OAEG;IACH,aAFU,cAAY,IAAI,CAEH;IAG3B,2CAmBC;IAED,4CAIC;IA2DD;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,YACT,MAAM,QAYhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAkCnB;IAED,6BAWC;;CACJ;uBA9OsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}

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

@@ -151,7 +151,8 @@ class Trail3DSystem extends System {
             tube.setKnotPosition(i, position_x, position_y, position_z);
             tube.setKnotThickness(i, trail.width);
             tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
-            tube.setKnotAlpha(i, color.w);
+            // seeded age = maxAge means "already expired", so alpha follows the fade law: 0
+            tube.setKnotAlpha(i, 0);
             tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, trail.maxAge);
         }
 
@@ -215,7 +216,7 @@ class Trail3DSystem extends System {
 
         const ageOffset = max2(0, trail.maxAge - trail.time);
 
-        this.simulator.update(tube, trail.maxAge, timeDelta);
+        this.simulator.update(tube, trail.maxAge, timeDelta, trail.color.w);
 
         if (trail.getFlag(Trail3DFlags.Spawning)) {
             trail.updateHead(newPosition.x, newPosition.y, newPosition.z, ageOffset);

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.d.ts

@@ -1,9 +1,45 @@
 export class LightProbeGridBaker {
+    /**
+     * Directions sampled one hit deep per probe. Direct light and sky converge with this count,
+     * every candidate also feeds the back-face visibility statistic.
+     *
+     * The defaults match the directional noise of the previous 4096-full-path bake at roughly half
+     * the cost (candidates are single-segment); raise both counts together for higher quality.
+     * @type {number}
+     */
+    candidate_count: number;
+    /**
+     * Full multi-bounce path traces per probe, re-sampled from the candidates by first-bounce
+     * importance. Only the indirect part of the estimate rides on these, so far fewer are needed
+     * than candidates.
+     * @type {number}
+     */
+    indirect_sample_count: number;
+    /**
+     * Total path depth including the first hit
+     * @type {number}
+     */
+    max_bounce_count: number;
+    /**
+     * GGX roughness of the prefilter cone applied to the baked radiance SH, in [0, 1].
+     * Attenuates band 1 before the 2-band truncation, suppressing directional overshoot that would
+     * otherwise reconstruct as negative irradiance (light/shadow bleeding) on the far side of a
+     * strong light. Higher values trade directionality for stability.
+     * @type {number}
+     */
+    filter_ggx_alpha: number;
+    /**
+     * A probe whose fraction of candidate rays hitting geometry back-faces exceeds this threshold is
+     * considered to be inside geometry. Such probes are filled from their valid neighbors after the
+     * bake instead of contributing interior darkness to trilinear filtering.
+     * @type {number}
+     */
+    interior_backface_threshold: number;
     /**
      * Renderer used to bake probes. Exposed so callers (and tests) can configure the underlying scene.
-     * @return {ProbeRenderer}
+     * @return {PathTracerProbeRenderer}
      */
-    get renderer(): ProbeRenderer;
+    get renderer(): PathTracerProbeRenderer;
     /**
      * Bake light probes
      * @returns {TaskGroup}
@@ -13,12 +49,15 @@ export class LightProbeGridBaker {
     bake(grid: LightProbeGrid, ecd: EntityComponentDataset): TaskGroup;
     /**
      *
-     * @param {ProbeRenderer} renderer
+     * @param {PathTracerProbeRenderer} renderer
      * @param {LightProbeGrid} grid
      * @param {number} probe_index
+     * @returns {boolean} true if the probe is valid, false if it appears to be inside geometry and
+     * should be filled from its neighbors
      */
-    bake_probe(renderer: ProbeRenderer, grid: LightProbeGrid, probe_index: number): void;
+    bake_probe(renderer: PathTracerProbeRenderer, grid: LightProbeGrid, probe_index: number): boolean;
     #private;
 }
+import { PathTracerProbeRenderer } from "../lpv/PathTracerProbeRenderer.js";
 import TaskGroup from "../../../../core/process/task/TaskGroup.js";
 //# sourceMappingURL=LightProbeGridBaker.d.ts.map

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightProbeGridBaker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/LightProbeGridBaker.js"],"names":[],"mappings":"AAWA;IAII;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,yDAJa,SAAS,CA2CrB;IAED;;;;;OAKG;IACH,uEAFW,MAAM,QAYhB;;CACJ;sBArFqB,4CAA4C"}
+{"version":3,"file":"LightProbeGridBaker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/LightProbeGridBaker.js"],"names":[],"mappings":"AAgBA;IAII;;;;;;;OAOG;IACH,iBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,uBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,6BAFU,MAAM,CAEmB;IAEnC;;;OAGG;IACH,wCAEC;IAED;;;;;OAKG;IACH,yDAJa,SAAS,CAoDrB;IAED;;;;;;;OAOG;IACH,qBANW,uBAAuB,qCAEvB,MAAM,GACJ,OAAO,CAuBnB;;CACJ;wCAlJuC,mCAAmC;sBAJrD,4CAA4C"}

package/src/engine/graphics/sh3/lpg/LightProbeGridBaker.js

@@ -1,21 +1,67 @@
 import { assert } from "../../../../core/assert.js";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { sh3_convolve_with_zh } from "../../../../core/geom/3d/sphere/harmonics/sh3_convolve_with_zh.js";
+import { sh3_ggx_zh } from "../../../../core/geom/3d/sphere/harmonics/sh3_ggx_zh.js";
 import TaskGroup from "../../../../core/process/task/TaskGroup.js";
 import { actionTask } from "../../../../core/process/task/util/actionTask.js";
 import { countTask } from "../../../../core/process/task/util/countTask.js";
 import { promiseTask } from "../../../../core/process/task/util/promiseTask.js";
 import { PathTracerProbeRenderer } from "../lpv/PathTracerProbeRenderer.js";
+import { bake_probe_sh3_resampled } from "./bake_probe_sh3_resampled.js";
+import { light_probe_grid_dilate } from "./light_probe_grid_dilate.js";
 
 const __position = new Float32Array(3);
 const __sh3_rgb = new Float64Array(27);
+const __zh = new Float64Array(3);
 
 export class LightProbeGridBaker {
 
     #ren = new PathTracerProbeRenderer();
 
+    /**
+     * Directions sampled one hit deep per probe. Direct light and sky converge with this count,
+     * every candidate also feeds the back-face visibility statistic.
+     *
+     * The defaults match the directional noise of the previous 4096-full-path bake at roughly half
+     * the cost (candidates are single-segment); raise both counts together for higher quality.
+     * @type {number}
+     */
+    candidate_count = 2048;
+
+    /**
+     * Full multi-bounce path traces per probe, re-sampled from the candidates by first-bounce
+     * importance. Only the indirect part of the estimate rides on these, so far fewer are needed
+     * than candidates.
+     * @type {number}
+     */
+    indirect_sample_count = 512;
+
+    /**
+     * Total path depth including the first hit
+     * @type {number}
+     */
+    max_bounce_count = 5;
+
+    /**
+     * GGX roughness of the prefilter cone applied to the baked radiance SH, in [0, 1].
+     * Attenuates band 1 before the 2-band truncation, suppressing directional overshoot that would
+     * otherwise reconstruct as negative irradiance (light/shadow bleeding) on the far side of a
+     * strong light. Higher values trade directionality for stability.
+     * @type {number}
+     */
+    filter_ggx_alpha = 0.5;
+
+    /**
+     * A probe whose fraction of candidate rays hitting geometry back-faces exceeds this threshold is
+     * considered to be inside geometry. Such probes are filled from their valid neighbors after the
+     * bake instead of contributing interior darkness to trilinear filtering.
+     * @type {number}
+     */
+    interior_backface_threshold = 0.25;
+
     /**
      * Renderer used to bake probes. Exposed so callers (and tests) can configure the underlying scene.
-     * @return {ProbeRenderer}
+     * @return {PathTracerProbeRenderer}
      */
     get renderer() {
         return this.#ren;
@@ -40,8 +86,10 @@ export class LightProbeGridBaker {
 
         const probe_count = grid.count;
 
+        const validity = new Uint8Array(probe_count);
+
         const tBakeIrradiance = countTask(0, probe_count, (probe_index) => {
-            this.bake_probe(renderer, grid, probe_index);
+            validity[probe_index] = this.bake_probe(renderer, grid, probe_index) ? 1 : 0;
 
         });
         tBakeIrradiance.estimatedDuration = probe_count;
@@ -57,6 +105,13 @@ export class LightProbeGridBaker {
         const tFinish = actionTask(() => {
             renderer.bake_end();
 
+            // probes inside geometry take on the average of their valid neighbors, so trilinear
+            // sampling near walls does not blend in interior darkness
+            light_probe_grid_dilate(
+                grid.harmonics, validity,
+                grid.resolution_x, grid.resolution_y, grid.resolution_z
+            );
+
             grid.incrementVersion();
         });
 
@@ -70,19 +125,31 @@ export class LightProbeGridBaker {
 
     /**
      *
-     * @param {ProbeRenderer} renderer
+     * @param {PathTracerProbeRenderer} renderer
      * @param {LightProbeGrid} grid
      * @param {number} probe_index
+     * @returns {boolean} true if the probe is valid, false if it appears to be inside geometry and
+     * should be filled from its neighbors
      */
     bake_probe(renderer, grid, probe_index) {
         assert.isNonNegativeInteger(probe_index, 'probe_index');
 
         grid.probe_position(__position, 0, probe_index);
 
-        // render a full SH3 probe with the shared facilities
-        renderer.bake(__position, 0, __sh3_rgb, 0);
+        const backface_fraction = bake_probe_sh3_resampled(
+            __sh3_rgb, 0,
+            renderer.scene, renderer.tracer, renderer.random,
+            __position, 0,
+            this.candidate_count, this.indirect_sample_count, this.max_bounce_count
+        );
+
+        // prefilter the radiance with a GGX cone before truncation, taming band-1 overshoot
+        sh3_ggx_zh(__zh, 0, this.filter_ggx_alpha);
+        sh3_convolve_with_zh(__sh3_rgb, 0, __sh3_rgb, 0, __zh[0], __zh[1], __zh[2], 3);
 
         // keep only bands 0 and 1: the coefficient-major layout puts them in the first 12 values
         array_copy(__sh3_rgb, 0, grid.harmonics, probe_index * 12, 12);
+
+        return backface_fraction <= this.interior_backface_threshold;
     }
 }

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bake a single SH3 radiance probe with importance re-sampling and back-face visibility rejection.
+ *
+ * Two-phase estimator, split by path length:
+ *
+ * 1. Candidate phase: `candidate_count` uniform sphere directions are traced one hit deep. Misses
+ *    take the background radiance; front-face hits take `emissive + albedo * direct_light`, both of
+ *    which are cheap and low-noise, and every such sample is projected onto the SH. Directions whose
+ *    first hit is a back face see the inside of geometry — they are rejected and the estimate is
+ *    renormalized over the remaining directions, so interior darkness does not bleed into the probe.
+ *
+ * 2. Indirect phase: `indirect_sample_count` continuations are picked from the hit candidates with
+ *    probability proportional to their first-bounce luminance (resampled importance sampling — the
+ *    selection a weighted reservoir would produce, drawn from the materialized candidate table), and
+ *    only these few directions pay for a full multi-bounce path trace. The 1/p_hat re-sampling weight
+ *    keeps the combined estimator unbiased.
+ *
+ * The two phases sum to the same integral as tracing every direction to full depth, but direct light
+ * converges with the full candidate count while the expensive multi-bounce work is spent where the
+ * first bounce found energy.
+ *
+ * @param {number[]|Float32Array|Float64Array} out 27 values: SH3 radiance, coefficient-major RGB triplets
+ * @param {number} out_offset
+ * @param {PathTracedScene} scene
+ * @param {PathTracer} tracer
+ * @param {function():number} random
+ * @param {number[]|Float32Array} position probe position
+ * @param {number} position_offset
+ * @param {number} candidate_count directions sampled one hit deep, at least 1
+ * @param {number} indirect_sample_count full path-traced continuations re-sampled from the candidates
+ * @param {number} max_bounce_count total path depth including the first hit, at least 1
+ * @returns {number} fraction of candidate directions whose first hit was a back face, in [0, 1]
+ */
+export function bake_probe_sh3_resampled(out: number[] | Float32Array | Float64Array, out_offset: number, scene: PathTracedScene, tracer: PathTracer, random: () => number, position: number[] | Float32Array, position_offset: number, candidate_count: number, indirect_sample_count: number, max_bounce_count: number): number;
+import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
+import { PathTracer } from "../path_tracer/PathTracer.js";
+//# sourceMappingURL=bake_probe_sh3_resampled.d.ts.map

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake_probe_sh3_resampled.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8CAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,eAAe,UACf,UAAU,gBACC,MAAM,YACjB,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,mBACN,MAAM,yBACN,MAAM,oBACN,MAAM,GACJ,MAAM,CAiMlB;gCAlS+B,mCAAmC;2BACjB,8BAA8B"}

package/src/engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js

@@ -0,0 +1,298 @@
+import { assert } from "../../../../core/assert.js";
+import { rgb_to_luminance } from "../../../../core/color/rgb_to_luminance.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sh3_basis_at } from "../../../../core/geom/3d/sphere/harmonics/sh3_basis_at.js";
+import { sh3_vector_accumulate } from "../../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
+import { random_point_on_sphere } from "../../../../core/geom/random/random_point_on_sphere.js";
+import { v3_dot } from "../../../../core/geom/vec3/v3_dot.js";
+import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
+import { PathTracer, SELF_OCCLUSION_OFFSET } from "../path_tracer/PathTracer.js";
+import { getBiasedNormalSample } from "../path_tracer/sampling/getBiasedNormalSample.js";
+
+/**
+ * Per-candidate record: direction(3), offset surface position(3), shading normal(3), albedo(3)
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 12;
+
+/**
+ * Fraction of the mean candidate luminance added to every re-sampling weight. Keeps surfaces that
+ * receive no direct light selectable — they may still return indirect radiance — so the estimator
+ * stays unbiased.
+ * @type {number}
+ */
+const RESAMPLING_WEIGHT_FLOOR = 0.1;
+
+const __ray = new Ray3();
+const __hit = [];
+const __surface = new Float32Array(9);
+const __direct = new Float32Array(3);
+const __radiance = new Float32Array(3);
+const __basis = new Float64Array(9);
+const __sh_direct = new Float64Array(27);
+const __sh_indirect = new Float64Array(27);
+
+let __candidates = new Float32Array(0);
+let __p_hat = new Float64Array(0);
+let __cumulative_p_hat = new Float64Array(0);
+
+/**
+ *
+ * @param {number} candidate_count
+ */
+function ensure_pool_capacity(candidate_count) {
+    if (__p_hat.length < candidate_count) {
+        __candidates = new Float32Array(candidate_count * CANDIDATE_STRIDE);
+        __p_hat = new Float64Array(candidate_count);
+        __cumulative_p_hat = new Float64Array(candidate_count);
+    }
+}
+
+/**
+ * Index of the candidate owning the cumulative-weight interval that contains `value`
+ * @param {number} value in [0, cumulative[count - 1])
+ * @param {number} count
+ * @returns {number}
+ */
+function pick_candidate(value, count) {
+    let low = 0;
+    let high = count - 1;
+
+    while (low < high) {
+        const mid = (low + high) >> 1;
+
+        if (__cumulative_p_hat[mid] > value) {
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+
+    return low;
+}
+
+/**
+ * Bake a single SH3 radiance probe with importance re-sampling and back-face visibility rejection.
+ *
+ * Two-phase estimator, split by path length:
+ *
+ * 1. Candidate phase: `candidate_count` uniform sphere directions are traced one hit deep. Misses
+ *    take the background radiance; front-face hits take `emissive + albedo * direct_light`, both of
+ *    which are cheap and low-noise, and every such sample is projected onto the SH. Directions whose
+ *    first hit is a back face see the inside of geometry — they are rejected and the estimate is
+ *    renormalized over the remaining directions, so interior darkness does not bleed into the probe.
+ *
+ * 2. Indirect phase: `indirect_sample_count` continuations are picked from the hit candidates with
+ *    probability proportional to their first-bounce luminance (resampled importance sampling — the
+ *    selection a weighted reservoir would produce, drawn from the materialized candidate table), and
+ *    only these few directions pay for a full multi-bounce path trace. The 1/p_hat re-sampling weight
+ *    keeps the combined estimator unbiased.
+ *
+ * The two phases sum to the same integral as tracing every direction to full depth, but direct light
+ * converges with the full candidate count while the expensive multi-bounce work is spent where the
+ * first bounce found energy.
+ *
+ * @param {number[]|Float32Array|Float64Array} out 27 values: SH3 radiance, coefficient-major RGB triplets
+ * @param {number} out_offset
+ * @param {PathTracedScene} scene
+ * @param {PathTracer} tracer
+ * @param {function():number} random
+ * @param {number[]|Float32Array} position probe position
+ * @param {number} position_offset
+ * @param {number} candidate_count directions sampled one hit deep, at least 1
+ * @param {number} indirect_sample_count full path-traced continuations re-sampled from the candidates
+ * @param {number} max_bounce_count total path depth including the first hit, at least 1
+ * @returns {number} fraction of candidate directions whose first hit was a back face, in [0, 1]
+ */
+export function bake_probe_sh3_resampled(
+    out, out_offset,
+    scene, tracer, random,
+    position, position_offset,
+    candidate_count, indirect_sample_count, max_bounce_count
+) {
+    assert.isArrayLike(out, 'out');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isInstanceOf(scene, PathTracedScene, 'scene');
+    assert.isInstanceOf(tracer, PathTracer, 'tracer');
+    assert.isFunction(random, 'random');
+    assert.isArrayLike(position, 'position');
+    assert.isNonNegativeInteger(position_offset, 'position_offset');
+    assert.isNonNegativeInteger(candidate_count, 'candidate_count');
+    assert.greaterThan(candidate_count, 0, 'candidate_count');
+    assert.isNonNegativeInteger(indirect_sample_count, 'indirect_sample_count');
+    assert.isNonNegativeInteger(max_bounce_count, 'max_bounce_count');
+    assert.greaterThan(max_bounce_count, 0, 'max_bounce_count');
+
+    ensure_pool_capacity(candidate_count);
+
+    __sh_direct.fill(0);
+    __sh_indirect.fill(0);
+
+    const position_x = position[position_offset];
+    const position_y = position[position_offset + 1];
+    const position_z = position[position_offset + 2];
+
+    let hit_count = 0;
+    let valid_count = 0;
+    let backface_count = 0;
+    let luminance_sum = 0;
+
+    for (let i = 0; i < candidate_count; i++) {
+
+        __ray[0] = position_x;
+        __ray[1] = position_y;
+        __ray[2] = position_z;
+
+        random_point_on_sphere(random, __ray, 3);
+
+        __ray.tMax = Infinity;
+
+        const direction_x = __ray[3];
+        const direction_y = __ray[4];
+        const direction_z = __ray[5];
+
+        const hit_distance = scene.trace(__hit, __ray);
+
+        if (hit_distance < 0) {
+            // sky
+            scene.sample_background(__radiance, 0, __ray, 3);
+        } else if (v3_dot(
+            __hit[3], __hit[4], __hit[5],
+            direction_x, direction_y, direction_z
+        ) > 0) {
+            // the first hit is a back face: this direction sees the inside of geometry
+            backface_count++;
+            continue;
+        } else {
+            scene.sample_material(__surface, __hit, __ray);
+
+            // stage the surface state in the ray: origin at the hit, direction holding the shading
+            // normal, then step off the surface along the normal — mirrors PathTracer exactly, so
+            // shadow rays and continuations start from the same offset point the tracer would use
+            __ray[0] = __hit[0];
+            __ray[1] = __hit[1];
+            __ray[2] = __hit[2];
+
+            __ray[3] = __surface[3];
+            __ray[4] = __surface[4];
+            __ray[5] = __surface[5];
+
+            const origin_magnitude = Math.max(Math.abs(__ray[0]), Math.abs(__ray[1]), Math.abs(__ray[2]));
+            __ray.shiftForward(SELF_OCCLUSION_OFFSET * Math.max(1, origin_magnitude));
+
+            scene.sample_lights(__direct, 0, __ray);
+
+            // first-bounce radiance: emission plus albedo-modulated direct light
+            __radiance[0] = __surface[6] + __surface[0] * __direct[0];
+            __radiance[1] = __surface[7] + __surface[1] * __direct[1];
+            __radiance[2] = __surface[8] + __surface[2] * __direct[2];
+
+            // record the candidate for indirect re-sampling
+            const candidate_address = hit_count * CANDIDATE_STRIDE;
+
+            __candidates[candidate_address] = direction_x;
+            __candidates[candidate_address + 1] = direction_y;
+            __candidates[candidate_address + 2] = direction_z;
+
+            __candidates[candidate_address + 3] = __ray[0];
+            __candidates[candidate_address + 4] = __ray[1];
+            __candidates[candidate_address + 5] = __ray[2];
+
+            __candidates[candidate_address + 6] = __surface[3];
+            __candidates[candidate_address + 7] = __surface[4];
+            __candidates[candidate_address + 8] = __surface[5];
+
+            __candidates[candidate_address + 9] = __surface[0];
+            __candidates[candidate_address + 10] = __surface[1];
+            __candidates[candidate_address + 11] = __surface[2];
+
+            const luminance = rgb_to_luminance(__radiance[0], __radiance[1], __radiance[2]);
+
+            __p_hat[hit_count] = luminance;
+            luminance_sum += luminance;
+
+            hit_count++;
+        }
+
+        valid_count++;
+
+        sh3_basis_at(direction_x, direction_y, direction_z, __basis);
+        sh3_vector_accumulate(__sh_direct, 0, __basis, 0, __radiance, 0, 3);
+    }
+
+    const backface_fraction = backface_count / candidate_count;
+
+    if (valid_count === 0) {
+        // probe is fully embedded in geometry, there is no usable radiance
+        for (let i = 0; i < 27; i++) {
+            out[out_offset + i] = 0;
+        }
+
+        return backface_fraction;
+    }
+
+    let total_p_hat = 0;
+
+    if (max_bounce_count > 1 && indirect_sample_count > 0 && hit_count > 0) {
+
+        // floor the weights so indirectly-lit surfaces stay selectable; when nothing received any
+        // direct light the selection degenerates to uniform (selection is scale-invariant in p_hat)
+        const mean_luminance = luminance_sum / hit_count;
+        const weight_floor = mean_luminance > 0 ? mean_luminance * RESAMPLING_WEIGHT_FLOOR : 1;
+
+        for (let i = 0; i < hit_count; i++) {
+            const p_hat = __p_hat[i] + weight_floor;
+
+            __p_hat[i] = p_hat;
+            total_p_hat += p_hat;
+
+            __cumulative_p_hat[i] = total_p_hat;
+        }
+
+        for (let k = 0; k < indirect_sample_count; k++) {
+            const pick = pick_candidate(random() * total_p_hat, hit_count);
+
+            const candidate_address = pick * CANDIDATE_STRIDE;
+
+            __ray[0] = __candidates[candidate_address + 3];
+            __ray[1] = __candidates[candidate_address + 4];
+            __ray[2] = __candidates[candidate_address + 5];
+
+            // cosine-weighted continuation about the shading normal, matching the tracer's own
+            // bounce sampling; the albedo/pi BRDF and the cosine/pi pdf cancel to a bare albedo scale
+            getBiasedNormalSample(__ray, 3, __candidates, candidate_address + 6, 1, random);
+
+            __ray.tMax = Infinity;
+
+            tracer.path_trace(__radiance, __ray, 1, max_bounce_count - 1, random, scene);
+
+            const resampling_weight = 1 / __p_hat[pick];
+
+            __radiance[0] *= __candidates[candidate_address + 9] * resampling_weight;
+            __radiance[1] *= __candidates[candidate_address + 10] * resampling_weight;
+            __radiance[2] *= __candidates[candidate_address + 11] * resampling_weight;
+
+            sh3_basis_at(
+                __candidates[candidate_address],
+                __candidates[candidate_address + 1],
+                __candidates[candidate_address + 2],
+                __basis
+            );
+            sh3_vector_accumulate(__sh_indirect, 0, __basis, 0, __radiance, 0, 3);
+        }
+    }
+
+    // back-face directions are excluded from the domain: normalizing by the valid count spreads the
+    // radiance of the visible directions over the full sphere, so partially embedded probes represent
+    // the open side instead of averaging in interior darkness
+    const direct_scale = (4 * Math.PI) / valid_count;
+    const indirect_scale = indirect_sample_count > 0
+        ? direct_scale * (total_p_hat / indirect_sample_count)
+        : 0;
+
+    for (let i = 0; i < 27; i++) {
+        out[out_offset + i] = __sh_direct[i] * direct_scale + __sh_indirect[i] * indirect_scale;
+    }
+
+    return backface_fraction;
+}

package/src/engine/graphics/sh3/lpg/light_probe_grid_dilate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fill invalid probes with the average of their valid 6-connected neighbors, expanding in waves until
+ * every reachable probe is filled.
+ *
+ * Probes marked invalid (typically because they sit inside geometry) would otherwise contribute their
+ * meaningless data to hardware trilinear filtering and bleed darkness across walls. Each pass reads
+ * only probes that were valid before the pass started, so the result is independent of traversal
+ * order. Probes with no valid probe anywhere in their connected region are left untouched.
+ *
+ * @param {Float32Array} harmonics probe data, {@link PROBE_VALUE_COUNT} values per probe; filled probes are written in place
+ * @param {Uint8Array} validity one flag per probe, non-zero = valid; filled probes are marked valid in place
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {number} number of probes that remained invalid
+ */
+export function light_probe_grid_dilate(harmonics: Float32Array, validity: Uint8Array, resolution_x: number, resolution_y: number, resolution_z: number): number;
+//# sourceMappingURL=light_probe_grid_dilate.d.ts.map

package/src/engine/graphics/sh3/lpg/light_probe_grid_dilate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light_probe_grid_dilate.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/light_probe_grid_dilate.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;GAeG;AACH,mDAPW,YAAY,YACZ,UAAU,gBACV,MAAM,gBACN,MAAM,gBACN,MAAM,GACJ,MAAM,CAsGlB"}

package/src/engine/graphics/sh3/lpg/light_probe_grid_dilate.js

@@ -0,0 +1,142 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Values per probe in {@link LightProbeGrid#harmonics}
+ * @type {number}
+ */
+const PROBE_VALUE_COUNT = 12;
+
+const __accumulator = new Float64Array(PROBE_VALUE_COUNT);
+
+let __source_validity = new Uint8Array(0);
+
+/**
+ * Fill invalid probes with the average of their valid 6-connected neighbors, expanding in waves until
+ * every reachable probe is filled.
+ *
+ * Probes marked invalid (typically because they sit inside geometry) would otherwise contribute their
+ * meaningless data to hardware trilinear filtering and bleed darkness across walls. Each pass reads
+ * only probes that were valid before the pass started, so the result is independent of traversal
+ * order. Probes with no valid probe anywhere in their connected region are left untouched.
+ *
+ * @param {Float32Array} harmonics probe data, {@link PROBE_VALUE_COUNT} values per probe; filled probes are written in place
+ * @param {Uint8Array} validity one flag per probe, non-zero = valid; filled probes are marked valid in place
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {number} number of probes that remained invalid
+ */
+export function light_probe_grid_dilate(
+    harmonics,
+    validity,
+    resolution_x, resolution_y, resolution_z
+) {
+    assert.isNonNegativeInteger(resolution_x, 'resolution_x');
+    assert.isNonNegativeInteger(resolution_y, 'resolution_y');
+    assert.isNonNegativeInteger(resolution_z, 'resolution_z');
+
+    const probe_count = resolution_x * resolution_y * resolution_z;
+
+    assert.greaterThanOrEqual(validity.length, probe_count, 'validity.length');
+    assert.greaterThanOrEqual(harmonics.length, probe_count * PROBE_VALUE_COUNT, 'harmonics.length');
+
+    if (__source_validity.length < probe_count) {
+        __source_validity = new Uint8Array(probe_count);
+    }
+
+    let invalid_count = 0;
+
+    for (let i = 0; i < probe_count; i++) {
+        if (validity[i] === 0) {
+            invalid_count++;
+        }
+    }
+
+    const slice_size = resolution_x * resolution_y;
+
+    let filled_this_pass = 1;
+
+    while (invalid_count > 0 && filled_this_pass > 0) {
+        filled_this_pass = 0;
+
+        // snapshot so each pass only reads probes that were valid before it started
+        __source_validity.set(validity.subarray(0, probe_count));
+
+        for (let z = 0; z < resolution_z; z++) {
+            for (let y = 0; y < resolution_y; y++) {
+                for (let x = 0; x < resolution_x; x++) {
+
+                    const index = x + resolution_x * y + slice_size * z;
+
+                    if (__source_validity[index] !== 0) {
+                        continue;
+                    }
+
+                    __accumulator.fill(0);
+                    let neighbor_count = 0;
+
+                    if (x > 0 && __source_validity[index - 1] !== 0) {
+                        accumulate_probe(harmonics, index - 1);
+                        neighbor_count++;
+                    }
+
+                    if (x < resolution_x - 1 && __source_validity[index + 1] !== 0) {
+                        accumulate_probe(harmonics, index + 1);
+                        neighbor_count++;
+                    }
+
+                    if (y > 0 && __source_validity[index - resolution_x] !== 0) {
+                        accumulate_probe(harmonics, index - resolution_x);
+                        neighbor_count++;
+                    }
+
+                    if (y < resolution_y - 1 && __source_validity[index + resolution_x] !== 0) {
+                        accumulate_probe(harmonics, index + resolution_x);
+                        neighbor_count++;
+                    }
+
+                    if (z > 0 && __source_validity[index - slice_size] !== 0) {
+                        accumulate_probe(harmonics, index - slice_size);
+                        neighbor_count++;
+                    }
+
+                    if (z < resolution_z - 1 && __source_validity[index + slice_size] !== 0) {
+                        accumulate_probe(harmonics, index + slice_size);
+                        neighbor_count++;
+                    }
+
+                    if (neighbor_count === 0) {
+                        continue;
+                    }
+
+                    const probe_address = index * PROBE_VALUE_COUNT;
+                    const inverse_count = 1 / neighbor_count;
+
+                    for (let i = 0; i < PROBE_VALUE_COUNT; i++) {
+                        harmonics[probe_address + i] = __accumulator[i] * inverse_count;
+                    }
+
+                    validity[index] = 1;
+                    filled_this_pass++;
+                }
+            }
+        }
+
+        invalid_count -= filled_this_pass;
+    }
+
+    return invalid_count;
+}
+
+/**
+ *
+ * @param {Float32Array} harmonics
+ * @param {number} probe_index
+ */
+function accumulate_probe(harmonics, probe_index) {
+    const address = probe_index * PROBE_VALUE_COUNT;
+
+    for (let i = 0; i < PROBE_VALUE_COUNT; i++) {
+        __accumulator[i] += harmonics[address + i];
+    }
+}

package/src/engine/graphics/sh3/path_tracer/PathTracer.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Base self-occlusion offset; scaled by coordinate magnitude so it stays above the Float32 ULP
+ * at large world scales
+ * @type {number}
+ */
+export const SELF_OCCLUSION_OFFSET: number;
 export class PathTracer {
     /**
      *

package/src/engine/graphics/sh3/path_tracer/PathTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracer.js"],"names":[],"mappings":"AA+CA;IAGI;;;;;;;;OAQG;IACH,gBAPW,MAAM,EAAE,GAAC,YAAY,OACrB,MAAM,EAAE,GAAC,YAAY,GAAC,IAAI,cAC1B,MAAM,cACN,MAAM,kDAuFhB;CACJ;qBA7IoB,sCAAsC"}
+{"version":3,"file":"PathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracer.js"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,oCAFU,MAAM,CAE6B;AAI7C;IAGI;;;;;;;;OAQG;IACH,gBAPW,MAAM,EAAE,GAAC,YAAY,OACrB,MAAM,EAAE,GAAC,YAAY,GAAC,IAAI,cAC1B,MAAM,cACN,MAAM,kDAuFhB;CACJ;qBA7IoB,sCAAsC"}

package/src/engine/graphics/sh3/path_tracer/PathTracer.js

@@ -41,7 +41,7 @@ const RUSSIAN_ROULETTE_SURVIVAL_RECIPROCAL = 1 / (1 - RUSSIAN_ROULETTE_PROBABILI
  * at large world scales
  * @type {number}
  */
-const SELF_OCCLUSION_OFFSET = 0.00001;
+export const SELF_OCCLUSION_OFFSET = 0.00001;
 
 const color_mask = new Float32Array(3);
 

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

@@ -1,14 +1,16 @@
 /**
  * Fixed-function simulation for {@link TubeX} tubes — the 3D analogue of
- * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, fades its alpha to zero
- * as it approaches `max_age`, and flows the along-tube UV coordinate with age.
+ * {@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.
  */
 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
      */
-    update(tube: TubeX, max_age: number, timeDelta: number): void;
+    update(tube: TubeX, max_age: number, timeDelta: number, alpha?: number): 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;;;;GAIG;AACH;IAEI;;;;OAIG;IACH,6BAHW,MAAM,aACN,MAAM,QAiBhB;CACJ"}
+{"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"}

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

@@ -3,8 +3,9 @@ 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 to zero
- * as it approaches `max_age`, and flows the along-tube UV coordinate with age.
+ * {@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.
  */
 export class TubeXFixedPhysicsSimulator {
 
@@ -12,8 +13,9 @@ 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
      */
-    update(tube, max_age, timeDelta) {
+    update(tube, max_age, timeDelta, alpha = 1) {
 
         const n = tube.getCount();
 
@@ -23,7 +25,7 @@ export class TubeXFixedPhysicsSimulator {
             const relative_age = clamp01(age / max_age);
 
             // fade out with age
-            tube.setKnotAlpha(i, 1.0 - relative_age);
+            tube.setKnotAlpha(i, (1.0 - relative_age) * alpha);
 
             // flow the along-tube UV with age
             tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, relative_age);

package/src/engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.d.ts

@@ -7,7 +7,8 @@ export class RibbonXFixedPhysicsSimulator {
      * @param {RibbonX} ribbon
      * @param {number} max_age
      * @param {number} timeDelta
+     * @param {number} [alpha] base alpha of an age-0 point; the age fade scales it
      */
-    update(ribbon: RibbonX, max_age: number, timeDelta: number): void;
+    update(ribbon: RibbonX, max_age: number, timeDelta: number, alpha?: number): void;
 }
 //# sourceMappingURL=RibbonXFixedPhysicsSimulator.d.ts.map

package/src/engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RibbonXFixedPhysicsSimulator.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAEI;;;;;OAKG;IACH,iCAHW,MAAM,aACN,MAAM,QAkBhB;CACJ"}
+{"version":3,"file":"RibbonXFixedPhysicsSimulator.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAEI;;;;;;OAMG;IACH,iCAJW,MAAM,aACN,MAAM,UACN,MAAM,QAkBhB;CACJ"}

package/src/engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.js

@@ -12,8 +12,9 @@ export class RibbonXFixedPhysicsSimulator {
      * @param {RibbonX} ribbon
      * @param {number} max_age
      * @param {number} timeDelta
+     * @param {number} [alpha] base alpha of an age-0 point; the age fade scales it
      */
-    update(ribbon, max_age, timeDelta) {
+    update(ribbon, max_age, timeDelta, alpha = 1) {
 
         const n = ribbon.getCount();
         for (let i = 0; i < n; i++) {
@@ -23,7 +24,7 @@ export class RibbonXFixedPhysicsSimulator {
             const relative_age = clamp01(age / max_age);
 
             // apply alpha over-time
-            ribbon.setPointAlpha(i, 1.0 - relative_age);
+            ribbon.setPointAlpha(i, (1.0 - relative_age) * alpha);
 
             ribbon.setPointAttribute_Scalar(i, RIBBON_ATTRIBUTE_ADDRESS_UV_OFFSET, relative_age);
         }