@needle-tools/engine 5.1.7 → 5.1.8-next.1784885350.large-bamboo.746608e

package/src/engine/webcomponents/needle-engine.loading.ts

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { _ERXbX, _owM, _jcZJFQ } from "../engine_license.js";
+import { _$BbU, _WXkIc, __UCuVxqBu } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { LoadingProgressArgs } from "../engine_setup.js";
 import { getParam } from "../engine_utils.js";
@@ -205,7 +205,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
 
-        const hasLicense = _owM();
+        const hasLicense = _WXkIc();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
             this._loadingElement.style.width = "100%";
@@ -373,7 +373,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
 
     // private async handleRuntimeLicense(loadingElement: HTMLElement) {
     //     // First check if we have a commercial license
-    //     let commercialLicense = _ERXbX();
+    //     let commercialLicense = _$BbU();
     //     // if it's the case then we don't need to perform a runtime check
     //     if (commercialLicense) return;
 
@@ -393,10 +393,10 @@ export class EngineLoadingView implements ILoadingViewHandler {
     //     loadingElement.appendChild(nonCommercialContainer);
 
     //     // Use the runtime license check
-    //     if (!isDevEnvironment() && _jcZJFQ) {
+    //     if (!isDevEnvironment() && __UCuVxqBu) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await _jcZJFQ;
-    //         commercialLicense = _ERXbX();
+    //         await __UCuVxqBu;
+    //         commercialLicense = _$BbU();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

package/src/engine/webcomponents/needle-engine.ts

@@ -3,7 +3,7 @@ import type { Texture } from "three";
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { _ERXbX, Telemetry } from "../engine_license.js";
+import { _$BbU, Telemetry } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -579,7 +579,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = _ERXbX();
+        const allowOverridingDefaultLoading = _$BbU();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/NeedleXRSession.ts

@@ -72,8 +72,8 @@ let debugFPSFramesSinceLastUpdate = 0;
 export interface INeedleXRSessionEventReceiver extends Pick<IComponent, "destroyed"> {
     get activeAndEnabled(): boolean;
     supportsXR?(mode: XRSessionMode): boolean;
-    /** Called before requesting a XR session */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    /** Called before requesting a XR session. May return a promise that is awaited before requesting. */
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     onEnterXR?(args: NeedleXREventArgs): void;
     onUpdateXR?(args: NeedleXREventArgs): void;
     onLeaveXR?(args: NeedleXREventArgs): void;
@@ -757,7 +757,15 @@ export class NeedleXRSession implements INeedleXRSession {
             console.log("%c" + `Requesting ${mode} session`, "font-weight:bold;");
         for (const script of scripts) {
             if (script.onBeforeXR && script.activeAndEnabled && !script.destroyed) {
-                script.onBeforeXR(mode, init);
+                try {
+                    // Await: onBeforeXR may be async (e.g. WebXRImageTracking awaits marker bitmap loads
+                    // so late-decoding markers aren't dropped). A failing hook must not abort the session
+                    // request for every other component.
+                    await script.onBeforeXR(mode, init);
+                }
+                catch (err) {
+                    console.error("[NeedleXRSession] onBeforeXR hook failed:", err);
+                }
             }
         }
         this.invokeSessionRequestStart(mode, init, context ?? Context.Current);

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { _ERXbX } from "../engine_license.js";
+import { _$BbU } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (_ERXbX()) {
+        if (_$BbU()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine-components/Component.ts

@@ -930,8 +930,9 @@ export abstract class Component implements IComponent, EventTarget,
      * Use to modify session initialization parameters
      * @param mode The XR session mode being requested
      * @param args The session initialization parameters that can be modified
+     * @returns void, or a promise that is awaited before the session is requested (e.g. to load assets)
      */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
 
     /**
      * Called when this component joins an XR session or becomes active in a running session

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

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { _owM } from "../../../engine/engine_license.js";
+import { _WXkIc } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!_owM()) {
+        if (!_WXkIc()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!_owM()) {
+                        if (!_WXkIc()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!_owM()) {
+        if (!_WXkIc()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

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

@@ -2,26 +2,39 @@ import { Behaviour } from "../Component.js";
 import type { XRControllerMovement } from "./controllers/XRControllerMovement.js";
 
 /**
- * Marks a GameObject as a valid teleportation target for VR locomotion.  
- * Add this component to objects or surfaces where users should be able to teleport.  
+ * Marks a GameObject as a valid teleportation target for VR locomotion.
+ * Add this component to objects or surfaces where users should be able to teleport.
  *
- * **Usage:**  
- * - Add to floor surfaces, platforms, or designated teleport spots
- * - Works with {@link XRControllerMovement} component's teleport system
- * - Can be used to restrict teleportation to specific areas
+ * **How targeting works (important):**
+ * The teleport ray uses a **visual raycast against rendered meshes** — NOT physics colliders.
+ * When {@link XRControllerMovement.useTeleportTarget} is enabled, the controller ray is cast
+ * against the rendered scene and the hit object (or any of its parents) is checked for a
+ * `TeleportTarget` component. You can only teleport onto an object if that object, or one of
+ * its ancestors, has this component.
+ *
+ * **Requirements for a target to be hittable:**
+ * - It MUST have a visible, rendered mesh (a `MeshRenderer` / geometry). The ray hits the
+ *   rendered geometry directly.
+ * - **A collider is NOT required.** Teleport does not use physics colliders — adding a
+ *   `BoxCollider` (or any collider) has no effect on whether the target can be teleported to.
+ * - It must NOT be on the IgnoreRaycast layer (three.js layer 2) and must not have
+ *   `raycastAllowed` / `visible` set to false, otherwise the ray skips it.
+ * - The `TeleportTarget` component may be on the hit mesh itself or on any parent
+ *   (resolved via `getComponentInParent`).
  *
  * **Setup:**
- * 1. Add this component to GameObjects that should be teleport destinations
- * 2. Configure {@link XRControllerMovement} to use teleport targets (optional)
+ * 1. Add this component to GameObjects (with a visible mesh) that should be teleport destinations
+ * 2. Enable "Use Teleport Target" on the {@link XRControllerMovement} component so teleporting
+ *    is restricted to objects carrying this component
  * 3. Test teleportation in VR mode
  *
  * @example
  * ```ts
- * // Make a platform teleportable
+ * // Make a platform teleportable (the platform already has a visible mesh)
  * const platform = myPlatform.addComponent(TeleportTarget);
  * ```
  *
- * @summary Marker component for valid VR teleportation destinations
+ * @summary Marker component for valid VR teleportation destinations (mesh hit-test, no collider needed)
  * @category XR
  * @group Components
  * @see {@link XRControllerMovement} for VR locomotion and teleport configuration

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

@@ -14,6 +14,7 @@ import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.j
 import { Behaviour, GameObject } from "../Component.js";
 import { EventList } from "../EventList.js";
 import { Renderer } from "../Renderer.js";
+import { _imageElements, collectTrackedImages, loadImage } from "./WebXRImageTracking.utils.js";
 
 // https://github.com/immersive-web/marker-tracking/blob/main/explainer.md
 
@@ -709,26 +710,25 @@ export class WebXRImageTracking extends Behaviour {
 
 
     /** @internal */
-    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
-        // console.log("onXRRequested", args, this.trackedImages)
-        if (this.trackedImages) {
-            args.optionalFeatures = args.optionalFeatures || [];
-            if (!args.optionalFeatures.includes("image-tracking"))
-                args.optionalFeatures.push("image-tracking");
+    async onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): Promise<void> {
+        if (!this.trackedImages) return;
 
-            if(!args.trackedImages) args.trackedImages = [];
-            for (const trackedImage of this.trackedImages) {
-                if (trackedImage.image?.length && trackedImage.widthInMeters > 0) {
-                    const bitmap = _imageElements.get(trackedImage.image);
-                    if (bitmap) {
-                        this.trackedImageIndexMap.set(args.trackedImages.length, trackedImage);
-                        args.trackedImages.push({
-                            image: bitmap,
-                            widthInMeters: trackedImage.widthInMeters
-                        });
-                    }
-                }
-            }
+        args.optionalFeatures = args.optionalFeatures || [];
+        if (!args.optionalFeatures.includes("image-tracking"))
+            args.optionalFeatures.push("image-tracking");
+
+        // Resolve the marker bitmaps *before* the session is requested.
+        // onBeforeXR runs the moment "Enter AR" is tapped. Marker images load asynchronously
+        // (network fetch + createImageBitmap), so without awaiting here a marker that hasn't finished
+        // decoding yet would be silently dropped from `trackedImages` and never registered with the
+        // native/WebXR session - it would then only start working after exiting and re-entering AR,
+        // once the bitmap has been cached. Awaiting the (idempotent) loads closes that race.
+        // A marker that can not be loaded resolves to null and is skipped individually, so a single
+        // unavailable image never rejects the whole XR session request. See forum topic #2859.
+        this.trackedImageIndexMap.clear();
+        const indexMap = await collectTrackedImages(this.trackedImages, args);
+        for (const [index, model] of indexMap) {
+            this.trackedImageIndexMap.set(index, model);
         }
     }
 
@@ -942,36 +942,4 @@ export class WebXRImageTracking extends Behaviour {
             }
         }
     }
-}
-
-
-
-
-const _imageElements: Map<string, ImageBitmap | null> = new Map();
-const _imageLoadingPromises: Map<string, Promise<boolean>> = new Map();
-
-async function loadImage(url: string) {
-    if (_imageElements.has(url)) {
-        if (_imageLoadingPromises.has(url)) return _imageLoadingPromises.get(url);
-        return Promise.resolve(true);
-    }
-    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);
-        });
-    });
-
-    _imageLoadingPromises.set(url, promise);
-    promise.finally(() => {
-        _imageLoadingPromises.delete(url);
-    });
-
-    return promise;
 }

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

@@ -0,0 +1,105 @@
+import { isDevEnvironment } from "../../engine/debug/index.js";
+import { getParam } from "../../engine/engine_utils.js";
+
+import type { WebXRImageTrackingModel } from "./WebXRImageTracking.js";
+
+// Kept in a dedicated module (with only lightweight imports) so the marker-loading logic can be unit
+// tested without pulling in the heavy WebXRImageTracking / USDZ exporter import graph.
+
+const debug = getParam("debugimagetracking");
+
+/**
+ * Cache of decoded marker bitmaps, keyed by image url.
+ * Also read by the USDZ exporter (see {@link WebXRImageTracking}) to embed the marker into the .usdz.
+ */
+export const _imageElements: Map<string, ImageBitmap | null> = new Map();
+const _imageLoadingPromises: Map<string, Promise<ImageBitmap | null>> = new Map();
+
+/**
+ * Resolve marker bitmaps for the given tracked-image models and append them to `args.trackedImages`
+ * (the list handed to `navigator.xr.requestSession`).
+ *
+ * Every valid marker is awaited so that images which are still decoding when the XR session is
+ * requested get included instead of being silently dropped (which previously caused markers to only
+ * work after re-entering AR). Loading happens in parallel and never rejects: a marker that can not be
+ * loaded is skipped individually so a single unavailable image can not fail the whole session request.
+ *
+ * @param models The configured tracked-image models
+ * @param args The session init object; `trackedImages` is created if missing and appended to
+ * @param load Injectable loader (defaults to {@link loadImage}); resolves the decoded bitmap or null
+ * @returns Map of `trackedImages` index -> model for the appended images (used to resolve results)
+ */
+export async function collectTrackedImages(
+    models: readonly WebXRImageTrackingModel[] | undefined | null,
+    args: { trackedImages?: Array<{ image: ImageBitmap, widthInMeters: number }> },
+    load: (url: string) => Promise<ImageBitmap | null> = loadImage,
+): Promise<Map<number, WebXRImageTrackingModel>> {
+    const indexMap = new Map<number, WebXRImageTrackingModel>();
+    if (!args.trackedImages) args.trackedImages = [];
+    if (!models) return indexMap;
+
+    const valid = models.filter(m => !!m.image?.length && m.widthInMeters > 0);
+    // Load in parallel and wait for all of them. Guard every load with a catch so that a rejecting
+    // loader is treated as "unavailable" (null) rather than aborting the whole session request.
+    const bitmaps = await Promise.all(valid.map(m => load(m.image!).catch(() => null)));
+
+    for (let i = 0; i < valid.length; i++) {
+        const model = valid[i];
+        const bitmap = bitmaps[i];
+        if (bitmap) {
+            indexMap.set(args.trackedImages.length, model);
+            args.trackedImages.push({ image: bitmap, widthInMeters: model.widthInMeters });
+        }
+        else if (isDevEnvironment() || debug) {
+            console.warn(`[WebXRImageTracking] Marker image could not be loaded, skipping: ${model.image}`);
+        }
+    }
+    return indexMap;
+}
+
+/**
+ * Load and decode a marker image into an {@link ImageBitmap}, caching it in {@link _imageElements}.
+ * Idempotent: concurrent or repeated calls for the same URL share a single in-flight load.
+ *
+ * Resolves to `null` and never rejects when the image can not be fetched or decoded, so callers can
+ * skip an unavailable marker without failing the surrounding XR session request. A failed load clears
+ * its cache entry so a later attempt (e.g. re-entering AR) can retry.
+ */
+export async function loadImage(url: string): Promise<ImageBitmap | null> {
+    const cached = _imageElements.get(url);
+    if (cached) return cached;
+    const pending = _imageLoadingPromises.get(url);
+    if (pending) return pending;
+
+    const promise = new Promise<ImageBitmap | null>(res => {
+        _imageElements.set(url, null); // placeholder to dedupe concurrent loads
+        if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Start loading image for tracking: ${url}`);
+        const imageElement = document.createElement("img") as HTMLImageElement;
+        imageElement.addEventListener("load", async () => {
+            try {
+                const img = await createImageBitmap(imageElement);
+                _imageElements.set(url, img);
+                if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Loaded image for tracking: ${url}`);
+                res(img);
+            }
+            catch (err) {
+                console.error(`[WebXRImageTracking] Failed to decode marker image for tracking: ${url}`, err);
+                _imageElements.delete(url); // allow a retry later (e.g. re-entering AR)
+                res(null);
+            }
+        });
+        imageElement.addEventListener("error", (evt) => {
+            console.error(`[WebXRImageTracking] Failed to load marker image for tracking: ${url}`, evt);
+            _imageElements.delete(url); // allow a retry later (e.g. re-entering AR)
+            res(null);
+        });
+        imageElement.src = url;
+    });
+
+    _imageLoadingPromises.set(url, promise);
+    promise.finally(() => {
+        _imageLoadingPromises.delete(url);
+    });
+
+    return promise;
+}

package/src/engine-components/webxr/controllers/XRControllerMovement.ts

@@ -28,8 +28,17 @@ declare type HitPointObject = Object3D & { material: Material & { opacity: numbe
  * 
  * Additionally it supports teleporting using the right controller's thumbstick or by pinching the index finger tip in front of the hand (if hand tracking is enabled).
  * It also visualizes controller rays and hit points in the scene.
- * 
- * 
+ *
+ * The component operates on the active XR rig and controllers from the {@link NeedleXRSession} (`args.xr.rig`,
+ * `args.xr.leftController` / `rightController`) and receives `onUpdateXR` regardless of where it sits in the hierarchy.
+ * It does NOT need to be on the same GameObject as {@link WebXR}, and does not read {@link WebXR} from its parents.
+ *
+ * **Duplicate-handler gotcha:** {@link WebXR.setDefaultMovementEnabled} (called when `WebXR.useDefaultControls` is enabled,
+ * the default) adds an `XRControllerMovement` to the WebXR GameObject only if that object has none. If you place your own
+ * `XRControllerMovement` on a different object, WebXR still adds a second, default one at runtime — two handlers then run
+ * simultaneously (doubled movement, and your teleport settings such as {@link XRControllerMovement.useTeleportTarget} are
+ * bypassed by the default handler). Put your component on the WebXR GameObject, or disable `WebXR.useDefaultControls`.
+ *
  * @summary Move the XR rig using controller input
  * @category XR
  * @group Components
@@ -61,7 +70,15 @@ export class XRControllerMovement extends Behaviour implements XRMovementBehavio
     @serializable()
     usePinchToTeleport: boolean = true;
 
-    /** Enable to only allow teleporting on objects with a TeleportTarget component (see {@link TeleportTarget})
+    /** Enable to only allow teleporting on objects with a {@link TeleportTarget} component.
+     *
+     * The teleport ray is a **visual raycast against rendered meshes** (not physics colliders):
+     * it hits the rendered geometry and then looks for a {@link TeleportTarget} on the hit object
+     * or any of its parents. A collider is NOT required on the target — only a visible mesh that
+     * is not on the IgnoreRaycast layer.
+     *
+     * When enabled, teleporting is rejected if the ray does not hit a `TeleportTarget` (the
+     * ground-plane fallback used in free teleport mode is also disabled).
      * @default false
     */
     @serializable()