@needle-tools/engine 4.10.4 → 4.10.5-next.267a93d

package/lib/engine-components/web/CursorFollow.js

@@ -9,6 +9,9 @@ import { getTempVector } from "../../engine/engine_three_utils.js";
 import { Behaviour } from "../Component.js";
 /**
  * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ *
+ * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
+ *
  * @category Web
  * @group Components
  * @component
@@ -19,31 +22,59 @@ export class CursorFollow extends Behaviour {
      * @default 0
      */
     damping = 0;
+    /**
+     * When enabled the object will follow the cursor even outside of the needle-engine canvas. This is useful for example for look at effects where you have a small needle-engine element on your page and you want the 3D object to keep looking at the cursor even when it's outside of the canvas.
+     * @default true
+     */
+    useFullPage = true;
     /**
      * If true, the initial distance to the camera is maintained when following the cursor.
      * @default true
      */
     keepDistance = true;
-    awake() {
-        this._distance = -1;
-    }
     _distance = -1;
-    updateDistance() {
-        if (this.keepDistance && this._distance !== -1) {
+    updateDistance(force = false) {
+        if (!force && (this.keepDistance && this._distance !== -1)) {
             return;
         }
         this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
     }
     /** @internal */
+    awake() {
+        this._distance = -1;
+    }
+    onEnable() {
+        this._distance = -1;
+        window.addEventListener('pointermove', this._onPointerMove);
+    }
+    onDisable() {
+        window.removeEventListener('pointermove', this._onPointerMove);
+    }
+    _ndc_x = 0;
+    _ndc_y = 0;
+    _onPointerMove = (e) => {
+        if (!this.useFullPage)
+            return;
+        const x = e.clientX;
+        const y = e.clientY;
+        const domx = this.context.domX;
+        const domy = this.context.domY;
+        const domw = this.context.domWidth;
+        const domh = this.context.domHeight;
+        this._ndc_x = (x - domx) / domw * 2 - 1;
+        this._ndc_y = -(y - domy) / domh * 2 + 1;
+    };
+    /** @internal */
     update() {
         // continuously update distance in case camera or object moves
         this.updateDistance();
+        const x = this.useFullPage ? this._ndc_x : this.context.input.mousePositionRC.x;
+        const y = this.useFullPage ? this._ndc_y : this.context.input.mousePositionRC.y;
         // follow cursor in screenspace but maintain initial distance from camera
-        const cursor = this.context.input.mousePositionRC;
         const camera = this.context.mainCamera;
         const cameraPosition = camera.worldPosition;
         // create ray from camera through cursor position
-        const rayDirection = getTempVector(cursor.x, cursor.y, 1).unproject(camera);
+        const rayDirection = getTempVector(x, y, 1).unproject(camera);
         rayDirection.sub(cameraPosition).normalize();
         // position object at initial distance along the ray
         const newPosition = rayDirection.multiplyScalar(this._distance).add(cameraPosition);
@@ -60,6 +91,9 @@ export class CursorFollow extends Behaviour {
 __decorate([
     serializable()
 ], CursorFollow.prototype, "damping", void 0);
+__decorate([
+    serializable()
+], CursorFollow.prototype, "useFullPage", void 0);
 __decorate([
     serializable()
 ], CursorFollow.prototype, "keepDistance", void 0);

package/lib/engine-components/web/CursorFollow.js.map

@@ -1 +1 @@
-{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,SAAS;IAEvC;;;OAGG;IAEH,OAAO,GAAW,CAAC,CAAC;IAEpB;;;OAGG;IAEH,YAAY,GAAY,IAAI,CAAC;IAE7B,KAAK;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC;IAEO,SAAS,GAAW,CAAC,CAAC,CAAC;IAE/B,cAAc;QACV,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE;YAC5C,OAAO;SACV;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACrG,CAAC;IAED,gBAAgB;IAChB,MAAM;QACF,8DAA8D;QAC9D,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,yEAAyE;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACvC,MAAM,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAE5C,iDAAiD;QACjD,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC5E,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,CAAC;QAE7C,oDAAoD;QACpD,MAAM,WAAW,GAAG,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACpF,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAClE,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,GAAG,CAAC;SACvC;aACI;YACD,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,WAAW,CAAC;SAC/C;IAEL,CAAC;CAEJ;AAjDG;IADC,YAAY,EAAE;6CACK;AAOpB;IADC,YAAY,EAAE;kDACc"}
+{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.10.4",
+  "version": "4.10.5-next.267a93d",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {
@@ -169,4 +169,4 @@
   "module": "lib/needle-engine.js",
   "typings": "lib/needle-engine.d.ts",
   "types": "lib/needle-engine.d.ts"
-}
+}

package/src/engine/debug/debug_overlay.ts

@@ -244,7 +244,7 @@ function getLogsContainer(domElement: HTMLElement): HTMLElement {
             padding-top: 0px;
             max-width: 70%;
             max-height: calc(100% - 5px);
-            z-index: 9999999999;
+            z-index: 100000;
             pointer-events: scroll;
             display: flex;
             align-items: end;

package/src/engine/engine_context.ts

@@ -1627,6 +1627,7 @@ export class Context implements IContext {
 			// but as a fallback we still register them (if e.g. there's no camera for compile async)
 			looputils.runPrewarm(this);
 			this._currentFrameEvent = FrameEvent.Undefined;
+			nodeFrame.camera = this.mainCamera as Camera | null;
 			nodeFrame.update();
 			this.renderNow();
 			this._currentFrameEvent = FrameEvent.OnAfterRender;

package/src/engine-components/Renderer.ts

@@ -359,7 +359,7 @@ export class Renderer extends Behaviour implements IRenderer {
     get sharedMaterials(): SharedMaterialArray {
 
         // @ts-ignore (original materials will be set during deserialization)
-        if(this._originalMaterials === undefined) return null;
+        if (this._originalMaterials === undefined) return null;
 
         // @ts-ignore during deserialization code might access this property *before* the setter and then create an empty array
         if (this.__isDeserializing === true) return null;
@@ -476,41 +476,43 @@ export class Renderer extends Behaviour implements IRenderer {
                 ? this._lightmapTextureOverride
                 : this.context.lightmaps.tryGetLightmap(this.sourceId, this.lightmapIndex);
             if (tex) {
-                if (!this._lightmaps)
-                    this._lightmaps = [];
-
-                if (type === "Mesh") {
-                    const mat = this.gameObject["material"];
-                    if (!mat?.isMeshBasicMaterial) {
-                        if (this._lightmaps.length <= 0) {
-                            const rm = new RendererLightmap(this.gameObject as any as Mesh, this.context);
-                            this._lightmaps.push(rm);
-                        }
-                        const rm = this._lightmaps[0];
-                        rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                    }
-                    else {
-                        if (mat)
-                            console.warn("Lightmapping is not supported on MeshBasicMaterial", mat.name)
-                    }
-                }
-                // for multi materials we need to loop through children 
-                // and then we add a lightmap renderer component to each of them
-                else if (this.isMultiMaterialObject(this.gameObject) && this.sharedMaterials.length > 0) {
-                    for (let i = 0; i < this.gameObject.children.length; i++) {
-                        const child = this.gameObject.children[i];
-                        if (!child["material"]?.isMeshBasicMaterial) {
-                            let rm: RendererLightmap | undefined = undefined;
-                            if (i >= this._lightmaps.length) {
-                                rm = new RendererLightmap(child as Mesh, this.context);
-                                this._lightmaps.push(rm);
-                            }
-                            else
-                                rm = this._lightmaps[i];
-                            rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                        }
-                    }
-                }
+                if (!this._lightmaps) this._lightmaps = [];
+
+
+                const rm = new RendererLightmap(this);
+                rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
+                this._lightmaps.push(rm);
+
+                // if (type === "Mesh") {
+                //     const mat = this.gameObject["material"];
+                //     if (!mat?.isMeshBasicMaterial) {
+                //         if (this._lightmaps.length <= 0) {
+                //         }
+                //         const rm = this._lightmaps[0];
+                //         rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
+                //     }
+                //     else {
+                //         if (mat)
+                //             console.warn("Lightmapping is not supported on MeshBasicMaterial", mat.name)
+                //     }
+                // }
+                // // for multi materials we need to loop through children 
+                // // and then we add a lightmap renderer component to each of them
+                // else if (this.isMultiMaterialObject(this.gameObject) && this.sharedMaterials.length > 0) {
+                //     for (let i = 0; i < this.gameObject.children.length; i++) {
+                //         const child = this.gameObject.children[i];
+                //         if (!child["material"]?.isMeshBasicMaterial) {
+                //             let rm: RendererLightmap | undefined = undefined;
+                //             if (i >= this._lightmaps.length) {
+                //                 rm = new RendererLightmap(child as Mesh, this.context);
+                //                 this._lightmaps.push(rm);
+                //             }
+                //             else
+                //                 rm = this._lightmaps[i];
+                //             rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
+                //         }
+                //     }
+                // }
             }
             else {
                 if (debugRenderer) console.warn("Lightmap not found", this.sourceId, this.lightmapIndex);
@@ -742,7 +744,6 @@ export class Renderer extends Behaviour implements IRenderer {
             const environmentIntensity = this.context.mainCameraComponent?.environmentIntensity ?? 1;
             material.envMapIntensity = Math.max(0, environmentIntensity * this.context.sceneLighting.environmentIntensity / factor);
         }
-
         if (this._lightmaps) {
             for (const lm of this._lightmaps) {
                 lm.updateLightmapUniforms(material);

package/src/engine-components/RendererLightmap.ts

@@ -3,6 +3,7 @@ import { Material, Mesh, MeshPhysicalMaterial, ShaderMaterial, Texture, Vector4,
 
 import type { Context } from "../engine/engine_setup.js";
 import { getParam } from "../engine/engine_utils.js";
+import { type Renderer } from "./Renderer.js";
 
 const debug = getParam("debuglightmaps");
 
@@ -31,15 +32,15 @@ export class RendererLightmap {
     private lightmapIndex: number = -1;
     private lightmapScaleOffset: Vector4 = new Vector4(1, 1, 0, 0);
 
-    private context: Context;
-    private gameObject: Mesh;
+    private readonly renderer: Renderer;
+    private get context(): Context { return this.renderer.context; }
+    private get gameObject() { return this.renderer.gameObject; }
     private lightmapTexture: Texture | null = null;
     private lightmapScaleOffsetUniform = { value: new Vector4(1, 1, 0, 0) };
     private lightmapUniform: { value: Texture | null } = { value: null };
 
-    constructor(gameObject: Mesh, context: Context) {
-        this.gameObject = gameObject;
-        this.context = context;
+    constructor(renderer: Renderer) {
+        this.renderer = renderer;
     }
 
     init(lightmapIndex: number, lightmapScaleOffset: Vector4, lightmapTexture: Texture) {
@@ -55,7 +56,7 @@ export class RendererLightmap {
             console.log("Lightmap:", this.gameObject.name, lightmapIndex, "\nScaleOffset:", lightmapScaleOffset, "\nTexture:", lightmapTexture)
             this.setLightmapDebugMaterial();
         }
-        else if(debug) console.log("Use debuglightmaps=show to render lightmaps only in the scene.")
+        else if (debug) console.log("Use debuglightmaps=show to render lightmaps only in the scene.")
         this.applyLightmap();
     }
 
@@ -88,32 +89,49 @@ export class RendererLightmap {
         console.assert(this.gameObject.type === "Mesh", "Lightmap only works on meshes", this);
 
         const mesh = this.gameObject as unknown as Mesh;
-        if (!mesh.geometry.getAttribute("uv1"))
+        if (!mesh.geometry.getAttribute("uv1")) {
             mesh.geometry.setAttribute("uv1", mesh.geometry.getAttribute("uv"));
+        }
+
+        for (let i = 0; i < this.renderer.sharedMaterials.length; i++) {
 
-        if (Array.isArray(this.gameObject.material)) {
-            const mats: Material[] = this.gameObject.material;
-            for (let i = 0; i < mats.length; i++) {
-                mats[i] = this.ensureLightmapMaterial(mats[i]);
+            const mat = this.renderer.sharedMaterials[i];
+            if (!mat) continue;
+
+            const newMat = this.ensureLightmapMaterial(mat);
+            if (mat !== newMat) {
+                this.renderer.sharedMaterials[i] = newMat;
             }
-        }
-        else {
-            this.gameObject.material = this.ensureLightmapMaterial(this.gameObject.material);
+
         }
 
+        // if (Array.isArray(this.gameObject.material)) {
+        //     const mats: Material[] = this.gameObject.material;
+        //     for (let i = 0; i < mats.length; i++) {
+        //         mats[i] = this.ensureLightmapMaterial(mats[i]);
+        //     }
+        // }
+        // else {
+        //     this.gameObject.material = this.ensureLightmapMaterial(this.gameObject.material);
+        // }
+
         if (this.lightmapIndex >= 0 && this.lightmapTexture) {
             // always on channel 1 for now. We could optimize this by passing the correct lightmap index along
             this.lightmapTexture.channel = 1;
-            const mat = this.gameObject.material;
-            if (Array.isArray(mat)) {
-                for (const entry of mat) {
-                    this.assignLightmapTexture(entry as any);
-
-                }
-            }
-            else if (mat) {
-                this.assignLightmapTexture(mat);
+            for (const mat of this.renderer.sharedMaterials) {
+                if (mat) this.assignLightmapTexture(mat);
             }
+
+            // const mat = this.gameObject.material;
+            // if (Array.isArray(mat)) {
+            //     for (const entry of mat) {
+            //         this.assignLightmapTexture(entry as any);
+
+            //     }
+            // }
+            // else if (mat) {
+            //     this.assignLightmapTexture(mat);
+            // }
         }
     }
 
@@ -127,7 +145,7 @@ export class RendererLightmap {
             if (material["NEEDLE:lightmap-material-version"] == undefined) {
                 if (debug) console.warn("Cloning material for lightmap " + material.name);
                 const mat: Material = material.clone();
-                if(!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
+                if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
                 material = mat;
                 material.onBeforeCompile = this.onBeforeCompile;
             }

package/src/engine-components/web/CursorFollow.ts

@@ -3,7 +3,10 @@ import { getTempVector } from "../../engine/engine_three_utils.js";
 import { Behaviour } from "../Component.js";
 
 /**
- * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * The CursorFollow component makes the object follow the cursor (or touch) position on screen.  
+ * 
+ * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
+ * 
  * @category Web
  * @group Components
  * @component
@@ -17,6 +20,13 @@ export class CursorFollow extends Behaviour {
     @serializable()
     damping: number = 0;
 
+    /**
+     * When enabled the object will follow the cursor even outside of the needle-engine canvas. This is useful for example for look at effects where you have a small needle-engine element on your page and you want the 3D object to keep looking at the cursor even when it's outside of the canvas.
+     * @default true
+     */
+    @serializable()
+    useFullPage: boolean = true;
+
     /**
      * If true, the initial distance to the camera is maintained when following the cursor.
      * @default true
@@ -24,31 +34,58 @@ export class CursorFollow extends Behaviour {
     @serializable()
     keepDistance: boolean = true;
 
+    
+    private _distance: number = -1;
+    updateDistance(force:boolean = false) {
+        if (!force && (this.keepDistance && this._distance !== -1)) {
+            return;
+        }
+        this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
+    }
+
+    /** @internal */
     awake() {
         this._distance = -1;
     }
 
-    private _distance: number = -1;
+    onEnable(): void {
+        this._distance = -1;
+        window.addEventListener('pointermove', this._onPointerMove);
+    }
+    onDisable(): void {
+        window.removeEventListener('pointermove', this._onPointerMove);
+    }
 
-    updateDistance() {
-        if (this.keepDistance && this._distance !== -1) {
-            return;
-        }
-        this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
+    private _ndc_x = 0;
+    private _ndc_y = 0;
+
+    private _onPointerMove = (e:PointerEvent) => {
+        if(!this.useFullPage) return;
+        const x = e.clientX;
+        const y = e.clientY;
+        const domx = this.context.domX;
+        const domy = this.context.domY;
+        const domw = this.context.domWidth;
+        const domh = this.context.domHeight;
+        this._ndc_x = (x - domx) / domw * 2 - 1;
+        this._ndc_y = - (y - domy) / domh * 2 + 1;
     }
 
+
     /** @internal */
     update() {
         // continuously update distance in case camera or object moves
         this.updateDistance();
 
+        const x = this.useFullPage ? this._ndc_x : this.context.input.mousePositionRC.x;
+        const y = this.useFullPage ? this._ndc_y : this.context.input.mousePositionRC.y;
+
         // follow cursor in screenspace but maintain initial distance from camera
-        const cursor = this.context.input.mousePositionRC;
         const camera = this.context.mainCamera;
         const cameraPosition = camera.worldPosition;
 
         // create ray from camera through cursor position
-        const rayDirection = getTempVector(cursor.x, cursor.y, 1).unproject(camera);
+        const rayDirection = getTempVector(x, y, 1).unproject(camera);
         rayDirection.sub(cameraPosition).normalize();
 
         // position object at initial distance along the ray