@needle-tools/engine 4.11.0-next.91b9cf1 → 4.11.0-next.cc37c71

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

@@ -284,7 +284,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         return opts;
     }
 
-    private feedText(text: string, richText: boolean) : void {
+    private feedText(text: string, richText: boolean): void {
         // if (!text || text.length <= 0) return;
         // if (!text ) return;
         if (debug) console.log("feedText", this.uiObject, text, richText);
@@ -511,6 +511,15 @@ 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;
+        }
+
+
         // we can only change the style for the family if the name has a suffix (e.g. Arial-Bold)
         const styleSeparator = familyName.lastIndexOf('-');
         if (styleSeparator < 0) return familyName;
@@ -532,7 +541,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
             fontBaseName = fontBaseName.substring(pathSeparatorIndex + 1);
         }
         const isUpperCase = fontBaseName[0] === fontBaseName[0].toUpperCase();
-        const fontNameWithoutSuffix = familyName.substring(0, styleSeparator);
+        const fontNameWithoutSuffix = familyName.substring(0, styleSeparator > pathSeparatorIndex ? styleSeparator : familyName.length);
         if (debug) console.log("Select font: ", familyName, FontStyle[style], fontBaseName, isUpperCase, fontNameWithoutSuffix);
 
         switch (style) {

package/src/engine-components/utils/LookAt.ts

@@ -11,6 +11,9 @@ import { Behaviour } from "../Component.js";
 /**
  * LookAt behaviour makes the object look at a target object or the camera.  
  * It can also invert the forward direction and keep the up direction.
+ * 
+ * @category Interactivity, Everywhere Actions
+ * @group Components
  */
 export class LookAt extends Behaviour implements UsdzBehaviour {
 

package/src/engine-components/utils/OpenURL.ts

@@ -15,8 +15,9 @@ export enum OpenURLMode {
     NewWindow = 2
 }
 
-/**
- * OpenURL behaviour opens a URL in a new tab or window.
+/** 
+ * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
+ * 
  * @category Interactivity
  * @group Components
  */

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

@@ -1,3 +1,4 @@
+import { Vector2 } from "three";
 import { NEPointerEvent } from "../../engine/engine_input.js";
 import { onStart } from "../../engine/engine_lifecycle_api.js";
 import { addAttributeChangeCallback } from "../../engine/engine_utils.js";
@@ -45,12 +46,14 @@ export class ClickThrough extends Behaviour {
         this.context.input.addEventListener('pointermove', this.onPointerEvent, {
             queue: 100,
         });
+        window.addEventListener("touchstart", this.onTouchStart, { passive: true });
         window.addEventListener("touchend", this.onTouchEnd, { passive: true });
         this._previousPointerEvents = this.context.domElement.style.pointerEvents;
     }
     onDisable() {
         this.context.input.removeEventListener('pointerdown', this.onPointerEvent);
         this.context.input.removeEventListener('pointermove', this.onPointerEvent);
+        window.removeEventListener("touchstart", this.onTouchStart);
         window.removeEventListener("touchend", this.onTouchEnd);
         this.context.domElement.style.pointerEvents = this._previousPointerEvents;
     }
@@ -69,9 +72,33 @@ export class ClickThrough extends Behaviour {
         }
     };
 
+
+
+    // #region Touch hack
+
+    private _touchDidHitAnything = false;
+    
+    private onTouchStart = (_evt: TouchEvent) => {
+
+        const touch = _evt.touches[0];
+        if (!touch) return;
+
+        const ndx = touch.clientX / window.innerWidth * 2 - 1;
+        const ndy = -(touch.clientY / window.innerHeight) * 2 + 1;
+        // console.log(ndx, ndy);
+        const hits = this.context.physics.raycast({
+            screenPoint: new Vector2(ndx, ndy),
+        })
+        if (hits.length > 0) {
+            this._touchDidHitAnything = true;
+        }
+    }
+
     private onTouchEnd = (_evt: TouchEvent) => {
+        const _didHit = this._touchDidHitAnything;
+        this._touchDidHitAnything = false;
         setTimeout(() => {
-            this.context.domElement.style.pointerEvents = 'all';
+            if (_didHit) this.context.domElement.style.pointerEvents = 'all';
         }, 100);
     }
 }

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

@@ -96,6 +96,7 @@ export class ScrollFollow extends Behaviour {
     @serializable()
     invert: boolean = false;
 
+
     /** 
      * **Experimental - might change in future updates**  
      * If set, the scroll position will be read from the specified element instead of the window.  
@@ -106,7 +107,7 @@ export class ScrollFollow extends Behaviour {
     htmlSelector: string | null = null;
 
     @serializable()
-    private mode: "window" = "window";
+    mode: "window" = "window";
 
     /**
      * Event fired when the scroll position changes
@@ -126,11 +127,6 @@ export class ScrollFollow extends Behaviour {
     private _appliedValue: number = -1;
 
 
-    private _scrollStart: number = 0;
-    private _scrollEnd: number = 0;
-    private _scrollValue: number = 0;
-    private _scrollContainerHeight: number = 0;
-
     /** @internal */
     onEnable() {
         window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
@@ -159,8 +155,7 @@ export class ScrollFollow extends Behaviour {
             }
         }
 
-        // if (this._current_value !== this._appliedValue) 
-        {
+        if (this._current_value !== this._appliedValue) {
             this._appliedValue = this._current_value;
 
             let defaultPrevented = false;
@@ -182,9 +177,6 @@ export class ScrollFollow extends Behaviour {
 
                 const value = this.invert ? 1 - this._current_value : this._current_value;
 
-                // const height = this._rangeEndValue - this._rangeStartValue;
-                // const pixelValue = this._rangeStartValue + value * height;
-
                 // apply scroll to target(s)
                 if (Array.isArray(this.target)) {
                     this.target.forEach(t => t && this.applyScroll(t, value));
@@ -202,16 +194,11 @@ export class ScrollFollow extends Behaviour {
 
     private _lastSelectorValue: string | null = null;
     private _lastSelectorElement: Element | null = null;
-    /** Top y */
-    private _rangeStartValue: number = 0;
-    /** Bottom y */
-    private _rangeEndValue: number = 0;
 
     private updateCurrentScrollValue = () => {
 
         switch (this.mode) {
             case "window":
-
                 if (this.htmlSelector?.length) {
                     if (this.htmlSelector !== this._lastSelectorValue) {
                         this._lastSelectorElement = document.querySelector(this.htmlSelector);
@@ -219,26 +206,20 @@ export class ScrollFollow extends Behaviour {
                     }
                     if (this._lastSelectorElement) {
                         const rect = this._lastSelectorElement.getBoundingClientRect();
-
-                        this._scrollStart = rect.top + window.scrollY;
-                        this._scrollEnd = rect.height - window.innerHeight;
-                        this._scrollValue = -rect.top;
                         this._target_value = -rect.top / (rect.height - window.innerHeight);
-                        this._rangeStartValue = rect.top + window.scrollY;
-                        this._rangeEndValue = this._rangeStartValue + rect.height - window.innerHeight;
-                        this._scrollContainerHeight = rect.height;
                         break;
                     }
                 }
                 else {
-                    this._scrollStart = 0;
-                    this._scrollEnd = window.document.body.scrollHeight - window.innerHeight;
-                    this._scrollValue = window.scrollY;
-                    this._target_value = this._scrollValue / (this._scrollEnd || 1);
-                    this._rangeStartValue = 0;
-                    this._rangeEndValue = document.body.scrollHeight;
-                    this._scrollContainerHeight = window.innerHeight;
+                    if (window.document.body.scrollHeight <= window.innerHeight) {
+                        // If the page is not scrollable we can still increment the scroll value to allow triggering timelines etc.
+                    }
+                    else {
+                        const diff = window.document.body.scrollHeight - window.innerHeight;
+                        this._target_value = window.scrollY / (diff || 1);
+                    }
                 }
+
                 break;
         }
 
@@ -272,11 +253,12 @@ export class ScrollFollow extends Behaviour {
             target.intensity = value;
         }
         else if (target instanceof Object3D) {
+            const t = target as any;
             // When objects are assigned they're expected to move vertically based on scroll
-            if (target["needle:scrollbounds"] === undefined) {
-                target["needle:scrollbounds"] = getBoundingBox(target) || null;
+            if (t["needle:scrollbounds"] === undefined) {
+                t["needle:scrollbounds"] = getBoundingBox(target) || null;
             }
-            const bounds = target["needle:scrollbounds"] as Box3;
+            const bounds = t["needle:scrollbounds"] as Box3;
             if (bounds) {
                 // TODO: remap position to use upper screen edge and lower edge instead of center
                 target.position.y = -bounds.min.y - value * (bounds.max.y - bounds.min.y);
@@ -473,7 +455,7 @@ function tryGetElementsForSelector(index: number): Element | null {
 
     if (!needsScrollMarkerRefresh) {
         const element = needleScrollMarkerCache[index] || null;
-        if (element) return element;
+        return element;
     }
     needsScrollMarkerRefresh = false;
     needleScrollMarkerCache.length = 0;

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

@@ -1,4 +1,4 @@
-import { Camera, Matrix4, PerspectiveCamera, Quaternion, Scene, Vector2, Vector3 } from "three";
+import { Camera, Matrix4, PerspectiveCamera, Vector3 } from "three";
 
 import { isDevEnvironment } from "../../engine/debug/debug.js";
 import { Gizmos } from "../../engine/engine_gizmos.js";
@@ -13,6 +13,8 @@ import { Behaviour } from "../Component.js";
 const debugParam = getParam("debugviewbox");
 const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
 
+export type ViewBoxMode = "continuous" | "once";
+
 /**
  * This component can be used to automatically fit a certain box area into the camera view - no matter your screen size or aspect ratio.  
  * This is useful for example to frame a character or object in the center of the screen and ensure it is always fully visible. You can also animate or scale the viewbox to create zoom or framing effects.
@@ -36,6 +38,9 @@ const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
 @registerType
 export class ViewBox extends Behaviour {
 
+    /**
+     * All active ViewBox instances. The last one in the array is the currently active one.
+     */
     static readonly instances: ViewBox[] = [];
 
     /**
@@ -45,21 +50,39 @@ export class ViewBox extends Behaviour {
     @serializable()
     referenceFieldOfView: number = -1;
 
+    /**
+     * The mode determines if the viewbox should be applied once or continuously while it is the active viewbox.  
+     * Options:
+     * - "once": The viewbox will be applied once when it becomes the active viewbox. This is useful if you want to fit the view once and then allow the user to zoom or pan freely.
+     * - "continuous": The viewbox will be applied continuously while it is the active viewbox. This is useful if you animate or scale the viewbox over time.
+    */
+    @serializable()
+    get mode() { return this._mode; }
+    set mode(v: ViewBoxMode) {
+        if (v === this._mode) return;
+        this._mode = v;
+        if (v === "once") this._applyCount = 0;
+        if (debugParam || this.debug) console.debug("[ViewBox] Set mode:", v);
+    }
+    private _mode: ViewBoxMode = "continuous";
+
     /**
      * Enable debug logs and rendering for this component instance
      */
     @serializable()
     debug: boolean = false;
 
+    /** @internal */
     onEnable(): void {
         if (debugParam || this.debug || isDevEnvironment()) console.debug("[ViewBox] Using camera fov:", this.referenceFieldOfView);
         // register instance
         ViewBox.instances.push(this);
-
+        this._applyCount = 0;
         this.removeUpdateCallback();
         this.context.pre_render_callbacks.push(this.internalUpdate);
     }
 
+    /** @internal */
     onDisable(): void {
         if (debugParam || this.debug) console.debug("[ViewBox] Disabled");
         // unregister instance
@@ -77,6 +100,7 @@ export class ViewBox extends Behaviour {
 
     private static readonly _tempProjectionMatrix: Matrix4 = new Matrix4();
     private static readonly _tempProjectionMatrixInverse: Matrix4 = new Matrix4();
+    private _applyCount = 0;
 
     private internalUpdate = () => {
         if (this.context.isInXR) return;
@@ -108,6 +132,11 @@ export class ViewBox extends Behaviour {
             return;
         }
 
+        if (this._applyCount >= 1 && this.mode === "once") {
+            return;
+        }
+        this._applyCount++;
+
         const domWidth = this.context.domWidth;
         const domHeight = this.context.domHeight;
 
@@ -129,7 +158,7 @@ export class ViewBox extends Behaviour {
         ViewBox._tempProjectionMatrix.copy(camera.projectionMatrix);
         ViewBox._tempProjectionMatrixInverse.copy(camera.projectionMatrixInverse);
         const view = camera.view;
-        const zoom = camera.zoom;
+        const cameraZoom = camera.zoom;
         const aspect = camera.aspect;
         const fov = camera.fov;
         // Set values to default so we can calculate the box size correctly
@@ -194,6 +223,7 @@ export class ViewBox extends Behaviour {
             width / diffWidth,
             height / diffHeight
         );
+        const zoom = scale / (height * .5);
         // console.log({ scale, width, height, boxWidth: boxWidth * camera.aspect, boxHeight, diffWidth, diffHeight, aspect: camera.aspect, distance })
         // this.context.focusRectSettings.zoom = 1.39;
         // if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
@@ -202,13 +232,13 @@ export class ViewBox extends Behaviour {
         vec.project(camera);
         this.context.focusRectSettings.offsetX = vec.x;
         this.context.focusRectSettings.offsetY = vec.y;
-        this.context.focusRectSettings.zoom = scale / (height * .5);
+        this.context.focusRectSettings.zoom = zoom;
         // if we don't have a focus rect yet, set it to the dom element
         if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
 
         // Reset values
         camera.view = view;
-        camera.zoom = zoom;
+        camera.zoom = cameraZoom;
         camera.aspect = aspect;
         camera.fov = fov;
         camera.projectionMatrix.copy(ViewBox._tempProjectionMatrix);

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

@@ -24,6 +24,8 @@ const debug = getParam("debugarcamera");
 /**
  * WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.
  * 
+ * - Example: https://samples.needle.tools/ar-camera-background
+ * 
  * @category XR
  * @group Components
  */

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

@@ -20,7 +20,7 @@ const invertForwardMatrix = new Matrix4().makeRotationY(Math.PI);
 
 /**
  * The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.  
- * It is also responsible for scaling the user in AR. 
+ * It is also responsible for scaling the user in AR and to define the center of the AR scene. If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
  * 
  * @example 
  * ```ts

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

@@ -27,6 +27,8 @@ const debugQuicklook = getParam("debugusdz");
  * 
  * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
  * 
+ * - Example: https://samples.needle.tools/collaborative-sandbox
+ * 
  * @example Enable VR and AR support using code
  * ```ts
  * import { onStart, WebXR } from "@needle-tools/engine";

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

@@ -290,6 +290,16 @@ class ImageTrackingExtension implements IUSDExporterExtension {
 
 
 /**
+ * Add this component to a object to enable image tracking in WebXR sessions.    
+ * 
+ * You need to add at least one {@link WebXRImageTrackingModel} to the `trackedImages` array to define which images to track and which objects to place on top of them.
+ * 
+ * **NOTE:** For Android devices, image tracking currently requires the user to enable the `chrome://flags/#webxr-incubations` flag in Chrome.  
+ * 
+ * **NOTE:** For iOS only one image can be tracked at a time. If you have multiple images in the `trackedImages` array, only the first one will be tracked. You can use the {@link setPrimaryImage} method to change which image is tracked before entering the XR session.  
+ * 
+ * - Example: https://samples.needle.tools/image-tracking
+ * 
  * @category XR
  * @group Components
  */
@@ -313,7 +323,14 @@ export class WebXRImageTracking extends Behaviour {
 
     /**
      * Add an image to track. If the image is already in the trackedImages array it won't be added again.  
-     * Note: that adding images at runtime *while* in AR is not supported.
+     * Note: that adding images at runtime *while* in AR is not supported.  
+     * 
+     * @example
+     * ```ts
+     * const imageTracking = GameObject.getComponent(myGameObject, WebXRImageTracking);
+     * const image = new WebXRImageTrackingModel({ url: "https://example.com/my-marker.png", widthInMeters: 0.2, object: myObject });
+     * imageTracking.addImage(image, true); // add and set as primary image
+     * ```
      */
     addImage(image: WebXRImageTrackingModel, asPrimary: boolean = false) {
         if (!this.trackedImages.includes(image)) {
@@ -324,7 +341,11 @@ export class WebXRImageTracking extends Behaviour {
     }
 
 
-
+    /**
+     * List of images to track in the WebXR session. Use {@link WebXRImageTrackingModel} to define each image and the object to place on top of it.  
+     * 
+     * Use the `addImage()` and `setPrimaryImage()` methods to modify this array at runtime.
+     */
     @serializable(WebXRImageTrackingModel)
     readonly trackedImages: WebXRImageTrackingModel[] = [];
 
@@ -339,6 +360,7 @@ export class WebXRImageTracking extends Behaviour {
 
     private _supported: boolean = true;
 
+    /** @internal */
     awake(): void {
         if (debug) console.log(this)
         if (!this.trackedImages) return;
@@ -348,9 +370,11 @@ export class WebXRImageTracking extends Behaviour {
             }
         }
     }
+    /** @internal */
     onEnable() {
         USDZExporter.beforeExport.addEventListener(this.onBeforeUSDZExport);
     }
+    /** @internal */
     onDisable(): void {
         USDZExporter.beforeExport.removeEventListener(this.onBeforeUSDZExport);
     }
@@ -362,7 +386,7 @@ export class WebXRImageTracking extends Behaviour {
     }
 
 
-
+    /** @internal */
     onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
         // console.log("onXRRequested", args, this.trackedImages)
         if (this.trackedImages) {
@@ -386,6 +410,7 @@ export class WebXRImageTracking extends Behaviour {
         }
     }
 
+    /** @internal */
     onEnterXR(_args: NeedleXREventArgs): void {
         if (this.trackedImages) {
             for (const trackedImage of this.trackedImages) {
@@ -408,6 +433,7 @@ export class WebXRImageTracking extends Behaviour {
         }
     };
 
+    /** @internal */
     onLeaveXR(_args: NeedleXREventArgs): void {
 
         if (!this.supported && DeviceUtilities.isAndroidDevice()) {
@@ -440,6 +466,7 @@ export class WebXRImageTracking extends Behaviour {
 
     private readonly webXRIncubationsWarning = "Image tracking is currently not supported on this device. On Chrome for Android, you can enable the <a target=\"_blank\" href=\"#\" onclick=\"() => console.log('I')\">chrome://flags/#webxr-incubations</a> flag.";
 
+    /** @internal */
     onUpdateXR(args: NeedleXREventArgs): void {
         this.currentImages.length = 0;