@woosh/meep-engine 2.165.5 → 2.165.6

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.5",
+  "version": "2.165.6",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeadsUpDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js"],"names":[],"mappings":";AAeA;;;;;GAKG;AACH;IASI;;;OAGG;IACH,4BAFW,cAAc,EAqBxB;IA/BD,wCAAgC;IAGhC,2HAGE;IAaE,yBAA8B;IAM9B;;;;OAIG;IACH,+BAAiD;IAGrD,iCAGC;IAED,gCAIC;IAED;;;;;;;OAOG;IACH,sCAwGC;IAED,6BAsBC;CACJ;uBAtMsB,iBAAiB;2BAIb,qBAAqB;uBAFzB,kBAAkB;4CALG,uDAAuD;6BAMtE,iCAAiC;+BAL/B,qCAAqC"}
+{"version":3,"file":"HeadsUpDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js"],"names":[],"mappings":";AAeA;;;;;GAKG;AACH;IASI;;;OAGG;IACH,4BAFW,cAAc,EAqBxB;IA/BD,wCAAgC;IAGhC,2HAGE;IAaE,yBAA8B;IAM9B;;;;OAIG;IACH,+BAAiD;IAGrD,iCAGC;IAED,gCAIC;IAED;;;;;;;OAOG;IACH,sCA6JC;IAED,6BAsBC;CACJ;uBA3PsB,iBAAiB;2BAIb,qBAAqB;uBAFzB,kBAAkB;4CALG,uDAAuD;6BAMtE,iCAAiC;+BAL/B,qCAAqC"}

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js

@@ -118,26 +118,79 @@ class HeadsUpDisplaySystem extends System {
         const worldPositionY = y;
         const worldPositionZ = z;
 
-        // Convert the [-1, 1] screen coordinate into a world coordinate on the near plane
-
-        // apply projection matrix
+        // project world position into clip space
         const _x = projection[0] * x + projection[4] * y + projection[8] * z + projection[12];
         const _y = projection[1] * x + projection[5] * y + projection[9] * z + projection[13];
         const _z = projection[2] * x + projection[6] * y + projection[10] * z + projection[14];
         const _w = projection[3] * x + projection[7] * y + projection[11] * z + projection[15];
 
-        // apply perspective transform
-        const d = 1 / Math.abs(_w);
-        x = _x * d;
-        y = _y * d;
-        z = _z * d;
+        let ndcX;
+        let ndcY;
+        let trackedPositionOutOfBounds;
 
-        const ndcX = (x + 1) / 2;
-        const ndcY = (1 - y) / 2;
+        if (_w > 0) {
+            // point is in front of the camera plane, apply perspective transform
+            const d = 1 / _w;
 
-        vp.position.set(ndcX, ndcY);
+            x = _x * d;
+            y = _y * d;
+            z = _z * d;
+
+            trackedPositionOutOfBounds = z > 1 || z < -1;
+
+            let dx = x * 0.5;
+            let dy = y * -0.5;
+
+            /*
+             Near the camera plane the projected position grows without bound while carrying no more
+             information than its direction from the viewport center. Cap it to the boundary of a doubled
+             viewport rect: edge-stick placement depends only on that direction, and unbounded coordinates
+             wreck float precision downstream (element extents cancel to zero next to values around 1e15).
+             */
+            const m = Math.max(Math.abs(dx), Math.abs(dy));
+
+            if (m > 1) {
+                const s = 1 / m;
+
+                dx *= s;
+                dy *= s;
+            }
+
+            ndcX = 0.5 + dx;
+            ndcY = 0.5 + dy;
+        } else {
+            /*
+             Point is on or behind the camera plane. Perspective division inverts through the projection
+             center, which would place the point on the opposite side of the screen from where it actually is.
+             Only the direction from the viewport center remains meaningful: clip-space (_x, -_y), the limit of
+             the in-front projection as a point approaches the camera plane.
 
-        const trackedPositionOutOfBounds = z > 1 || z < -1;
+             Push the position out along that direction to the boundary of a doubled viewport rect. That is
+             guaranteed to be off-screen, letting stick-to-edge placement resolve it to the correct point on
+             the screen edge; without stick-to-edge the element is hidden anyway.
+             */
+            trackedPositionOutOfBounds = true;
+
+            let dx = _x;
+            let dy = -_y;
+
+            const m = Math.max(Math.abs(dx), Math.abs(dy));
+
+            if (m > 0) {
+                const s = 1 / m;
+
+                dx *= s;
+                dy *= s;
+            } else {
+                // point lies exactly on the camera's view axis, direction is undefined; push down
+                dy = 1;
+            }
+
+            ndcX = 0.5 + dx;
+            ndcY = 0.5 + dy;
+        }
+
+        vp.position.set(ndcX, ndcY);
 
         const visible = (!trackedPositionOutOfBounds || vp.stickToScreenEdge) && this.__visibility_predicate.test(worldPositionX, worldPositionY, worldPositionZ);
 

package/src/engine/ecs/gui/hud/testHudEdgeStick.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testHudEdgeStick.d.ts.map

package/src/engine/ecs/gui/hud/testHudEdgeStick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testHudEdgeStick.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/hud/testHudEdgeStick.js"],"names":[],"mappings":""}

package/src/engine/ecs/gui/hud/testHudEdgeStick.js

@@ -0,0 +1,134 @@
+import { EngineHarness } from "../../../EngineHarness.js";
+import Entity from "../../Entity.js";
+import { Transform } from "../../transform/Transform.js";
+import EmptyView from "../../../../view/elements/EmptyView.js";
+import GUIElement from "../GUIElement.js";
+import GUIElementSystem from "../GUIElementSystem.js";
+import ViewportPosition from "../position/ViewportPosition.js";
+import ViewportPositionSystem from "../position/ViewportPositionSystem.js";
+import HeadsUpDisplay from "./HeadsUpDisplay.js";
+import HeadsUpDisplaySystem from "./HeadsUpDisplaySystem.js";
+import { EngineConfiguration } from "../../../EngineConfiguration.js";
+import { AttachmentSystem } from "../../attachment/AttachmentSystem.js";
+import { CameraSystem } from "../../../graphics/ecs/camera/CameraSystem.js";
+import TopDownCameraController from "../../../graphics/ecs/camera/topdown/TopDownCameraController.js";
+
+const eh = new EngineHarness();
+
+/**
+ *
+ * @param {Engine} engine
+ * @return {EngineConfiguration}
+ */
+function makeConfig(engine) {
+    const r = new EngineConfiguration();
+
+    r.addSystem(new AttachmentSystem());
+    r.addSystem(new HeadsUpDisplaySystem(engine.graphics));
+    r.addSystem(new ViewportPositionSystem(engine.gameView.size));
+    r.addSystem(new GUIElementSystem(engine.gui.view, engine));
+
+    return r;
+}
+
+const RING_RADIUS = 25;
+const BADGE_COUNT = 12;
+
+/**
+ *
+ * @param {Engine} engine
+ */
+async function main(engine) {
+
+    await EngineHarness.buildBasics({
+        engine,
+        enableWater: false,
+        enableShadows: false,
+        pitch: 0.7,
+        distance: 10
+    });
+
+    // highlight stuck badges
+    const style = document.createElement('style');
+    style.textContent = `
+        .hud-edge-stick-badge {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font: bold 12px sans-serif;
+            color: white;
+            border-radius: 50%;
+            border: 2px solid white;
+            box-sizing: border-box;
+        }
+        .hud-edge-stick-badge.hud-system-sticky-flag {
+            border-color: black;
+        }
+    `;
+    document.head.appendChild(style);
+
+    const ecd = engine.entityManager.dataset;
+
+    const tracked = [];
+
+    for (let i = 0; i < BADGE_COUNT; i++) {
+        const angle = (i / BADGE_COUNT) * Math.PI * 2;
+
+        const x = 5 + Math.cos(angle) * RING_RADIUS;
+        const z = 5 + Math.sin(angle) * RING_RADIUS;
+
+        const view = new EmptyView({
+            classList: ['hud-edge-stick-badge'],
+            css: {
+                background: `hsl(${(i / BADGE_COUNT) * 360}, 80%, 45%)`
+            }
+        });
+
+        view.size.set(28, 28);
+        view.el.textContent = String(i);
+
+        const transform = new Transform();
+        transform.position.set(x, 0.5, z);
+
+        const vp = new ViewportPosition();
+        vp.anchor.set(0.5, 0.5);
+        vp.stickToScreenEdge = true;
+        vp.screenEdgeWidth = 8;
+
+        const entity = new Entity()
+            .add(transform)
+            .add(new HeadsUpDisplay())
+            .add(vp)
+            .add(GUIElement.fromView(view))
+            .build(ecd);
+
+        tracked.push({ entity, transform, vp, view, index: i });
+    }
+
+    const active_camera = CameraSystem.getFirstActiveCamera(ecd);
+    const controller = ecd.getComponent(active_camera.entity, TopDownCameraController);
+
+    window.__hud_edge_stick_test = {
+        engine,
+        ecd,
+        tracked,
+        camera: active_camera.component,
+        controller
+    };
+}
+
+/**
+ *
+ * @param {EngineHarness} harness
+ */
+async function init(harness) {
+    const engine = eh.engine;
+
+    await makeConfig(engine).apply(engine);
+
+    await eh.initialize();
+
+    main(engine);
+}
+
+init(eh);

package/src/engine/ecs/gui/position/ViewportPositionSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ViewportPositionSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/position/ViewportPositionSystem.js"],"names":[],"mappings":";AAuBA;IACI,+BAoBC;IAjBG,8DAAkD;IAElD,kEAEC;IAED,kBAAgC;IAEhC,yCAME;IAEF,SAAc;IAGlB,2CAEC;IAED,4CAEC;IAED;;;OAGG;IACH,sBAHW,UAAU,MACV,gBAAgB,QAkE1B;IAED;;;;;OAKG;IACH,SAJW,gBAAgB,MAChB,UAAU,qBA8BpB;IAED;;;;;OAKG;IACH,WAJW,gBAAgB,MAChB,UAAU,qBAmBpB;IA4EL;;;OAGG;IACH,mCAFU,OAAO,CAEwC;CA7ExD;uBAlLsB,iBAAiB;uBACjB,kBAAkB;6BAEZ,uBAAuB;4CAJR,uDAAuD;8BAJrE,iDAAiD"}
+{"version":3,"file":"ViewportPositionSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/position/ViewportPositionSystem.js"],"names":[],"mappings":";AAwBA;IACI,+BAoBC;IAjBG,8DAAkD;IAElD,kEAEC;IAED,kBAAgC;IAEhC,yCAME;IAEF,SAAc;IAGlB,2CAEC;IAED,4CAEC;IAED;;;OAGG;IACH,sBAHW,UAAU,MACV,gBAAgB,QAkE1B;IAED;;;;;OAKG;IACH,SAJW,gBAAgB,MAChB,UAAU,qBA8BpB;IAED;;;;;OAKG;IACH,WAJW,gBAAgB,MAChB,UAAU,qBAmBpB;IAgGL;;;OAGG;IACH,mCAFU,OAAO,CAEwC;CAjGxD;uBAlLsB,iBAAiB;uBACjB,kBAAkB;6BAEZ,uBAAuB;4CAJR,uDAAuD;8BALrE,iDAAiD"}

package/src/engine/ecs/gui/position/ViewportPositionSystem.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../../core/assert.js";
 import { SignalBinding } from "../../../../core/events/signal/SignalBinding.js";
 import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
+import { clamp } from "../../../../core/math/clamp.js";
 import { EPSILON } from "../../../../core/math/EPSILON.js";
 import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
@@ -186,9 +187,6 @@ class ViewportPositionSystem extends System {
 
 const STICKY_FLAG_CLASS_NAME = 'hud-system-sticky-flag';
 
-
-const stickyBounds = new AABB2();
-
 /**
  *
  * @param {View} view
@@ -202,37 +200,60 @@ function setElementPosition(view, bounds, viewportSize, vp) {
 
     if (vp.stickToScreenEdge) {
 
-
         const screenEdgeWidth = vp.screenEdgeWidth;
         const clipEdgeX = screenEdgeWidth / viewportSize.x;
         const clipEdgeY = screenEdgeWidth / viewportSize.y;
 
+        const width = bounds.width;
+        const height = bounds.height;
 
-        stickyBounds.set(clipEdgeX, clipEdgeY, 1 - clipEdgeX, 1 - clipEdgeY);
+        const anchorX = vp.anchor.x;
+        const anchorY = vp.anchor.y;
 
-        let stickFlag = false;
+        // tracked point that the element hangs off, in normalized viewport coordinates
+        const px = bounds.x0 + width * anchorX;
+        const py = bounds.y0 + height * anchorY;
+
+        // rect of anchor positions for which the element stays fully on screen, inset by the edge margin
+        const ax0 = clipEdgeX + width * anchorX;
+        const ay0 = clipEdgeY + height * anchorY;
+        const ax1 = 1 - clipEdgeX - width * (1 - anchorX);
+        const ay1 = 1 - clipEdgeY - height * (1 - anchorY);
+
+        const stickFlag = px < ax0 || px > ax1 || py < ay0 || py > ay1;
+
+        if (stickFlag) {
+            /*
+             Tracked point is off-screen. Place the element on the line from the viewport center towards the
+             tracked point, at the point where that line leaves the valid rect. This keeps the element on the
+             invisible line leading to the tracked position, instead of clamping each axis independently,
+             which piles far-away directions into the corners.
+             */
+            const dx = px - 0.5;
+            const dy = py - 0.5;
+
+            let t = 1;
+
+            if (dx > 0) {
+                t = Math.min(t, (ax1 - 0.5) / dx);
+            } else if (dx < 0) {
+                t = Math.min(t, (ax0 - 0.5) / dx);
+            }
 
-        if (bounds.x0 < stickyBounds.x0) {
-            x = stickyBounds.x0;
+            if (dy > 0) {
+                t = Math.min(t, (ay1 - 0.5) / dy);
+            } else if (dy < 0) {
+                t = Math.min(t, (ay0 - 0.5) / dy);
+            }
 
-            stickFlag = true;
-        } else if (bounds.x1 > stickyBounds.x1) {
-            x = stickyBounds.x1 - bounds.width;
+            // clamp covers rects that do not contain the viewport center, such as for oversized elements
+            const sx = clamp(0.5 + dx * t, ax0, ax1);
+            const sy = clamp(0.5 + dy * t, ay0, ay1);
 
-            stickFlag = true;
+            x = sx - width * anchorX;
+            y = sy - height * anchorY;
         } else {
             x = bounds.x0;
-        }
-
-        if (bounds.y0 < stickyBounds.y0) {
-            y = stickyBounds.y0;
-
-            stickFlag = true;
-        } else if (bounds.y1 > stickyBounds.y1) {
-            y = stickyBounds.y1 - bounds.height;
-
-            stickFlag = true;
-        } else {
             y = bounds.y0;
         }
 

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({

package/src/engine/graphics/render/forward_plus/LightManager.d.ts

@@ -191,6 +191,11 @@ export class LightManager {
      * @private
      */
     private __handle_light_dimensions_change;
+    /**
+     *
+     * @private
+     */
+    private __handle_light_appearance_change;
     /**
      *
      * @param {LightRenderMetadata} data

package/src/engine/graphics/render/forward_plus/LightManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightManager.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/forward_plus/LightManager.js"],"names":[],"mappings":"AAoIA;IAiBQ;;;;OAIG;IACH,2BAAgD;IAEhD,oCAAoC;IACpC,yCAA4C;IAE5C;;;;;;;;OAQG;IACH,0BAKC;IAaD;;;;;OAKG;IACH,+BAAoD;IAMpD;;;;;OAKG;IACH,8BAAmD;IAMnD;;;;OAIG;IACH,uCAAiF;IAWjF;;;;;OAKG;IACH,+BAEE;IAEF;;;;OAIG;IACH,iCAA8E;IAE9E;;;;OAIG;IACH,2BAAmC;IAEnC;;;;;OAKG;IACH,kCAAoE;IACpE;;;;;OAKG;IACH,kCAAoE;IAEpE;;;;OAIG;IACH,gCAAiC;IAEjC;;;;OAIG;IACH,6BAAiD;IACjD;;;;OAIG;IACH,6BAAiD;IAEjD;;;;OAIG;IACH,uBAAmC;IAEnC;;;;OAIG;IACH,8BAAiD;IAEjD;;;;OAIG;IACH,4BAA+C;IAG/C;;;;OAIG;IACH,yBAA2C;IAE3C;;;;OAIG;IACH,iCAAmD;IAUnD;;;;;OAKG;IACH,kCAAqC;IAErC;;;;OAIG;IACH,mCAAsC;IAK1C,0BAEC;IAED;;;;;;OAMG;IACH,0CAQC;IAED;;;OAGG;IACH,uCAEC;IAED,qCAQC;IAED;;;;;;OAMG;IACH,4CAgBC;IAED,iCAIC;IAED,gCA6BC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,oBAFa,WAAW,CAIvB;IAED;;;OAGG;IACH,kBAFa,WAAW,CAIvB;IAED;;OAEG;IACH,sBAFa,aAAa,CAIzB;IAED;;OAEG;IACH,wBAFa,WAAW,CAIvB;IAED;;;OAGG;IACH,iBAFa,SAAS,OAAO,CAAC,CAI7B;IAED;;;OAGG;IACH,yCAKC;IAED;;;;OAIG;IACH,qCAyBC;IAED;;;;OAIG;IACH,uCA8BC;IAED;;;;OAIG;IACH,qCAMC;IAED;;;;OAIG;IACH,uCAKC;IAED;;;;;OAKG;IACH,4CAJW,mBAAmB,GACjB,MAAM,CAalB;IAED;;;;;;OAMG;IACH,+BAgCC;IAED;;;OAGG;IACH,6BAoBC;IAED,6BAYC;IAGD;;;;OAIG;IACH,6BAMC;IAED,mCA0EC;IAED,mCAgFC;IAED;;;OAGG;IACH,oCA+IC;IAED;;;OAGG;IACH,uCAUC;IAED;;;OAGG;IACH,oCAOC;IAED;;;OAGG;IACH,uCAWC;IAED;;;OAGG;IACH,mBAFW,SAAO,MAAM,iBAAiB,QAmDxC;IAED,gBAKC;IAED;;;;;OAKG;IACH,wBAJW,MAAM,KACN,MAAM,KACN,MAAM,QA2ChB;IAED;;;;OAIG;IACH,gCAFa,OAAO,CAInB;IAED;;;OAGG;IACH,qCAMC;IAED;;;;OAIG;IACH,mCAFa,OAAO,CAiBnB;;CACJ;4BAvrCM,OAAO;8BAAP,OAAO;oBAkBM,kCAAkC;oCAiBlB,0BAA0B"}
+{"version":3,"file":"LightManager.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/forward_plus/LightManager.js"],"names":[],"mappings":"AAoIA;IAiBQ;;;;OAIG;IACH,2BAAgD;IAEhD,oCAAoC;IACpC,yCAA4C;IAE5C;;;;;;;;OAQG;IACH,0BAKC;IAaD;;;;;OAKG;IACH,+BAAoD;IAMpD;;;;;OAKG;IACH,8BAAmD;IAMnD;;;;OAIG;IACH,uCAAiF;IAWjF;;;;;OAKG;IACH,+BAEE;IAEF;;;;OAIG;IACH,iCAA8E;IAE9E;;;;OAIG;IACH,2BAAmC;IAEnC;;;;;OAKG;IACH,kCAAoE;IACpE;;;;;OAKG;IACH,kCAAoE;IAEpE;;;;OAIG;IACH,gCAAiC;IAEjC;;;;OAIG;IACH,6BAAiD;IACjD;;;;OAIG;IACH,6BAAiD;IAEjD;;;;OAIG;IACH,uBAAmC;IAEnC;;;;OAIG;IACH,8BAAiD;IAEjD;;;;OAIG;IACH,4BAA+C;IAG/C;;;;OAIG;IACH,yBAA2C;IAE3C;;;;OAIG;IACH,iCAAmD;IAUnD;;;;;OAKG;IACH,kCAAqC;IAErC;;;;OAIG;IACH,mCAAsC;IAK1C,0BAEC;IAED;;;;;;OAMG;IACH,0CAQC;IAED;;;OAGG;IACH,uCAEC;IAED,qCAQC;IAED;;;;;;OAMG;IACH,4CAgBC;IAED,iCAIC;IAED,gCA6BC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,oBAFa,WAAW,CAIvB;IAED;;;OAGG;IACH,kBAFa,WAAW,CAIvB;IAED;;OAEG;IACH,sBAFa,aAAa,CAIzB;IAED;;OAEG;IACH,wBAFa,WAAW,CAIvB;IAED;;;OAGG;IACH,iBAFa,SAAS,OAAO,CAAC,CAI7B;IAED;;;OAGG;IACH,yCAKC;IAED;;;OAGG;IACH,yCAGC;IAED;;;;OAIG;IACH,qCAyBC;IAED;;;;OAIG;IACH,uCA8BC;IAED;;;;OAIG;IACH,qCAOC;IAED;;;;OAIG;IACH,uCAMC;IAED;;;;;OAKG;IACH,4CAJW,mBAAmB,GACjB,MAAM,CAalB;IAED;;;;;;OAMG;IACH,+BAgCC;IAED;;;OAGG;IACH,6BAoBC;IAED,6BAYC;IAGD;;;;OAIG;IACH,6BAMC;IAED,mCA0EC;IAED,mCAgFC;IAED;;;OAGG;IACH,oCA+IC;IAED;;;OAGG;IACH,uCAUC;IAED;;;OAGG;IACH,oCAOC;IAED;;;OAGG;IACH,uCAWC;IAED;;;OAGG;IACH,mBAFW,SAAO,MAAM,iBAAiB,QAmDxC;IAED,gBAKC;IAED;;;;;OAKG;IACH,wBAJW,MAAM,KACN,MAAM,KACN,MAAM,QA2ChB;IAED;;;;OAIG;IACH,gCAFa,OAAO,CAInB;IAED;;;OAGG;IACH,qCAMC;IAED;;;;OAIG;IACH,mCAFa,OAAO,CAiBnB;;CACJ;4BAlsCM,OAAO;8BAAP,OAAO;oBAkBM,kCAAkC;oCAiBlB,0BAA0B"}

package/src/engine/graphics/render/forward_plus/LightManager.js

@@ -505,6 +505,15 @@ export class LightManager {
         this.__light_data_needs_update = true;
     }
 
+    /**
+     *
+     * @private
+     */
+    __handle_light_appearance_change() {
+        // appearance changes (such as color or intensity) don't affect bounds, only the encoded data
+        this.__light_data_needs_update = true;
+    }
+
     /**
      *
      * @param {LightRenderMetadata} data
@@ -585,6 +594,7 @@ export class LightManager {
         const light = data.light;
 
         light.onDimensionChanged(this.__handle_light_dimensions_change, this);
+        light.onAppearanceChanged(this.__handle_light_appearance_change, this);
     }
 
     /**
@@ -597,6 +607,7 @@ export class LightManager {
 
         const light = data.light;
         light.offDimensionChanged(this.__handle_light_dimensions_change, this);
+        light.offAppearanceChanged(this.__handle_light_appearance_change, this);
     }
 
     /**

package/src/engine/graphics/render/forward_plus/model/AbstractLight.d.ts

@@ -2,7 +2,7 @@ export class AbstractLight {
     id: number;
     toString(): string;
     /**
-     *
+     * Dimension changes affect the light's bounds ({@link AbstractLight#getAABB}) as well as its encoded record
      * @param {function} f
      * @param {*} [thisArg]
      * @returns {void}
@@ -15,6 +15,21 @@ export class AbstractLight {
      * @returns {void}
      */
     offDimensionChanged(f: Function, thisArg?: any): void;
+    /**
+     * Appearance changes affect the light's encoded record ({@link AbstractLight#toArray}) but not its bounds,
+     * such as color or intensity
+     * @param {function} f
+     * @param {*} [thisArg]
+     * @returns {void}
+     */
+    onAppearanceChanged(f: Function, thisArg?: any): void;
+    /**
+     *
+     * @param {function} f
+     * @param {*} [thisArg]
+     * @returns {void}
+     */
+    offAppearanceChanged(f: Function, thisArg?: any): void;
     /**
      *
      * @param {number[]} result

package/src/engine/graphics/render/forward_plus/model/AbstractLight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/AbstractLight.js"],"names":[],"mappings":"AAEA;IAEI,WAAkB;IAGlB,mBAEC;IAED;;;;;OAKG;IACH,gDAFa,IAAI,CAIhB;IAED;;;;;OAKG;IACH,iDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GACrC,IAAI,CAIhB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,WAClC,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,eAHW,aAAa,GACX,MAAM,CAIlB;IAGL,aAA4B;CAF3B"}
+{"version":3,"file":"AbstractLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/AbstractLight.js"],"names":[],"mappings":"AAEA;IAEI,WAAkB;IAGlB,mBAEC;IAED;;;;;OAKG;IACH,gDAFa,IAAI,CAIhB;IAED;;;;;OAKG;IACH,iDAFa,IAAI,CAIhB;IAED;;;;;;OAMG;IACH,iDAFa,IAAI,CAIhB;IAED;;;;;OAKG;IACH,kDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GACrC,IAAI,CAIhB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,WAClC,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,eAHW,aAAa,GACX,MAAM,CAIlB;IAGL,aAA4B;CAF3B"}

package/src/engine/graphics/render/forward_plus/model/AbstractLight.js

@@ -10,7 +10,7 @@ export class AbstractLight {
     }
 
     /**
-     *
+     * Dimension changes affect the light's bounds ({@link AbstractLight#getAABB}) as well as its encoded record
      * @param {function} f
      * @param {*} [thisArg]
      * @returns {void}
@@ -29,6 +29,27 @@ export class AbstractLight {
         throw new Error('Not Implemented');
     }
 
+    /**
+     * Appearance changes affect the light's encoded record ({@link AbstractLight#toArray}) but not its bounds,
+     * such as color or intensity
+     * @param {function} f
+     * @param {*} [thisArg]
+     * @returns {void}
+     */
+    onAppearanceChanged(f, thisArg) {
+        throw new Error('Not Implemented');
+    }
+
+    /**
+     *
+     * @param {function} f
+     * @param {*} [thisArg]
+     * @returns {void}
+     */
+    offAppearanceChanged(f, thisArg) {
+        throw new Error('Not Implemented');
+    }
+
     /**
      *
      * @param {number[]} result

package/src/engine/graphics/render/forward_plus/model/Decal.d.ts

@@ -29,6 +29,13 @@ export class Decal extends AbstractLight {
     compare(other: any): number;
     onDimensionChanged(f: any, thisArg: any): void;
     offDimensionChanged(f: any, thisArg: any): void;
+    /**
+     * Appearance data (color, uv) is stored in raw arrays without change signals; uv only shifts when the
+     * texture atlas re-packs, which happens alongside decal addition/removal where the encoded data is
+     * invalidated anyway
+     */
+    onAppearanceChanged(f: any, thisArg: any): void;
+    offAppearanceChanged(f: any, thisArg: any): void;
     getCenter(result: any): void;
     getAABB(result: any): void;
     toArray(destination: any, address: any): number;

package/src/engine/graphics/render/forward_plus/model/Decal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Decal.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/Decal.js"],"names":[],"mappings":"AASA;IAIQ;;;OAGG;IACH,WAFU,MAAM,EAAE,GAAC,YAAY,GAAC,MAAM,CAED;IACrC,gCAA6C;IAC7C,iBAA6B;IAE7B,oBAAgC;IAKhC;;;OAGG;IACH,2BAA2B;IAE3B;;;;OAIG;IACH,eAFU,MAAM,CAEM;IAEtB,0EAA6C;IAGjD;;;OAGG;IACH,gBAFW,MAAM,EAAE,GAAC,YAAY,GAAC,UAAU,MAAM,CAAC,QAOjD;IAED,6CAGC;IAED,yCAGC;IAED,4BAUC;IAED,+CAGC;IAED,gDAGC;IAED,6BAKC;IAED,2BAIC;IAED,gDAcC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;IAEvB,2BAAkC;CARjC;8BAjH6B,oBAAoB;mBAK/B,6CAA6C"}
+{"version":3,"file":"Decal.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/Decal.js"],"names":[],"mappings":"AASA;IAIQ;;;OAGG;IACH,WAFU,MAAM,EAAE,GAAC,YAAY,GAAC,MAAM,CAED;IACrC,gCAA6C;IAC7C,iBAA6B;IAE7B,oBAAgC;IAKhC;;;OAGG;IACH,2BAA2B;IAE3B;;;;OAIG;IACH,eAFU,MAAM,CAEM;IAEtB,0EAA6C;IAGjD;;;OAGG;IACH,gBAFW,MAAM,EAAE,GAAC,YAAY,GAAC,UAAU,MAAM,CAAC,QAOjD;IAED,6CAGC;IAED,yCAGC;IAED,4BAUC;IAED,+CAGC;IAED,gDAGC;IAED;;;;OAIG;IACH,gDACC;IAED,iDACC;IAED,6BAKC;IAED,2BAIC;IAED,gDAcC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;IAEvB,2BAAkC;CARjC;8BA5H6B,oBAAoB;mBAK/B,6CAA6C"}

package/src/engine/graphics/render/forward_plus/model/Decal.js

@@ -83,6 +83,17 @@ export class Decal extends AbstractLight {
         this.__signal_transfom_changed.remove(f, thisArg);
     }
 
+    /**
+     * Appearance data (color, uv) is stored in raw arrays without change signals; uv only shifts when the
+     * texture atlas re-packs, which happens alongside decal addition/removal where the encoded data is
+     * invalidated anyway
+     */
+    onAppearanceChanged(f, thisArg) {
+    }
+
+    offAppearanceChanged(f, thisArg) {
+    }
+
     getCenter(result) {
         // extract translation portion of the matrix
         result[0] = this.transform[12];

package/src/engine/graphics/render/forward_plus/model/PointLight.d.ts

@@ -23,6 +23,8 @@ export class PointLight extends AbstractLight {
     getAABB(result: any): void;
     onDimensionChanged(listener: any, context: any): void;
     offDimensionChanged(listener: any, context: any): void;
+    onAppearanceChanged(listener: any, context: any): void;
+    offAppearanceChanged(listener: any, context: any): void;
     /**
      * @readonly
      * @type {boolean}

package/src/engine/graphics/render/forward_plus/model/PointLight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/PointLight.js"],"names":[],"mappings":"AAKA;IAEI;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;OAGG;IACH,iBAFU,OAAO,CAEO;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEY;IAE3B;;;OAGG;IACH,oBAFU,OAAO,CAEU;IAG3B,6BAEC;IAED,2BAeC;IAED,sDAGC;IAED,uDAGC;IA6BL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;IAEjC,2BAAuC;CARtC;8BArF6B,oBAAoB;oBAD9B,qCAAqC;oBADrC,qCAAqC;sBADnC,oCAAoC"}
+{"version":3,"file":"PointLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/PointLight.js"],"names":[],"mappings":"AAKA;IAEI;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;OAGG;IACH,iBAFU,OAAO,CAEO;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEY;IAE3B;;;OAGG;IACH,oBAFU,OAAO,CAEU;IAG3B,6BAEC;IAED,2BAeC;IAED,sDAGC;IAED,uDAGC;IAED,uDAGC;IAED,wDAGC;IA6BL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;IAEjC,2BAAuC;CARtC;8BA/F6B,oBAAoB;oBAD9B,qCAAqC;oBADrC,qCAAqC;sBADnC,oCAAoC"}

package/src/engine/graphics/render/forward_plus/model/PointLight.js

@@ -61,6 +61,16 @@ export class PointLight extends AbstractLight {
         this.radius.onChanged.remove(listener, context);
     }
 
+    onAppearanceChanged(listener, context) {
+        this.color.onChanged.add(listener, context);
+        this.intensity.onChanged.add(listener, context);
+    }
+
+    offAppearanceChanged(listener, context) {
+        this.color.onChanged.remove(listener, context);
+        this.intensity.onChanged.remove(listener, context);
+    }
+
     /**
      *
      * @param {number[]|Float32Array|Float64Array} destination

package/src/engine/graphics/render/forward_plus/model/SpotLight.d.ts

@@ -38,6 +38,8 @@ export class SpotLight extends AbstractLight {
     getAABB(result: any): void;
     onDimensionChanged(listener: any, context: any): void;
     offDimensionChanged(listener: any, context: any): void;
+    onAppearanceChanged(listener: any, context: any): void;
+    offAppearanceChanged(listener: any, context: any): void;
     /**
      * @readonly
      * @type {boolean}

package/src/engine/graphics/render/forward_plus/model/SpotLight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SpotLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/SpotLight.js"],"names":[],"mappings":"AAMA;IAGI;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;OAGG;IACH,oBAFU,OAAO,CAES;IAE1B;;;OAGG;IACH,gBAFU,OAAO,CAEgB;IAEjC;;;OAGG;IACH,mBAFU,OAAO,CAES;IAE1B;;;OAGG;IACH,gBAFU,KAAK,CAEY;IAE3B;;;OAGG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,mBAFU,OAAO,CAEW;IAG5B,6BAYC;IAED,2BAcC;IAED,sDAKC;IAED,uDAKC;IAuCL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B;8BA/H6B,oBAAoB;oBAD9B,qCAAqC;oBADrC,qCAAqC;sBAFnC,oCAAoC"}
+{"version":3,"file":"SpotLight.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/model/SpotLight.js"],"names":[],"mappings":"AAMA;IAGI;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;OAGG;IACH,oBAFU,OAAO,CAES;IAE1B;;;OAGG;IACH,gBAFU,OAAO,CAEgB;IAEjC;;;OAGG;IACH,mBAFU,OAAO,CAES;IAE1B;;;OAGG;IACH,gBAFU,KAAK,CAEY;IAE3B;;;OAGG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,mBAFU,OAAO,CAEW;IAG5B,6BAYC;IAED,2BAcC;IAED,sDAKC;IAED,uDAKC;IAED,uDAIC;IAED,wDAIC;IAuCL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B;8BA3I6B,oBAAoB;oBAD9B,qCAAqC;oBADrC,qCAAqC;sBAFnC,oCAAoC"}

package/src/engine/graphics/render/forward_plus/model/SpotLight.js

@@ -94,6 +94,18 @@ export class SpotLight extends AbstractLight {
         this.direction.onChanged.remove(listener, context);
     }
 
+    onAppearanceChanged(listener, context) {
+        this.color.onChanged.add(listener, context);
+        this.intensity.onChanged.add(listener, context);
+        this.penumbra.onChanged.add(listener, context);
+    }
+
+    offAppearanceChanged(listener, context) {
+        this.color.onChanged.remove(listener, context);
+        this.intensity.onChanged.remove(listener, context);
+        this.penumbra.onChanged.remove(listener, context);
+    }
+
     /**
      *
      * @param {number[]|Float32Array|Float64Array} destination

package/src/engine/graphics/trail/tube/TubeMaterialX.d.ts

@@ -1,5 +1,12 @@
 export class TubeMaterialX extends ShaderMaterial {
-    constructor(params: any);
+    /**
+     * @param {Object} params three.js material parameters, plus:
+     * @param {boolean} [params.lit=false] compile the lit variant — standard light
+     *     chain, receive-only shadows — instead of the unlit one
+     */
+    constructor({ lit, ...params }?: {
+        lit?: boolean;
+    });
 }
 import { ShaderMaterial } from "three";
 //# sourceMappingURL=TubeMaterialX.d.ts.map

package/src/engine/graphics/trail/tube/TubeMaterialX.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TubeMaterialX.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeMaterialX.js"],"names":[],"mappings":"AAsDA;IACI,yBAuBC;CACJ;+BA/E0D,OAAO"}
+{"version":3,"file":"TubeMaterialX.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeMaterialX.js"],"names":[],"mappings":"AAuIA;IACI;;;;OAIG;IACH;QAH4B,GAAG,GAApB,OAAO;OAoCjB;CACJ;+BA/KsF,OAAO"}

package/src/engine/graphics/trail/tube/TubeMaterialX.js

@@ -1,12 +1,25 @@
-import { DoubleSide, NormalBlending, ShaderMaterial } from "three";
+import { DoubleSide, NormalBlending, ShaderMaterial, UniformsLib, UniformsUtils } from "three";
 
 const TWO_PI = "6.283185307179586";
 
 /**
- * Unlit tube material. Vertices arrive as ring CENTRES; the actual surface vertex
+ * Tube material. Vertices arrive as ring CENTRES; the actual surface vertex
  * is extruded here in WORLD space from the per-knot tangent frame (tn, tb) and the
  * vertex's angular position `tubeUv.x`. The mesh transform is identity (centres are
  * already world space, written CPU-side), so modelViewMatrix == viewMatrix.
+ *
+ * Unlit by default. The LIT define switches the fragment stage onto the standard
+ * three.js light chain instead — specular is forced to zero, so the tube shades as
+ * a matte (Lambert) surface under ambient / hemisphere / light-probe / directional /
+ * point / spot lights, and receives shadows (it never casts them). The surface
+ * normal is the ring's radial direction; the per-knot thickness taper's tilt is
+ * ignored.
+ *
+ * The lit variant deliberately follows the three.js chunk conventions —
+ * `void main() {`, `transformed`, `#include <worldpos_vertex>`,
+ * `#include <lights_pars_begin>`, `#include <lights_fragment_begin>` — because the
+ * Forward+ {@link MaterialTransformer} keys its textual injections on exactly these
+ * markers to add clustered point-light accumulation and decals.
  */
 const vertexShader = `
     varying vec2 vUv;
@@ -19,18 +32,44 @@ const vertexShader = `
     attribute float thickness;
     attribute vec3 color;
 
-    void main(){
+    #ifdef LIT
+
+        varying vec3 vNormal;
+        varying vec3 vViewPosition;
+
+        #include <common>
+        #include <shadowmap_pars_vertex>
+
+    #endif
+
+    void main() {
         float angle = tubeUv.x * ${TWO_PI};
 
         // radial direction in the knot's frame; unit, perpendicular to the tangent
         vec3 radial = cos(angle) * tn + sin(angle) * tb;
 
-        vec3 surface = position + radial * (thickness * 0.5);
+        // extruded surface vertex, named per three.js chunk convention
+        vec3 transformed = position + radial * (thickness * 0.5);
 
         vUv = tubeUv;
         vColor = vec4(color / 255.0, alpha);
 
-        gl_Position = projectionMatrix * modelViewMatrix * vec4(surface, 1.0);
+        vec4 mvPosition = modelViewMatrix * vec4(transformed, 1.0);
+
+        #ifdef LIT
+
+            // the tube's surface normal is the radial direction itself
+            vec3 transformedNormal = normalMatrix * radial;
+
+            vNormal = transformedNormal;
+            vViewPosition = -mvPosition.xyz;
+
+            #include <worldpos_vertex>
+            #include <shadowmap_vertex>
+
+        #endif
+
+        gl_Position = projectionMatrix * mvPosition;
     }
 `;
 
@@ -40,7 +79,21 @@ const fragmentShader = `
 
     uniform sampler2D uDiffuse;
 
-    void main(){
+    #ifdef LIT
+
+        // vViewPosition is declared by <lights_phong_pars_fragment>
+        varying vec3 vNormal;
+
+        #include <common>
+        #include <packing>
+        #include <bsdfs>
+        #include <lights_pars_begin>
+        #include <lights_phong_pars_fragment>
+        #include <shadowmap_pars_fragment>
+
+    #endif
+
+    void main() {
         vec4 diffuseColor = vColor;
 
         #ifdef USE_TEXTURE
@@ -48,24 +101,67 @@ const fragmentShader = `
             diffuseColor *= texel;
         #endif
 
-        gl_FragColor = diffuseColor;
+        #ifdef LIT
+
+            ReflectedLight reflectedLight = ReflectedLight(vec3(0.0), vec3(0.0), vec3(0.0), vec3(0.0));
+
+            #include <normal_fragment_begin>
+
+            // Blinn-Phong with specular forced to zero = pure Lambert; a trail is a
+            // matte surface, highlights on a fading tube read as artifacts
+            BlinnPhongMaterial material;
+            material.diffuseColor = diffuseColor.rgb;
+            material.specularColor = vec3(0.0);
+            material.specularShininess = 1.0;
+            material.specularStrength = 0.0;
+
+            #include <lights_fragment_begin>
+            #include <lights_fragment_end>
+
+            vec3 outgoingLight = reflectedLight.directDiffuse + reflectedLight.indirectDiffuse;
+
+            gl_FragColor = vec4(outgoingLight, diffuseColor.a);
+
+            #include <tonemapping_fragment>
+            #include <encodings_fragment>
+
+        #else
+
+            gl_FragColor = diffuseColor;
+
+        #endif
     }
 `;
 
 export class TubeMaterialX extends ShaderMaterial {
-    constructor(params) {
+    /**
+     * @param {Object} params three.js material parameters, plus:
+     * @param {boolean} [params.lit=false] compile the lit variant — standard light
+     *     chain, receive-only shadows — instead of the unlit one
+     */
+    constructor({ lit = false, ...params } = {}) {
         super({
             fragmentShader,
             vertexShader,
-            uniforms: {
-                uDiffuse: {
-                    type: 't',
-                    value: null
-                }
-            },
+            uniforms: lit
+                ? UniformsUtils.merge([
+                    UniformsLib.lights,
+                    { uDiffuse: { value: null } }
+                ])
+                : {
+                    uDiffuse: {
+                        type: 't',
+                        value: null
+                    }
+                },
             defines: {
-                USE_TEXTURE: false
+                USE_TEXTURE: false,
+                // a `false` define is omitted from the compiled shader entirely,
+                // not emitted as "#define LIT false"
+                LIT: lit
             },
+            // wires the renderer's light state into the merged uniforms
+            lights: lit,
             blending: NormalBlending,
             transparent: true,
             // The primary use is transparent trails (depthWrite: false). Callers that

package/src/engine/graphics/trail/tube/TubeXMaterialSpec.d.ts

@@ -1,7 +1,7 @@
 /**
  * Material configuration for a {@link TubeX}. Used as a cache key in
  * {@link TubeXPlugin}, so any field that changes the compiled material (texture,
- * depth-write mode) participates in {@link equals}/{@link hash}.
+ * depth-write mode, lighting) participates in {@link equals}/{@link hash}.
  */
 export class TubeXMaterialSpec {
     /**
@@ -16,11 +16,18 @@ export class TubeXMaterialSpec {
      * @type {boolean}
      */
     depthWrite: boolean;
+    /**
+     * When true the tube shades as a matte surface under the standard scene
+     * lights and receives shadows; when false (default) it renders unlit.
+     * @type {boolean}
+     */
+    lit: boolean;
     equals(other: any): boolean;
     hash(): number;
-    fromJSON({ diffuse, depthWrite }: {
+    fromJSON({ diffuse, depthWrite, lit }: {
         diffuse: any;
         depthWrite?: boolean;
+        lit?: boolean;
     }): void;
 }
 //# sourceMappingURL=TubeXMaterialSpec.d.ts.map

package/src/engine/graphics/trail/tube/TubeXMaterialSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TubeXMaterialSpec.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeXMaterialSpec.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IAEI;;;OAGG;IACH,SAFU,SAAO,IAAI,CAEN;IAEf;;;;;OAKG;IACH,YAFU,OAAO,CAEE;IAEnB,4BAGC;IAED,eAEC;IAED;;;aAYC;CACJ"}
+{"version":3,"file":"TubeXMaterialSpec.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeXMaterialSpec.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IAEI;;;OAGG;IACH,SAFU,SAAO,IAAI,CAEN;IAEf;;;;;OAKG;IACH,YAFU,OAAO,CAEE;IAEnB;;;;OAIG;IACH,KAFU,OAAO,CAEL;IAEZ,4BAIC;IAED,eAEC;IAED;;;;aAeC;CACJ"}

package/src/engine/graphics/trail/tube/TubeXMaterialSpec.js

@@ -4,7 +4,7 @@ import { computeStringHash } from "../../../../core/primitives/strings/computeSt
 /**
  * Material configuration for a {@link TubeX}. Used as a cache key in
  * {@link TubeXPlugin}, so any field that changes the compiled material (texture,
- * depth-write mode) participates in {@link equals}/{@link hash}.
+ * depth-write mode, lighting) participates in {@link equals}/{@link hash}.
  */
 export class TubeXMaterialSpec {
 
@@ -22,16 +22,24 @@ export class TubeXMaterialSpec {
      */
     depthWrite = false;
 
+    /**
+     * When true the tube shades as a matte surface under the standard scene
+     * lights and receives shadows; when false (default) it renders unlit.
+     * @type {boolean}
+     */
+    lit = false;
+
     equals(other) {
         return this.diffuse === other.diffuse
-            && this.depthWrite === other.depthWrite;
+            && this.depthWrite === other.depthWrite
+            && this.lit === other.lit;
     }
 
     hash() {
-        return (computeStringHash(this.diffuse) * 2) + (this.depthWrite ? 1 : 0);
+        return (computeStringHash(this.diffuse) * 4) + (this.lit ? 2 : 0) + (this.depthWrite ? 1 : 0);
     }
 
-    fromJSON({ diffuse, depthWrite = false }) {
+    fromJSON({ diffuse, depthWrite = false, lit = false }) {
 
         if (diffuse !== undefined && diffuse !== null) {
             assert.isString(diffuse, "diffuse");
@@ -43,5 +51,8 @@ export class TubeXMaterialSpec {
 
         assert.isBoolean(depthWrite, "depthWrite");
         this.depthWrite = depthWrite;
+
+        assert.isBoolean(lit, "lit");
+        this.lit = lit;
     }
 }

package/src/engine/graphics/trail/tube/TubeXPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TubeXPlugin.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeXPlugin.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH;IAOI,8BAWC;IARG,WAAyB;IAU7B;;;OAGG;IACH,4CAFa,aAAa,CAIzB;;CAsCJ;6BA3E4B,iCAAiC;8BAChC,oBAAoB"}
+{"version":3,"file":"TubeXPlugin.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeXPlugin.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH;IAOI,8BAWC;IARG,WAAyB;IAU7B;;;OAGG;IACH,4CAFa,aAAa,CAIzB;;CA4CJ;6BAjF4B,iCAAiC;8BAChC,oBAAoB"}

package/src/engine/graphics/trail/tube/TubeXPlugin.js

@@ -48,6 +48,7 @@ export class TubeXPlugin extends EnginePlugin {
     #build_material(spec) {
 
         const material = new TubeMaterialX({
+            lit: spec.lit,
             transparent: true,
             depthWrite: spec.depthWrite,
             wireframe: false
@@ -75,6 +76,11 @@ export class TubeXPlugin extends EnginePlugin {
             material.needsUpdate = true;
         }
 
-        return material;
+        // Hand the material to the material manager so renderer-wide compile steps
+        // apply — under Forward+ the lit variant is rewritten to also receive
+        // clustered point lights and decals. With no steps registered this is a
+        // pass-through. The async texture callback above still lands: the compiled
+        // material shares the source's uniform objects.
+        return this.engine.graphics.getMaterialManager().obtain(material).getValue();
     }
 }