@needle-tools/engine 5.0.4 → 5.0.6

package/src/engine-components/NestedGltf.ts

@@ -9,9 +9,9 @@ import { EventList } from "./EventList.js";
 const debug = getParam("debugnestedgltf");
 
 /**
- * NestedGltf loads and instantiates a glTF file when the component starts.   
- * NestedGltf components are created by the Unity exporter when nesting Objects with the GltfObject component (in Unity).  
- * Use this for lazy-loading content, modular scene composition, or dynamic asset loading.  
+ * NestedGltf loads and instantiates a glTF file when the component starts.
+ * This enables splitting a scene into multiple `.glb` files that are loaded on demand,
+ * keeping initial load times small and allowing parts of a scene to be reused across different contexts.
  * 
  * ![](https://cloud.needle.tools/-/media/lJKrr_2tWlqRFdFc46U4bQ.gif)
  *
@@ -23,6 +23,23 @@ const debug = getParam("debugnestedgltf");
  * - Progress callbacks for loading UI
  * - Preloading support for faster display
  * - Event callback when loading completes
+ * 
+ * **Limitations:**
+ * - Loads only once; there is no public API to unload and reload content
+ * - Requires a parent object — does nothing if the GameObject has no parent
+ * - Not intended to be added from code. For loading glTF assets at runtime,
+ *   use {@link AssetReference.loadAsset} or {@link SceneSwitcher} instead
+ *
+ * **Unity Editor usage:**
+ * NestedGltf components are created automatically by the exporter when nesting GltfObject components:
+ * - A parent GameObject with a `GltfObject` component is exported as a `.glb` file
+ * - Any child GameObject that also has a `GltfObject` component is exported as a separate `.glb` file
+ * - The child's `GltfObject` is replaced with a `NestedGltf` reference pointing to that separate `.glb`
+ *
+ * ```
+ * Parent [GltfObject]       → exported as parent.glb
+ *   └─ Child [GltfObject]   → exported as child.glb, replaced with NestedGltf in parent.glb
+ * ```
  *
  * @example Load a glTF when object becomes active
  * ```ts
@@ -40,7 +57,6 @@ const debug = getParam("debugnestedgltf");
  * // Later, when object becomes active, it displays instantly
  * ```
  *
- * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
  * @see {@link AssetReference} for asset loading utilities

package/src/engine-components/Networking.ts

@@ -37,7 +37,7 @@ const debug = getParam("debugnet");
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
- * @summary Networking configuration
+ * @summary Configures the websocket server URL for multiplayer networking
  * @category Networking
  * @group Components
  */

package/src/engine-components/OrbitControls.ts

@@ -758,19 +758,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (this.targetBounds) {
             // #region target bounds
-            const targetVector = this._controls.target;
             const boundsCenter = this.targetBounds.worldPosition;
             const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
             const min = getTempVector(boundsCenter).sub(boundsHalfSize);
             const max = getTempVector(boundsCenter).add(boundsHalfSize);
-            const newTarget = getTempVector(this._controls.target).clamp(min, max);
-            const duration = .1;
-            if (duration <= 0) targetVector.copy(newTarget);
-            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+
             if (this._lookTargetLerpActive) {
-                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
-                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+                // During a programmatic transition (fitCamera / setLookTargetPosition with immediate: false),
+                // only clamp the destination. The look-target lerp (above) handles moving _controls.target
+                // towards the endpoint — we must not fight it by also lerping _controls.target here.
+                this._lookTargetEndPosition.clamp(min, max);
+            }
+            else {
+                // Interactive use (pan/orbit): smoothly push the target back into bounds
+                const targetVector = this._controls.target;
+                const newTarget = getTempVector(targetVector).clamp(min, max);
+                const duration = .1;
+                if (duration <= 0) targetVector.copy(newTarget);
+                else targetVector.lerp(newTarget, Math.min(1, this.context.time.deltaTime / duration));
             }
+
             if (debug) {
                 Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
             }
@@ -847,7 +854,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
-                    Gizmos.DrawWireSphere(this._controls.target, 0.1, 0x00ff00);
+                    const distance = this._controls.getDistance();
+                    Gizmos.DrawWireSphere(this._controls.target, 0.01 * distance, 0x00ff00);
                 }
             }
         }
@@ -1022,7 +1030,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (debug) {
             console.warn("OrbitControls: setLookTargetPosition", position, immediateOrDuration);
-            Gizmos.DrawWireSphere(this._lookTargetEndPosition, .2, 0xff0000, 2);
+            const distance = this._controls.getDistance();
+            Gizmos.DrawWireSphere(this._lookTargetEndPosition, 0.01 * distance, 0xff5500, 2);
         }
 
         if (immediateOrDuration === true) {

package/src/engine-components/postprocessing/VolumeParameter.ts

@@ -156,4 +156,7 @@ class VolumeParameterSerializer extends TypeSerializer {
         return parameter;
     }
 }
-new VolumeParameterSerializer();
+/** @internal */
+export function initVolumeParameterSerializer() {
+    new VolumeParameterSerializer();
+}

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

@@ -4,7 +4,7 @@ import * as ThreeMeshUI from 'three-mesh-ui'
 import { Mathf } from "../../engine/engine_math.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { FrameEvent } from "../../engine/engine_setup.js";
-import { delayForFrames, getParam } from "../../engine/engine_utils.js";
+import { getParam } from "../../engine/engine_utils.js";
 import { type NeedleXREventArgs } from "../../engine/xr/api.js";
 import { Camera } from "../Camera.js";
 import { GameObject } from "../Component.js";
@@ -236,19 +236,13 @@ export class Canvas extends UIRootComponent implements ICanvas {
         }
     }
 
-    async onEnterXR(args: NeedleXREventArgs) {
+    onEnterXR(args: NeedleXREventArgs) {
         // workaround for https://linear.app/needle/issue/NE-4114
         if (this.screenspace) {
             if (args.xr.isVR || args.xr.isPassThrough) {
                 this.gameObject.visible = false;
             }
         }
-        else {
-            this.gameObject.visible = false;
-            await delayForFrames(1).then(()=>{
-                this.gameObject.visible = true;
-            });
-        }
     }
     onLeaveXR(args: NeedleXREventArgs): void {
         if (this.screenspace) {

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

@@ -81,7 +81,24 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
     @serializable()
     supportRichText: boolean = false;
     @serializable(URL)
-    font?: string;
+    set font(val: string | null) {
+        if (val !== this._font) {
+            this._font = val;
+            // If the font is assigned during deserialization it means the font URL MUST be resolved with the style suffix. If it's assigned at runtime by a user invocation and is absolute then we assume the user is prividing a full path to the font asset json or png
+            this._assignedAtRuntime = this.__didAwake;
+        }
+    }
+    get font(): string | null {
+        return this._font;
+    }
+    private _font: string | null = null;
+    private _assignedAtRuntime: boolean = true;
+
+
+    /**
+     * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
+     * @default false
+     */
     @serializable()
     fontStyle: FontStyle = FontStyle.Normal;
 
@@ -224,8 +241,15 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         //     fontSize /= this.canvas?.scaleFactor;
         // }
 
-
-        const textOpts = {
+        const textOpts: {
+            color: Color,
+            fontOpacity: number,
+            fontSize: number,
+            fontKerning: string,
+            whiteSpace?: string,
+            overflow?: string,
+            lineHeight?: number
+        } = {
             color: this.color,
             fontOpacity: this.color.alpha,
             fontSize: fontSize,
@@ -486,15 +510,16 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
      * @private
      */
     private setFont(opts: ThreeMeshUIEveryOptions, fontStyle: FontStyle) {
+        
+        if (!this.font) {
+            if(debug) console.warn("No font set for Text component, skipping font setup");
+            return;
+        }
 
-        // @TODO : THH could be useful to uniformize font family name :
-        //         This would ease possible html/vr matching
-        //              -   Arial instead of assets/arial
-        //              -   Arial should stay Arial instead of arial
-        if (!this.font) return;
         const fontName = this.font;
         const familyName = this.getFamilyNameWithCorrectSuffix(fontName, fontStyle);
-        if (debug) console.log("Selected font family:" + familyName);
+
+        if (debug) console.log("Selected font family:" + familyName, this.font);
 
         // ensure a font family is register under this name
         let fontFamily = ThreeMeshUI.FontLibrary.getFontFamily(familyName as string);
@@ -527,9 +552,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
                 opts.fontWeight = 400;
         }
 
-
         // Ensure a fontVariant is registered
-        //@TODO: @swingingtom add type for fontWeight
         let fontVariant = fontFamily.getVariant(opts.fontWeight as any as string, opts.fontStyle);
         if (!fontVariant) {
             let jsonPath = familyName;
@@ -550,13 +573,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
 
     private getFamilyNameWithCorrectSuffix(familyName: string, style: FontStyle): string {
 
-
-        // the URL decorator resolves the URL to absolute URLs - we need to remove the domain part since we're only interested in the path
-        if (familyName.startsWith("https:") || familyName.startsWith("http:")) {
-            const url = new URL(familyName);
-            familyName = url.pathname;
-        }
-
+        const isAbsolute = familyName.startsWith("https:") || familyName.startsWith("http:");
 
         // we can only change the style for the family if the name has a suffix (e.g. Arial-Bold)
         const styleSeparator = familyName.lastIndexOf('-');
@@ -580,8 +597,16 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         }
         const isUpperCase = fontBaseName[0] === fontBaseName[0].toUpperCase();
         const fontNameWithoutSuffix = familyName.substring(0, styleSeparator > pathSeparatorIndex ? styleSeparator : familyName.length);
+
         if (debug) console.log("Select font: ", familyName, FontStyle[style], fontBaseName, isUpperCase, fontNameWithoutSuffix);
 
+        /**
+         * If a user provides a font with an absolute URL AND the font name does not end with "-msdf.json" or ".png" (e.g. "https://example.com/fonts/Arial-Bold"), we will assume that the user is providing the full path to the font files and we will not try to modify the font name based on the style. This allows users to have more control over the font files they are using, especially if they are hosting their own fonts or using a custom font provider that does not follow the same naming conventions as our default fonts.
+         */
+        if (isAbsolute && this._assignedAtRuntime && !(familyName.endsWith("-msdf.json") || familyName.endsWith(".png"))) {
+            return fontNameWithoutSuffix;
+        }
+
         switch (style) {
             case FontStyle.Normal:
                 if (isUpperCase) return fontNameWithoutSuffix + "-Regular";

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

@@ -289,20 +289,28 @@ export class CursorFollow extends Behaviour {
 
 
         if (this.snapToSurface) {
-            ray.origin = _position;
-            ray.direction = rayDirection.multiplyScalar(-1);
-            const hits = this.context.physics.raycastFromRay(ray);
-            if (hits?.length) {
-                const hit = hits[0];
-                if (this.damping > 0) {
-                    this.gameObject.worldPosition = _position.lerp(hit.point, this.context.time.deltaTime / this.damping);
-                }
-                else {
-                    this.gameObject.worldPosition = hit.point;
+            ray.origin = cameraPosition;
+            ray.direction = rayDirection;
+            const hits = this.context.physics.raycastFromRay(ray, {
+                testObject: obj => {
+                    return obj !== this.gameObject && !this.gameObject.contains(obj) ? true : false
                 }
-
-                if(debug) {
-                    Gizmos.DrawLine(hit.point, hit.normal!.add(hit.point), 0x00FF00);
+            });
+            if (hits?.length) {
+                // Get the first hit that is not a child of *this* object. Because we do not want to lerp to a surface that is part of the object itself, since that would result in *this* object moving closer and closer to the camera as it tries to snap to itself
+                const hit = hits[0];//.find(h => !this.gameObject.contains(h.object));
+                if (hit) {
+                    if (this.damping > 0) {
+                        this.gameObject.worldPosition = _position.lerp(hit.point, this.context.time.deltaTime / this.damping);
+                        // this._distance = this.gameObject.worldPosition.distanceTo(cameraPosition);
+                    }
+                    else {
+                        this.gameObject.worldPosition = hit.point;
+                        // this._distance = hit.point.distanceTo(cameraPosition);
+                    }
+                    if (debug) {
+                        Gizmos.DrawLine(hit.point, hit.normal!.add(hit.point), 0x00FF00);
+                    }
                 }
             }
         }

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -886,9 +886,11 @@ async function loadImage(url: string) {
     }
     const promise = new Promise<boolean>(res => {
         _imageElements.set(url, null);
+        if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Start loading image for tracking: ${url}`);
         const imageElement = document.createElement("img") as HTMLImageElement;
         imageElement.src = url;
         imageElement.addEventListener("load", async () => {
+            if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Loaded image for tracking: ${url}`);
             const img = await createImageBitmap(imageElement);
             _imageElements.set(url, img);
             res(true);