@woosh/meep-engine 2.165.4 → 2.165.6

package/src/engine/graphics/ecs/light/LightContext.d.ts

@@ -16,6 +16,14 @@ export class LightContext extends SystemEntityContext {
      */
     getTransform(): Transform;
     __rebuild(): void;
+    /**
+     * Forward+ point lights have no shadow support; a shadow-casting point
+     * light falls through to a real three.js light instead
+     * @return {boolean}
+     * @private
+     */
+    private __use_fp_binding;
+    __handleCastShadowChanged(): void;
     __build(): void;
     applySettings(): void;
 }

package/src/engine/graphics/ecs/light/LightContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightContext.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/LightContext.js"],"names":[],"mappings":"AAKA;IAEI;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,kBAEC;IAED;;;OAGG;IACH,0BAEC;IAED,kBAIC;IAED,gBASC;IAED,sBAEC;CAgBJ;oCAjEmC,4CAA4C"}
+{"version":3,"file":"LightContext.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/LightContext.js"],"names":[],"mappings":"AAKA;IAEI;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,kBAEC;IAED;;;OAGG;IACH,0BAEC;IAED,kBAIC;IAED;;;;;OAKG;IACH,yBAMC;IAED,kCAQC;IAED,gBASC;IAED,sBAEC;CAsBJ;oCA/FmC,4CAA4C"}

package/src/engine/graphics/ecs/light/LightContext.js

@@ -34,8 +34,32 @@ export class LightContext extends SystemEntityContext {
         this.__binding.link(this);
     }
 
+    /**
+     * Forward+ point lights have no shadow support; a shadow-casting point
+     * light falls through to a real three.js light instead
+     * @return {boolean}
+     * @private
+     */
+    __use_fp_binding() {
+        const light = this.getLight();
+
+        return light.type.getValue() === LightType.POINT
+            && this.system.__use_forward_plus
+            && !light.castShadow.getValue();
+    }
+
+    __handleCastShadowChanged() {
+        if ((this.__binding instanceof FPLightBinding) === this.__use_fp_binding()) {
+            // routing is unchanged; a three.js-bound light reacts to castShadow
+            // through its own binding, no rebuild needed
+            return;
+        }
+
+        this.__rebuild();
+    }
+
     __build() {
-        if (this.getLight().type.getValue() === LightType.POINT && this.system.__use_forward_plus) {
+        if (this.__use_fp_binding()) {
             this.__binding = new FPLightBinding();
         } else {
             this.__binding = new ThreeLightBinding();
@@ -53,12 +77,18 @@ export class LightContext extends SystemEntityContext {
         this.__build();
         this.__binding.link(this);
 
-        this.getLight().type.onChanged.add(this.__rebuild, this);
+        const light = this.getLight();
+
+        light.type.onChanged.add(this.__rebuild, this);
+        light.castShadow.onChanged.add(this.__handleCastShadowChanged, this);
     }
 
     unlink() {
 
-        this.getLight().type.onChanged.remove(this.__rebuild, this);
+        const light = this.getLight();
+
+        light.type.onChanged.remove(this.__rebuild, this);
+        light.castShadow.onChanged.remove(this.__handleCastShadowChanged, this);
 
         this.__binding.unlink(this);
 

package/src/engine/graphics/ecs/light/LightSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/LightSystem.js"],"names":[],"mappings":"AA6QA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,2DARW,YAAY,SACZ,WAAW,oBACX,MAAM,qCA6EhB;;uBA7WsB,qBAAqB;sBAEtB,YAAY;AASlC;IACI;;;;;OAKG;IACH,2CAsFC;IA1EG,kDAAsC;IAGtC,6DAEC;IAGD,eAAoB;IACpB,WAA2B;IAC3B,aAAwB;IAExB;;;;OAIG;IACH,mBAA0B;IAE1B;;;;OAIG;IACH,wBAA2B;IAE3B,gBAAkB;IAElB;;;;OAIG;IACH,kBAAoC;IAGpC;;;;OAIG;IACH,2BAA8B;IAC9B;;;;OAIG;IACH,iBAAoB;IAGpB;;;;OAIG;IACH,4BAAgD;IAqBpD,mCAEC;IAED;;;;OAIG;IACH,uBAHW,MAAM,SACN,MAAM,GAAC,MAAM,GAAC,OAAO,QAkB/B;IAED;;;;OAIG;IACH,4BAHW,KAAK,UACL,MAAM,QAMhB;IAED,2CAOC;IAED,4CASC;IAGD,4CAOC;IAED;;;;;OAKG;IACH,wCAwCC;IAED;;;;;;OAMG;IACH,sCAwBC;CACJ;sCAjQqC,8CAA8C;0BAC1D,qCAAqC;4CAFnB,uDAAuD"}
+{"version":3,"file":"LightSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/LightSystem.js"],"names":[],"mappings":"AAoRA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,2DARW,YAAY,SACZ,WAAW,oBACX,MAAM,qCA6EhB;;uBApXsB,qBAAqB;sBAEtB,YAAY;AASlC;IACI;;;;;OAKG;IACH,2CAsFC;IA1EG,kDAAsC;IAGtC,6DAEC;IAGD,eAAoB;IACpB,WAA2B;IAC3B,aAAwB;IAExB;;;;OAIG;IACH,mBAA0B;IAE1B;;;;OAIG;IACH,wBAA2B;IAE3B,gBAAkB;IAElB;;;;OAIG;IACH,kBAAoC;IAGpC;;;;OAIG;IACH,2BAA8B;IAC9B;;;;OAIG;IACH,iBAAoB;IAGpB;;;;OAIG;IACH,4BAAgD;IAqBpD,mCAEC;IAED;;;;OAIG;IACH,uBAHW,MAAM,SACN,MAAM,GAAC,MAAM,GAAC,OAAO,QAkB/B;IAED;;;;OAIG;IACH,4BAHW,KAAK,UACL,MAAM,QAMhB;IAED,2CAOC;IAED,4CASC;IAGD,4CAOC;IAED;;;;;OAKG;IACH,wCA+CC;IAED;;;;;;OAMG;IACH,sCAwBC;CACJ;sCAxQqC,8CAA8C;0BAC1D,qCAAqC;4CAFnB,uDAAuD"}

package/src/engine/graphics/ecs/light/LightSystem.js

@@ -213,12 +213,19 @@ class LightSystem extends AbstractContextSystem {
 
                 l.castShadow = true;
 
-                three_update_shadow_camera_extents(
-                    this.__camera_object,
-                    l,
-                    light.maxShadowDistance.getValue(),
-                    this.__graphics.layers
-                );
+                if (light.type.getValue() === LightType.DIRECTION) {
+                    // the orthographic view-frustum fit only makes sense for
+                    // directional lights; applying it to the perspective
+                    // shadow camera of a point/spot light corrupts its
+                    // projection (those cameras are driven by
+                    // LightShadow.updateMatrices instead)
+                    three_update_shadow_camera_extents(
+                        this.__camera_object,
+                        l,
+                        light.maxShadowDistance.getValue(),
+                        this.__graphics.layers
+                    );
+                }
 
             } else {
 

package/src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.d.ts

@@ -35,6 +35,18 @@ export class ThreeLightBinding extends LightBinding {
     __shadowmap_link(): void;
     __shadowmap_unlink(): void;
     __shadowmap_prepare_view(): void;
+    /**
+     * A point light shadow renders six cube faces, a single camera frustum
+     * would only cull correctly for one of them. Instead, cull by the
+     * axis-aligned box bounding the light's sphere of influence: every caster
+     * that can shadow any face lies within `distance` of the light. The box is
+     * written directly as six inward-facing "frustum" planes and the resulting
+     * visible set is shared by all six face renders.
+     * @param {CameraView} cameraView
+     * @param {THREE.PointLight} light
+     * @private
+     */
+    private __shadowmap_prepare_view_point;
     __shadowmap_render(): void;
     applySettings(settings: any): void;
 }

package/src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThreeLightBinding.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.js"],"names":[],"mappings":"AA6FA;;;;GAIG;AACH,6EAFW,MAAM,QAgBhB;AAED;IAGI;;;;OAIG;IACH,iBAAgB;IAEhB;;;;OAIG;IACH,qBAAoB;IAEpB;;;;OAIG;IACH,qBAA6B;IAG7B,qBAYC;IAED,uBAcC;IAED;;;;OAIG;IACH,yBAEC;IAYD,+BAEC;IAUD,yBAuBC;IAED,2BAgBC;IAED,iCA0BC;IAGD,2BA0CC;IA8CD,mCAmBC;CAEJ;6BAtX4B,oBAAoB"}
+{"version":3,"file":"ThreeLightBinding.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.js"],"names":[],"mappings":"AA2JA;;;;GAIG;AACH,6EAFW,MAAM,QAqBhB;AAED;IAGI;;;;OAIG;IACH,iBAAgB;IAEhB;;;;OAIG;IACH,qBAAoB;IAEpB;;;;OAIG;IACH,qBAA6B;IAG7B,qBAYC;IAED,uBAeC;IAED;;;;OAIG;IACH,yBAEC;IAYD,+BAEC;IAUD,yBAuBC;IAED,2BAmCC;IAED,iCA+BC;IAED;;;;;;;;;;OAUG;IACH,uCA8CC;IAGD,2BAkDC;IA8CD,mCAsCC;CAEJ;6BAxiB4B,oBAAoB"}

package/src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.js

@@ -1,4 +1,4 @@
-import { DoubleSide, Mesh, MeshDepthMaterial, RGBADepthPacking, Scene } from "three";
+import { DoubleSide, Mesh, MeshDepthMaterial, MeshDistanceMaterial, RGBADepthPacking, Scene, Vector3 } from "three";
 import { ThreeBypassRenderer } from "../../../../render/utils/ThreeBypassRenderer.js";
 import { CameraView } from "../../../../render/view/CameraView.js";
 import { three_setSceneAutoUpdate } from "../../../../three/three_setSceneAutoUpdate.js";
@@ -59,6 +59,68 @@ function __getDepthMaterial(object) {
     return result;
 }
 
+const __distance_material = new MeshDistanceMaterial({
+    side: DoubleSide
+});
+
+/**
+ * Reference values for point light shadow casting, set per render in
+ * {@link ThreeLightBinding.__shadowmap_render} before the shadow scene is
+ * built. Shadow renders are sequential, so shared state is safe here.
+ */
+const __distance_params = {
+    reference_position: new Vector3(),
+    near_distance: 0,
+    far_distance: 0
+};
+
+/**
+ * Point light shadows compare world-space distance to the light rather than
+ * projected depth (three.js getPointShadow), which requires
+ * MeshDistanceMaterial instead of MeshDepthMaterial
+ * @param {Mesh} object
+ * @returns {Material}
+ * @private
+ */
+function __getDistanceMaterial(object) {
+    let result;
+
+    const customDistanceMaterial = object.customDistanceMaterial;
+
+    if (customDistanceMaterial !== undefined) {
+        result = customDistanceMaterial;
+    } else {
+
+        const source_material = object.material;
+        if (
+            typeof source_material.alphaTest === "number"
+            && source_material.alphaTest > 0
+            && source_material.alphaTest < 1
+            && source_material.map !== null
+            && source_material.map !== undefined
+        ) {
+            // alpha-tested
+            result = new MeshDistanceMaterial({
+                side: DoubleSide,
+                map: source_material.map,
+                alphaTest: source_material.alphaTest
+            });
+
+        } else {
+            // generic
+            result = __distance_material;
+        }
+    }
+
+    if (result.isMeshDistanceMaterial === true) {
+        result.referencePosition.copy(__distance_params.reference_position);
+        result.nearDistance = __distance_params.near_distance;
+        result.farDistance = __distance_params.far_distance;
+    }
+
+    return result;
+}
+
 /**
  *
  * @param {THREE.Object3D} object3D
@@ -109,6 +171,11 @@ export function three_set_shadow_resolution(shadow, resolution) {
             shadow.map = null;
         }
 
+        if (shadow.mapPass !== null) {
+            shadow.mapPass.dispose();
+            shadow.mapPass = null;
+        }
+
     }
 }
 
@@ -157,13 +224,14 @@ export class ThreeLightBinding extends LightBinding {
          */
         const cache = this.__system.__three_light_cache;
 
+        // tear down shadow state while the light is still bound
+        this.__shadowmap_unlink();
+
         cache.release(this.__three_getLight());
 
         // clear bound light
         this.__c_light.__threeObject = null;
 
-        this.__shadowmap_unlink();
-
         super.unlink(ctx);
     }
 
@@ -239,6 +307,25 @@ export class ThreeLightBinding extends LightBinding {
         shadows.remove(this.__shadow_map);
 
         this.__shadow_map = null;
+
+        // release GPU resources of the shadow render targets, they are
+        // re-created on demand if shadow casting is enabled again
+        const light = this.__three_getLight();
+
+        const shadow = light === null ? undefined : light.shadow;
+
+        if (shadow !== undefined) {
+
+            if (shadow.map !== null) {
+                shadow.map.dispose();
+                shadow.map = null;
+            }
+
+            if (shadow.mapPass !== null) {
+                shadow.mapPass.dispose();
+                shadow.mapPass = null;
+            }
+        }
     }
 
     __shadowmap_prepare_view() {
@@ -250,6 +337,11 @@ export class ThreeLightBinding extends LightBinding {
          */
         const light = this.__three_getLight();
 
+        if (light.isPointLight === true) {
+            this.__shadowmap_prepare_view_point(cameraView, light);
+            return;
+        }
+
         /**
          *
          * @type {LightShadow}
@@ -269,6 +361,65 @@ export class ThreeLightBinding extends LightBinding {
 
     }
 
+    /**
+     * A point light shadow renders six cube faces, a single camera frustum
+     * would only cull correctly for one of them. Instead, cull by the
+     * axis-aligned box bounding the light's sphere of influence: every caster
+     * that can shadow any face lies within `distance` of the light. The box is
+     * written directly as six inward-facing "frustum" planes and the resulting
+     * visible set is shared by all six face renders.
+     * @param {CameraView} cameraView
+     * @param {THREE.PointLight} light
+     * @private
+     */
+    __shadowmap_prepare_view_point(cameraView, light) {
+        const p = this.__c_transform.position;
+
+        // mirrors PointLightShadow.updateMatrices: distance of 0 means unbounded
+        const r = light.distance || light.shadow.camera.far;
+
+        const f = cameraView.frustum;
+
+        // plane format: nx, ny, nz, constant; a point is inside a plane when
+        // dot(normal, point) + constant >= 0
+
+        // x >= p.x - r
+        f[0] = 1;
+        f[1] = 0;
+        f[2] = 0;
+        f[3] = r - p.x;
+
+        // x <= p.x + r
+        f[4] = -1;
+        f[5] = 0;
+        f[6] = 0;
+        f[7] = r + p.x;
+
+        // y >= p.y - r
+        f[8] = 0;
+        f[9] = 1;
+        f[10] = 0;
+        f[11] = r - p.y;
+
+        // y <= p.y + r
+        f[12] = 0;
+        f[13] = -1;
+        f[14] = 0;
+        f[15] = r + p.y;
+
+        // z >= p.z - r
+        f[16] = 0;
+        f[17] = 0;
+        f[18] = 1;
+        f[19] = r - p.z;
+
+        // z <= p.z + r
+        f[20] = 0;
+        f[21] = 0;
+        f[22] = -1;
+        f[23] = r + p.z;
+    }
+
 
     __shadowmap_render() {
 
@@ -297,6 +448,14 @@ export class ThreeLightBinding extends LightBinding {
 
         const shadow = threeLight.shadow;
 
+        const is_point_light = threeLight.isPointLight === true;
+
+        if (is_point_light) {
+            __distance_params.reference_position.setFromMatrixPosition(threeLight.matrixWorld);
+            __distance_params.near_distance = shadow.camera.near;
+            // mirrors PointLightShadow.updateMatrices
+            __distance_params.far_distance = threeLight.distance || shadow.camera.far;
+        }
 
         // prepare shadow scene
         const visible_objects = cameraView.visible_objects;
@@ -306,7 +465,7 @@ export class ThreeLightBinding extends LightBinding {
             scene: shadow_scene,
             input: visible_objects.elements,
             input_size: visible_object_count,
-            material_extractor: __getDepthMaterial,
+            material_extractor: is_point_light ? __getDistanceMaterial : __getDepthMaterial,
             object_filter: scene_object_filter
         })
 
@@ -367,9 +526,28 @@ export class ThreeLightBinding extends LightBinding {
 
             // disable automatic shadowmap rendering in three.js
             shadow.autoUpdate = false;
-            shadow.camera.matrixAutoUpdate = false;
 
-            const resolution = parseInt(settings.shadowResolution);
+            let resolution = parseInt(settings.shadowResolution);
+
+            if (shadow.isPointLightShadow === true) {
+                // PointLightShadow.updateMatrices re-orients the camera for
+                // every cube face and relies on updateMatrixWorld() to
+                // re-compose the matrix, so matrixAutoUpdate must stay enabled
+                shadow.camera.matrixAutoUpdate = true;
+
+                // small offset in normalized [near..far] distance units to
+                // suppress acne, casters render double-sided so front faces
+                // would otherwise compare against their own stored distance
+                shadow.bias = -0.002;
+
+                // resolution is per cube face and the shadow map allocates a
+                // 4x2 face atlas, cap the default to keep memory use sane
+                resolution = settings.shadowResolutionPoint !== undefined
+                    ? parseInt(settings.shadowResolutionPoint)
+                    : Math.min(resolution, 1024);
+            } else {
+                shadow.camera.matrixAutoUpdate = false;
+            }
 
             shadow.radius = 1;
             shadow.blurSamples = 8;

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

@@ -96,6 +96,27 @@ declare class Trail3D {
     get textureURL(): string;
     set depthWrite(arg: boolean);
     get depthWrite(): boolean;
+    /**
+     * @param {boolean} v
+     */
+    set lightingEnabled(arg: boolean);
+    /**
+     * Whether the trail's tube processes standard scene lighting. When enabled the
+     * tube shades as a matte (Lambert) surface under the scene's ambient /
+     * hemisphere / light-probe / directional / point / spot lights and receives
+     * shadows; it never casts them. Under the Forward+ pipeline the material is
+     * additionally rewritten by the renderer's material manager, so clustered
+     * point lights and decals apply as well. When disabled (default) the tube
+     * renders unlit.
+     *
+     * Stored in {@link Trail3DFlags.Lit}. This is a build-time option — it selects
+     * the compiled material and the mesh's shadow settings — so it must be set
+     * before the trail is built / registered with the system, and cannot change
+     * afterwards.
+     *
+     * @returns {boolean}
+     */
+    get lightingEnabled(): boolean;
     /**
      * @param {number|Trail3DFlags} flag
      * @returns {void}
@@ -124,7 +145,7 @@ declare class Trail3D {
      * Clear the trail's geometry and reset its state.
      */
     clear(): void;
-    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, offset, color }: {
+    fromJSON({ maxAge, width, radialSegments, spawnMode, spawnDistance, textureURL, depthWrite, lightingEnabled, offset, color }: {
         maxAge?: number;
         width?: number;
         radialSegments?: number;
@@ -132,6 +153,7 @@ declare class Trail3D {
         spawnDistance?: number;
         textureURL: any;
         depthWrite?: boolean;
+        lightingEnabled?: boolean;
         offset?: Vector3;
         color?: {
             r: number;
@@ -154,6 +176,7 @@ declare class Trail3D {
         };
         textureURL: string;
         depthWrite: boolean;
+        lightingEnabled: boolean;
         offset: {
             x: number;
             y: number;

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;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"}
+{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAiCA;;;;;GAKG;AACH;IAoPI,oCAMC;IAxPD;;;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;IA0BD;;OAEG;IACH,kCAQC;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;;OAEG;IACH,qBAFW,MAAM,QAoBhB;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;;;;;+BA3c8B,+BAA+B;sBAPxC,iCAAiC;oBACnC,kCAAkC;sBAShC,2BAA2B;kCACf,uCAAuC;0BAZ/C,yCAAyC;6BAatC,mBAAmB"}

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../../core/assert.js";
 import { FLOAT32_MAX } from "../../../../core/binary/FLOAT32_MAX.js";
 import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
 import { Color } from "../../../../core/color/Color.js";
@@ -164,6 +165,39 @@ class Trail3D {
         this.material.depthWrite = v;
     }
 
+    /**
+     * Whether the trail's tube processes standard scene lighting. When enabled the
+     * tube shades as a matte (Lambert) surface under the scene's ambient /
+     * hemisphere / light-probe / directional / point / spot lights and receives
+     * shadows; it never casts them. Under the Forward+ pipeline the material is
+     * additionally rewritten by the renderer's material manager, so clustered
+     * point lights and decals apply as well. When disabled (default) the tube
+     * renders unlit.
+     *
+     * Stored in {@link Trail3DFlags.Lit}. This is a build-time option — it selects
+     * the compiled material and the mesh's shadow settings — so it must be set
+     * before the trail is built / registered with the system, and cannot change
+     * afterwards.
+     *
+     * @returns {boolean}
+     */
+    get lightingEnabled() {
+        return this.getFlag(Trail3DFlags.Lit);
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set lightingEnabled(v) {
+        if (v === this.lightingEnabled) {
+            return;
+        }
+
+        assert.notOk(this.getFlag(Trail3DFlags.Built), "lightingEnabled cannot change after the trail is built");
+
+        this.writeFlag(Trail3DFlags.Lit, v);
+    }
+
     /**
      * @param {number|Trail3DFlags} flag
      * @returns {void}
@@ -214,6 +248,11 @@ class Trail3D {
 
         const mesh = ThreeFactory.createMesh(geometry, null);
 
+        // receive-only lighting: castShadow stays false. The geometry's `position`
+        // attribute holds ring CENTRES (the surface is extruded in the material's
+        // vertex stage), so a stock depth pass would render a degenerate line anyway.
+        mesh.receiveShadow = this.getFlag(Trail3DFlags.Lit);
+
         this.tube = tube;
         this.mesh = mesh;
     }
@@ -258,6 +297,7 @@ class Trail3D {
                  spawnDistance = DEFAULT_SPAWN_DISTANCE,
                  textureURL,
                  depthWrite = false,
+                 lightingEnabled = false,
                  offset = Vector3.zero,
                  color = { r: 1, g: 1, b: 1, a: 1 }
              }) {
@@ -269,6 +309,7 @@ class Trail3D {
         this.spawnDistance = spawnDistance;
         this.textureURL = textureURL;
         this.depthWrite = depthWrite;
+        this.lightingEnabled = lightingEnabled;
 
         this.offset.fromJSON(offset);
         this.color.fromJSON(color);
@@ -284,6 +325,7 @@ class Trail3D {
             color: this.color.toJSON(),
             textureURL: this.textureURL,
             depthWrite: this.depthWrite,
+            lightingEnabled: this.lightingEnabled,
             offset: this.offset.toJSON()
         };
     }
@@ -294,6 +336,7 @@ class Trail3D {
     equals(other) {
         return this.textureURL === other.textureURL
             && this.depthWrite === other.depthWrite
+            && this.lightingEnabled === other.lightingEnabled
             && this.width === other.width
             && this.radialSegments === other.radialSegments
             && this.maxAge === other.maxAge

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

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

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

@@ -14,5 +14,13 @@ export const Trail3DFlags = {
      * segment can bridge post-clear geometry to pre-clear history (e.g. a long
      * streak after teleporting the entity).
      */
-    Reseed: 16
+    Reseed: 16,
+
+    /**
+     * The tube processes standard scene lighting (receive-only — it never casts
+     * shadows). Build-time flag: it selects the compiled material and the mesh's
+     * shadow settings, so it must be set before the trail is built / registered
+     * with the system; changing it afterwards has no effect.
+     */
+    Lit: 32
 };

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;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"}
+{"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,QAgBhB;IAED;;;;OAIG;IACH,kBAJW,OAAO,aACP,SAAS,UACT,MAAM,QAQhB;IAED;;;OAGG;IACH,yBAHW,OAAO,aACP,SAAS,QAkCnB;IAED,6BAWC;;CACJ;uBAlPsB,wBAAwB;0BACrB,qCAAqC;oBAW3C,cAAc;4CAbU,uDAAuD;2CAUxD,0DAA0D;+BANtE,yBAAyB"}

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

@@ -170,6 +170,10 @@ class Trail3DSystem extends System {
      * @param {number} entityId
      */
     link(trail, transform, entityId) {
+        // Trail3DFlags.Lit is final by link time — bake it into the material spec
+        // (the material cache key) so lit and unlit trails obtain distinct materials
+        trail.material.lit = trail.getFlag(Trail3DFlags.Lit);
+
         if (!trail.getFlag(Trail3DFlags.Built)) {
             this.#build_trail(trail, transform);
         } else {

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

@@ -6,6 +6,8 @@ import { EngineHarness } from "../../../EngineHarness.js";
 import { BehaviorComponent } from "../../../intelligence/behavior/ecs/BehaviorComponent.js";
 import { BehaviorSystem } from "../../../intelligence/behavior/ecs/BehaviorSystem.js";
 import { OrbitingBehavior } from "../../../intelligence/behavior/ecs/OrbitingBehavior.js";
+import { Light } from "../light/Light.js";
+import { LightType } from "../light/LightType.js";
 import { TrailSpawnMode } from "../../trail/TrailSpawnMode.js";
 import Trail3D from "./Trail3D.js";
 import Trail3DSystem from "./Trail3DSystem.js";
@@ -44,6 +46,9 @@ async function main(engine) {
             // exercise the distance-based spawning path too
             spawnMode: TrailSpawnMode.Distance,
             spawnDistance: 0.15,
+            // alternate unlit / lit around the ring: lit tubes shade under the
+            // harness sun + ambient fill and receive (never cast) shadows
+            lightingEnabled: i % 2 === 1,
             color: { r: 1, g: 1, b: 1, a: 1 }
         }));
 
@@ -59,7 +64,23 @@ async function main(engine) {
         entity.build(ecd);
     }
 
-    console.log("Trail3D prototype: spawned", emitter_count, "orbiting tube emitters");
+    // a strong green point light in the middle of the ring. Non-shadow-casting
+    // POINT lights route through the Forward+ clustered path, so it only shows
+    // on materials that went through the FP material transformer — including
+    // the lit tubes.
+    new Entity()
+        .add(Light.fromJSON({
+            type: LightType.POINT,
+            color: { r: 0.1, g: 1, b: 0.1 },
+            intensity: 4,
+            distance: 8
+        }))
+        .add(Transform.fromJSON({
+            position: { x: 9, y: 2, z: 9 }
+        }))
+        .build(ecd);
+
+    console.log("Trail3D prototype: spawned", emitter_count, "orbiting tube emitters (odd indices lit) + clustered point light");
 }
 
 harness.initialize({