@needle-tools/engine 4.11.2 → 4.11.3-next.35d1b4d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.11.2",
+  "version": "4.11.3-next.35d1b4d",
   "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/engine_utils.ts

@@ -4,9 +4,11 @@ import { Quaternion, Vector2, Vector3, Vector4 } from "three";
 declare type Vector = Vector2 | Vector3 | Vector4 | Quaternion;
 
 import { needleLogoOnlySVG } from "./assets/index.js";
+import { isDevEnvironment } from "./debug/debug.js";
 import type { Context } from "./engine_context.js";
 import { ContextRegistry } from "./engine_context_registry.js";
 import { type SourceIdentifier } from "./engine_types.js";
+import { InternalAttributeUtils } from "./engine_utils_attributes.js";
 import type { NeedleEngineWebComponent } from "./webcomponents/needle-engine.js";
 
 // https://schneidenbach.gitbooks.io/typescript-cookbook/content/nameof-operator.html
@@ -908,7 +910,7 @@ export async function PromiseAllWithErrors<T>(promise: Promise<T>[]): Promise<{
  * @param args.colorDark The color of the dark squares
  * @param args.colorLight The color of the light squares
  * @param args.correctLevel The error correction level to use
- * @param args.showLogo If true, the same logo as for the Needle loading screen will be drawn in the center of the QR code
+ * @param args.showLogo If true, the logo will be shown in the center of the QR code. By default the Needle Logo will be used. You can override which logo is being used by setting the `needle-engine` web component's `qr-logo-src` attribute. The logo can also be disabled by setting that attribute to a falsey value (e.g. "0" or "false")
  * @param args.showUrl If true, the URL will be shown below the QR code
  * @param args.domElement The dom element to append the QR code to. If not provided a new div will be created and returned
  * @returns The dom element containing the QR code
@@ -946,16 +948,16 @@ export async function generateQRCode(args: { domElement?: HTMLElement, text: str
     // Number of rows/columns of the generated QR code
     const moduleCount = qrCode?._oQRCode.moduleCount || 0;
     const canvas = qrCode?._oDrawing?._elCanvas as HTMLCanvasElement;
-    
+
     let sizePercentage = 0.25;
     if (moduleCount < 40)
         sizePercentage = Math.floor(moduleCount / 4) / moduleCount;
     else
         sizePercentage = Math.floor(moduleCount / 6) / moduleCount;
-    
+
     const paddingPercentage = Math.floor(moduleCount / 20) / moduleCount;
     try {
-        const img = await addOverlays(canvas, { showLogo: args.showLogo, logoSize: sizePercentage, logoPadding: paddingPercentage }).catch(_e => { /** ignore */ });
+        const img = await internalRenderQRCodeOverlays(canvas, { showLogo: args.showLogo, logoSize: sizePercentage, logoPadding: paddingPercentage }).catch(_e => { /** ignore */ });
         if (img) {
             target.innerHTML = "";
             target.append(img);
@@ -1002,7 +1004,8 @@ export async function generateQRCode(args: { domElement?: HTMLElement, text: str
     return target;
 }
 
-async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean, logoSize?: number, logoPadding?: number }): Promise<HTMLImageElement | void> {
+
+async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean, logoSize?: number, logoPadding?: number }): Promise<HTMLImageElement | void> {
     if (!canvas) return;
 
     // Internal settings
@@ -1019,18 +1022,38 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
     const rectangleRadius = 0;
 
     // Draw the website's icon in the center of the QR code
-    const faviconImage = new Image();
+    const image = new Image();
     const element = document.querySelector("needle-engine") as NeedleEngineWebComponent;
-    const logoSrc = element?.getAttribute("loading-logo-src") || needleLogoOnlySVG;
+    if (!element) {
+        console.debug("[QR Code] No web component found")
+    }
+
+    // Query logo src from needle-engine attribute.
+    // For any supported attribute it's possible to use "falsey" values (e.g. "0" or "false" to disable the logo in the QR code)
+    let logoSrc: false | string | null = null;
+    logoSrc = InternalAttributeUtils.getAttributeAndCheckFalsey(element, "qrcode-logo-src");
+    if (args.showLogo !== true && logoSrc === false) return; // Explictly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "logo-src");
+    if (args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "loading-logo-src", {
+        onAttribute: () => {
+            if (isDevEnvironment()) console.warn("[QR Code] 'loading-logo-src' is deprecated, please use 'logo-src' or 'qrcode-logo-src' instead.");
+            else console.debug("[QR Code] 'loading-logo-src' is deprecated.");
+        }
+    });
+    if (args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+
+    logoSrc ||= needleLogoOnlySVG;
     if (!logoSrc) return;
 
     let haveLogo = false;
     if (args.showLogo !== false) {
-        faviconImage.src = logoSrc;
+        image.src = logoSrc;
         haveLogo = await new Promise((resolve, _reject) => {
-            faviconImage.onload = () => resolve(true);
-            faviconImage.onerror = (err) => {
-                console.error("Error loading favicon image for QR code", err);
+            image.onload = () => resolve(true);
+            image.onerror = (err) => {
+                let errorUrl = logoSrc !== needleLogoOnlySVG ? "'" + logoSrc + "'" : null;
+                console.error("[QR Code] Error loading logo image for QR code", errorUrl, isDevEnvironment() ? err : "");
                 resolve(false);
             };
         });
@@ -1073,7 +1096,7 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
 
     if (haveLogo) {
         // Get aspect of image
-        const aspect = faviconImage.width / faviconImage.height;
+        const aspect = image.width / image.height;
         if (aspect > 1) sizeY = sizeX / aspect;
         else sizeX = sizeY * aspect;
 
@@ -1114,7 +1137,7 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
         paddedContext.shadowColor = "transparent";
         const logoX = (paddedCanvas.width - sizeX) / 2;
         const logoY = (paddedCanvas.height - sizeY) / 2;
-        paddedContext.drawImage(faviconImage, logoX, logoY, sizeX, sizeY);
+        paddedContext.drawImage(image, logoX, logoY, sizeX, sizeY);
     }
 
     // Replace the canvas with the padded one
@@ -1125,4 +1148,5 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
     img.style.height = "auto";
 
     return img;
-}
+}
+

package/src/engine/engine_utils_attributes.ts

@@ -0,0 +1,72 @@
+
+
+/**
+ * @internal
+ */
+export namespace InternalAttributeUtils {
+
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    export function isFalsey(value: string | null): boolean {
+        return value === "0" || value?.toLowerCase() === "false";
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    export function getAttributeValueIfNotFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string) => void }): string | null {
+        const attrValue = element.getAttribute(attributeName);
+        if (isFalsey(attrValue)) {
+            return null;
+        }
+        opts?.onAttribute?.call(null, attrValue!);
+        return attrValue;
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     * 
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     * 
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    export function getAttributeAndCheckFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string, falsey:boolean) => void }): false | string | null {
+        const attrValue = element.getAttribute(attributeName);
+        // If the attribute is not set at all we just return
+        if(attrValue === null) {
+            return null;
+        }
+        if (isFalsey(attrValue)) {
+            opts?.onAttribute?.call(null, attrValue!, true);
+            return false;
+        }
+        opts?.onAttribute?.call(null, attrValue!, false);
+        return attrValue;
+    }
+
+}
+

package/src/engine-components/Animation.ts

@@ -58,7 +58,7 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject
+ * Animation component to play animations on a GameObject.
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/AnimationCurve.ts

@@ -27,7 +27,10 @@ export class Keyframe {
 }
 
 /**
- * AnimationCurve is a representation of a curve that can be used to animate values over time.  
+ * AnimationCurve is a representation of a curve that can be used to animate values over time. 
+ * 
+ * @category Animation
+ * @group Utilities 
  */
 export class AnimationCurve {
 

package/src/engine-components/Animator.ts

@@ -39,8 +39,9 @@ export declare class PlayOptions {
 
 /** 
  * The Animator component plays and manages animations on a GameObject. 
- * It works with an AnimatorController to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
+ * It works with an {@link AnimatorController} to handle state transitions and animation blending.
+ * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+ * 
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AnimatorController.ts

@@ -51,6 +51,9 @@ declare type CreateAnimatorControllerOptions = {
  * 
  * Use the static method {@link AnimatorController.createFromClips} to create
  * an animator controller from a set of animation clips.
+ * 
+ * @category Animation and Sequencing
+ * @group Utilities
  */
 export class AnimatorController {
 

package/src/engine-components/LookAtConstraint.ts

@@ -2,9 +2,14 @@ import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
+import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
+ * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
+ * This component is used by {@link OrbitControls} internally.
+ * 
+ * @category Camera Controls
+ * @group Components
  */
 export class LookAtConstraint extends Behaviour {
 

package/src/engine-components/NeedleMenu.ts

@@ -9,6 +9,7 @@ import { Behaviour } from './Component.js';
  * 
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
+ * 
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -10,6 +10,9 @@ const debug = getParam("debugnestedgltf");
 
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+ * 
+ * @category Asset Management
+ * @group Components
  */
 export class NestedGltf extends Behaviour {
 

package/src/engine-components/ReflectionProbe.ts

@@ -15,6 +15,10 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 const $originalMaterial = Symbol("original material");
 
 /**
+ * A ReflectionProbe provides reflection data to materials within its defined area.
+ * 
+ * - Sample: http://samples.needle.tools/reflection-probes
+ * 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/RendererLightmap.ts

@@ -9,9 +9,13 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
-// this component is automatically added by the Renderer if the object has lightmap uvs AND we have a lightmap
-// for multimaterial objects GLTF exports a "Group" with the renderer component
-// and every child mesh is a material from unity
+
+/**
+ * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
+ * 
+ * @category Rendering
+ * @group Components
+ */
 export class RendererLightmap {
 
     get lightmap(): Texture | null {

package/src/engine-components/SeeThrough.ts

@@ -39,6 +39,9 @@ let i = 0;
  * Requires a Renderer component on the same object or a child object.
  * 
  * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class SeeThrough extends Behaviour {
 
@@ -241,6 +244,7 @@ export class SeeThrough extends Behaviour {
 
                 const wasTransparent = mat.transparent;
                 const wasAlphaHash = mat.alphaHash;
+                const previousOpacity = mat.opacity;
 
                 mat.alphaHash = this.useAlphaHash;
 
@@ -253,7 +257,10 @@ export class SeeThrough extends Behaviour {
                     mat.transparent = mat.opacity >= 1 ? false : !this.useAlphaHash;
                 }
 
-                if (wasTransparent != mat.transparent || wasAlphaHash != mat.alphaHash) {
+                if (wasTransparent !== mat.transparent 
+                    || wasAlphaHash !== mat.alphaHash 
+                    || mat.opacity !== previousOpacity // MeshPhysicsMaterial needs that and maybe other materials too...
+                ) {
                     mat.needsUpdate = true;
                 }
             }

package/src/engine-components/Skybox.ts

@@ -120,6 +120,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/SpriteRenderer.ts

@@ -9,6 +9,9 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugspriterenderer");
 const showWireframe = getParam("wireframe");
 
+/**
+ * @internal
+ */
 class SpriteUtils {
 
     static cache: { [key: string]: BufferGeometry } = {};
@@ -82,7 +85,7 @@ function updateTextureIfNecessary(tex: Texture) {
 }
 
 /**
- * A sprite is a mesh that represents a 2D image
+ * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
  * @category Rendering
  * @group Components
  */
@@ -152,6 +155,9 @@ export class Sprite {
 
 const $spriteTexOwner = Symbol("spriteOwner");
 
+/**
+ * @category Sprites
+ */
 export class SpriteSheet {
 
     @serializable(Sprite)
@@ -162,6 +168,11 @@ export class SpriteSheet {
     }
 }
 
+/**
+ * Used by the {@link SpriteRenderer} to hold the sprite sheet and the currently active sprite index.
+ * 
+ * @category Sprites
+ */
 export class SpriteData {
 
     static create() {
@@ -246,7 +257,12 @@ export class SpriteData {
 }
 
 /**
- * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).  
+ * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).   
+ * 
+ * - Example: https://engine.needle.tools/samples/spritesheet-animation
+ * 
+ * @category Sprites
+ * @group Components
  */
 export class SpriteRenderer extends Behaviour {
 

package/src/engine-components/export/usdz/ThreeUSDZExporter.ts

@@ -42,9 +42,9 @@ import { Progress } from '../../../engine/engine_time_utils.js';
 // import { BehaviorExtension } from '../../api.js';
 import type { IUSDExporterExtension } from './Extension.js';
 import type { AnimationExtension } from './extensions/Animation.js';
+import { BehaviorExtension } from './extensions/behavior/Behaviour.js';
 import type { PhysicsExtension } from './extensions/behavior/PhysicsExtension.js';
 import {buildNodeMaterial} from './extensions/NodeMaterialConverter.js';
-import { BehaviorExtension } from './extensions/behavior/Behaviour.js';
 
 type MeshPhysicalNodeMaterial = import("three/src/materials/nodes/MeshPhysicalNodeMaterial.js").default;
 

package/src/engine-components/splines/Spline.ts

@@ -36,6 +36,9 @@ export class SplineData {
  * The spline is defined by an array of knots (SplineData) which define position, rotation and tangents.  
  * 
  * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineContainer extends Behaviour {
 

package/src/engine-components/splines/SplineUtils.ts

@@ -3,7 +3,9 @@ import { Vector3 } from "three";
 import { Mathf } from "../../engine/engine_math.js";
 import { SplineContainer, SplineData } from "./Spline.js";
 
-
+/**
+ * @category Splines
+ */
 export namespace SplineUtils {
 
     /**

package/src/engine-components/splines/SplineWalker.ts

@@ -11,6 +11,9 @@ import { SplineContainer } from "./Spline.js";
  * Use this with a SplineContainer component.
  * 
  * - Example http://samples.needle.tools/splines
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineWalker extends Behaviour {
 

package/src/engine-components/timeline/SignalAsset.ts

@@ -2,15 +2,23 @@ import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
+import type { PlayableDirector } from "./PlayableDirector.js";
 
 const debug = getParam("debugsignals")
 
 
+/**
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ */
 export class SignalAsset {
     @serializable()
     guid!: string;
 }
 
+/**
+ * An event that links a signal to a reaction.
+ * Used internally by {@link SignalReceiver}.
+ */
 export class SignalReceiverEvent {
     @serializable(SignalAsset)
     signal!: SignalAsset;
@@ -19,7 +27,10 @@ export class SignalReceiverEvent {
 }
 
 /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. 
- * Signals can be added to a signal track on a timeline
+ * Signals can be added to a signal track on a {@link PlayableDirector}
+ * 
+ * @category Sequencing and Timelines
+ * @group Components
  */
 export class SignalReceiver extends Behaviour {
 
@@ -41,7 +52,7 @@ export class SignalReceiver extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if(debug) console.log("SignalReceiver awake", this);
+        if (debug) console.log("SignalReceiver awake", this);
     }
 
     /** @internal */

package/src/engine-components/ui/Raycaster.ts

@@ -28,6 +28,12 @@ export abstract class Raycaster extends Behaviour {
 }
 
 
+/**
+ * A Raycaster that performs raycasting against its own GameObject.  
+ * 
+ * @category Interaction
+ * @group Components
+ */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
     private raycastHits: Intersection[] = [];
@@ -65,6 +71,13 @@ export class ObjectRaycaster extends Raycaster {
     }
 }
 
+
+/**
+ * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
+ * 
+ * @category UI
+ * @group Components
+ */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
     // ignoreReversedGraphics: boolean = false;
@@ -76,6 +89,12 @@ export class GraphicRaycaster extends ObjectRaycaster {
     }
 }
 
+/**
+ * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
+ * 
+ * @category XR
+ * @group Components
+ */
 export class SpatialGrabRaycaster extends Raycaster {
 
     /**