@needle-tools/engine 5.1.8 → 5.1.10

package/src/engine-components/postprocessing/Effects/DepthOfField.ts

@@ -83,12 +83,20 @@ export class DepthOfField extends PostProcessingEffect {
         //     inverted: true,
         //     // blendFunction: BlendFunction.SET,
         // });
+        // Seed from the parameters, the same way BloomEffect does. The
+        // onValueChanged handlers below only fire on a LATER assignment, so
+        // hardcoding defaults here discarded anything set before the effect
+        // was created — which is the usual case, since components are
+        // configured right after addComponent but the effect is built when
+        // the composer asks for it. Values applied in awake/start were lost
+        // and only took hold if the same value was assigned a second time.
         const dof = new MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect(this.context.mainCamera!, {
-            worldFocusRange: .2,
+            worldFocusRange: this.focalLength.value,
             focalLength: 1,
-            bokehScale: 20,
+            bokehScale: this.aperture.value,
             resolutionScale: this.resolutionScale.value,
         });
+        dof.cocMaterial.worldFocusDistance = this.focusDistance.value;
 
         this.focusDistance.onValueChanged = v => {
             dof.cocMaterial.worldFocusDistance = v;

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

@@ -1,6 +1,13 @@
 export * from "./PostProcessingEffect.js";
 export * from "./PostProcessingHandler.js"
 export { PostProcessingEffectOrder } from "./utils.js";
+/* Effect option enums. The effect components themselves are exported from
+   codegen/components.ts, but these were unreachable: `DepthOfField.mode`
+   could not be set to a named value from outside the package. */
+export { DepthOfFieldMode } from "./Effects/DepthOfField.js";
+export { QualityLevel } from "./Effects/Antialiasing.js";
+export { ScreenSpaceAmbientOcclusionN8QualityMode } from "./Effects/ScreenspaceAmbientOcclusionN8.js";
+export { NEToneMappingMode } from "./Effects/Tonemapping.utils.js";
 export { PostProcessingManager } from "./Volume.js"
 export { Volume } from "./Volume.js"
 export * from "./VolumeParameter.js"

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

@@ -20,25 +20,34 @@ import { Behaviour } from "../Component.js";
 export class LookAt extends Behaviour implements UsdzBehaviour {
 
     /**
-     * The target object to look at. If not set, the main camera will be used.
+     * The target object to look at.
+     * @default undefined — when no target is set the main camera is used
      */
     @serializable(Object3D)
     target?: Object3D;
 
     /**
-     * Inverts the forward direction.
+     * Inverts the forward direction, so the object turns its back to the target
+     * instead of facing it. Useful for models authored facing -Z.
+     * @default false
      */
     @serializable()
     invertForward: boolean = false;
 
     /**
-     * Keep the up direction.
+     * Keeps the object upright while turning, so it only rotates around the up
+     * axis rather than tilting to point directly at a target above or below it.
+     * @default true
      */
     @serializable()
     keepUpDirection: boolean = true;
 
     /**
-     * Copy the target rotation.
+     * Copies the target's rotation instead of aiming at its position. Use this to
+     * match a target's orientation, for example to align with the camera.
+     *
+     * Ignored during a VR or AR session.
+     * @default false
      */
     @serializable()
     copyTargetRotation: boolean = false;

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

@@ -520,7 +520,7 @@ export class WebXR extends Behaviour {
             models = this.gameObject.addComponent(XRControllerModel)!;
             this._createdComponentsInSession.push(models);
             models.createControllerModel = this.showControllerModels;
-            models.createHandModel == this.showHandModels;
+            models.createHandModel = this.showHandModels;
         }
         if (models) models.enabled = enabled;
         return models;

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

@@ -4,6 +4,7 @@ import { Object3DEventMap } from "three";
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../engine/debug/index.js";
 import { AssetReference } from "../../engine/engine_addressables.js";
 import { Context } from "../../engine/engine_context.js";
+import { Telemetry } from "../../engine/engine_license.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { IGameObject } from "../../engine/engine_types.js";
 import { CircularBuffer, delay, DeviceUtilities, getParam } from "../../engine/engine_utils.js";
@@ -14,6 +15,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
 
@@ -216,9 +218,9 @@ export class WebXRImageTrackingModel {
      * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
      * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
      */
-    constructor(params: { url: string, widthInMeters: number, /** Object to track */ object: AssetReference | Object3D, createObjectInstance?: boolean, imageDoesNotMove?: boolean, hideWhenTrackingIsLost?: boolean }) {
+    constructor(params: Omit<WebXRImageTrackingOptions, "asPrimary">) {
         this.image = params.url;
-        this.widthInMeters = params.widthInMeters;
+        if (params.widthInMeters !== undefined) this.widthInMeters = params.widthInMeters;
         if (params.object instanceof Object3D) {
             this.object = new AssetReference({ asset: params.object });
         }
@@ -322,6 +324,27 @@ export class WebXRImageTrackingModel {
     }
 }
 
+/**
+ * Options for adding a trackable image marker via {@link WebXRImageTracking.addImage}.
+ * A convenience shape that also accepts a plain {@link Object3D} for `object`.
+ */
+export interface WebXRImageTrackingOptions {
+    /** URL to the marker image to track. Use high-contrast images with unique features for reliable tracking. */
+    url?: string;
+    /** The 3D object (or {@link AssetReference}) to display when the marker is detected. */
+    object: AssetReference | Object3D;
+    /** Physical width of the printed marker in meters. Must match the real marker size. @default 0.25 */
+    widthInMeters?: number;
+    /** Create a new instance of the object for each detection. @default false */
+    createObjectInstance?: boolean;
+    /** Enable for static markers (walls/floor) to improve tracking stability. @default false */
+    imageDoesNotMove?: boolean;
+    /** Hide the object when tracking is lost. @default true */
+    hideWhenTrackingIsLost?: boolean;
+    /** Make this the primary marker (used in QuickLook fallback mode). @default false */
+    asPrimary?: boolean;
+}
+
 /** Data passed to image tracking event listeners. */
 export interface WebXRImageTrackingEvent {
     /** The images currently being tracked this frame. */
@@ -619,27 +642,37 @@ export class WebXRImageTracking extends Behaviour {
      * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
      * In QuickLook mode, the first (primary) marker is used.
      *
-     * @param image The marker configuration to add
-     * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
+     * @param image The marker configuration - either a plain options object or a {@link WebXRImageTrackingModel}.
+     *              Set `asPrimary: true` to make this the primary marker (for QuickLook fallback).
      *
      * @example
      * ```ts
-     * // Super simple - works across all platforms
-     * const marker = new WebXRImageTrackingModel({
+     * // Super simple - just pass the marker url and the object to show
+     * imageTracking.addImage({
      *   url: "https://mysite.com/poster.png",
-     *   widthInMeters: 0.42, // A3 poster width
-     *   object: cool3DModel
+     *   object: cool3DModel,
+     *   widthInMeters: 0.42, // A3 poster width (optional, defaults to 0.25)
      * });
-     * imageTracking.addImage(marker);
      * // That's it! Needle does the rest.
      * ```
      */
-    addImage(image: WebXRImageTrackingModel, asPrimary: boolean = false) {
-        if (!this.trackedImages.includes(image)) {
-            this.trackedImages.push(image);
-            loadImage(image.image!);
+    addImage(options: WebXRImageTrackingOptions): void;
+    addImage(model: WebXRImageTrackingModel): void;
+    addImage(image: WebXRImageTrackingOptions | WebXRImageTrackingModel): void {
+        // Accept either a ready-made model or a plain options object (which allows `object` to be a
+        // plain Object3D). Normalize to a WebXRImageTrackingModel; the constructor wraps Object3D in
+        // an AssetReference for us.
+        const model = image instanceof WebXRImageTrackingModel ? image : new WebXRImageTrackingModel(image);
+        if (!this.trackedImages.includes(model)) {
+            this.trackedImages.push(model);
+            loadImage(model.image!);
+            if(isDevEnvironment()) {
+                if(model.widthInMeters <= 0) {
+                    this.onInvalidImageSizeDetected(model.image!);
+                }
+            }
         }
-        if (asPrimary) this.setPrimaryImage(image);
+        if (!(image instanceof WebXRImageTrackingModel) && image.asPrimary) this.setPrimaryImage(model);
     }
 
 
@@ -689,6 +722,9 @@ export class WebXRImageTracking extends Behaviour {
         for (const trackedImage of this.trackedImages) {
             if (trackedImage.image) {
                 loadImage(trackedImage.image);
+                if(isDevEnvironment() && trackedImage.widthInMeters <= 0) {
+                    this.onInvalidImageSizeDetected(trackedImage.image);
+                }
             }
         }
     }
@@ -701,6 +737,16 @@ export class WebXRImageTracking extends Behaviour {
         USDZExporter.beforeExport.removeEventListener(this.onBeforeUSDZExport);
     }
 
+
+    private onInvalidImageSizeDetected(url:string) {
+        if(globalThis["__NEEDLE_DEBUG_WebARImageSizeInvalid__"]) return;
+        globalThis["__NEEDLE_DEBUG_WebARImageSizeInvalid__"] = true;
+        console.warn(`[WebXRImageTracking] Invalid marker size detected for image ${url}. Ensure 'widthInMeters' is greater than 0 for accurate tracking.`);
+        if(isDevEnvironment()) {
+            showBalloonWarning(`[WebXRImageTracking] Invalid marker size detected for image ${url}. Ensure 'widthInMeters' is greater than 0 for accurate tracking.`);
+        }
+    }
+
     private onBeforeUSDZExport = (args: { exporter: USDZExporter }) => {
         if (this.activeAndEnabled && this.trackedImages?.length) {
             args.exporter.extensions.push(new ImageTrackingExtension(args.exporter, this));
@@ -709,31 +755,30 @@ 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);
         }
     }
 
     /** @internal */
-    onEnterXR(_args: NeedleXREventArgs): void {
+    onEnterXR(args: NeedleXREventArgs): void {
         if (this.trackedImages) {
             for (const trackedImage of this.trackedImages) {
                 if (trackedImage.object?.asset) {
@@ -753,11 +798,52 @@ export class WebXRImageTracking extends Behaviour {
         for (const trackedData of this.imageToObjectMap.values()) {
             trackedData.frames = 0;
         }
+
+        // A session GRANTED before the scene finished loading (App Clip / NeedleGo
+        // handoff, Quest link traversal) was requested without this component's
+        // markers — onBeforeXR never contributed to its init, and the WebXR spec has
+        // no way to add tracked images to a running session. The NeedleGo polyfill
+        // CAN (ARKit re-runs its configuration with new detection images), so
+        // register late where supported and surface the misconfiguration otherwise.
+        if (this.trackedImages?.length && this.trackedImageIndexMap.size === 0) {
+            if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] No marker images made it into the session init (granted session?) — attempting runtime registration for ${this.trackedImages.length} image(s)`);
+            this.registerImagesWithRunningSession(args.xr.session);
+        }
+        else if (this.trackedImages?.length && (isDevEnvironment() || debug)) {
+            console.debug(`[WebXRImageTracking] ${this.trackedImageIndexMap.size} marker image(s) registered via the session init`);
+        }
     };
 
+    /** Late-registers this component's marker images into an already running session
+     * via the NeedleGo polyfill's runtime hook. See {@link onEnterXR}. */
+    private async registerImagesWithRunningSession(session: XRSession) {
+        const register = (session as XRSession & { nonStandard_registerTrackedImages?: (images: Array<{ image: ImageBitmap, widthInMeters: number }>) => number }).nonStandard_registerTrackedImages;
+        if (typeof register !== "function") {
+            console.warn("[WebXRImageTracking] The XR session was started before the scene finished loading and does not support registering marker images at runtime — image tracking will not work in this session. Exit and re-enter AR from the loaded page.");
+            Telemetry.sendEvent(this.context, "xr", { action: "image_tracking_missed_session_init" });
+            return;
+        }
+        const args: { trackedImages?: Array<{ image: ImageBitmap, widthInMeters: number }> } = {};
+        const indexMap = await collectTrackedImages(this.trackedImages, args);
+        if (!args.trackedImages?.length) return;
+        // the session may have ended (or been replaced) while marker bitmaps loaded
+        if (this.context.xr?.session !== session) return;
+        const baseIndex = register.call(session, args.trackedImages);
+        if (baseIndex < 0) return;
+        for (const [index, model] of indexMap) {
+            this.trackedImageIndexMap.set(baseIndex + index, model);
+        }
+        if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Registered ${args.trackedImages.length} marker image(s) with the running session (granted before the scene loaded)`);
+    }
+
     /** @internal */
     onLeaveXR(_args: NeedleXREventArgs): void {
 
+        // result indices are scoped to the session that registered the images — a new
+        // session rebuilds the map (onBeforeXR, or the late registration in onEnterXR
+        // for granted sessions, which detects the empty map)
+        this.trackedImageIndexMap.clear();
+
         if (!this.supported && DeviceUtilities.isAndroidDevice()) {
             showBalloonWarning(this.webXRIncubationsWarning);
         }
@@ -942,36 +1028,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/XRControllerModel.ts

@@ -1,7 +1,6 @@
 import { AxesHelper, Group, Material, Mesh, Object3D, XRHandSpace } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { XRControllerModelFactory } from "three/examples/jsm/webxr/XRControllerModelFactory.js";
-import { XRHandMeshModel } from "three/examples/jsm/webxr/XRHandMeshModel.js";
 
 import { AssetReference } from "../../../engine/engine_addressables.js";
 import { setDontDestroy } from "../../../engine/engine_gameobject.js";
@@ -15,6 +14,7 @@ import { NeedleXRController, type NeedleXRControllerEventArgs, type NeedleXREven
 import { registerComponentExtension, registerExtensions } from "../../../engine/extensions/extensions.js";
 import { NEEDLE_progressive } from "../../../engine/extensions/NEEDLE_progressive.js";
 import { flipForwardMatrix } from "../../../engine/xr/internal.js";
+import { XRHandMeshModel } from "../../../engine/xr/XRHandMeshModel.js";
 import { Behaviour, Component, GameObject } from "../../Component.js"
 
 const debug = getParam("debugwebxr");
@@ -288,8 +288,6 @@ export class XRControllerModel extends Behaviour {
 
         const loader = new GLTFLoader();
         addDracoAndKTX2Loaders(loader, context);
-        await registerExtensions(loader, context, this.sourceId ?? "", this.sourceId ?? "");
-        const componentsExtension = registerComponentExtension(loader);
 
         let filename = "";
 
@@ -306,22 +304,30 @@ export class XRControllerModel extends Behaviour {
             loader.setPath('https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/generic-hand/');
         }
 
+        // The hand is a separate glTF and needs its own source id: its components resolve their
+        // relative uris against it (resolveUrl) and its lightmaps/skybox are keyed by it. Using
+        // this component's id resolved the hand's uris next to the HOST glb and let the hand's
+        // skybox overwrite the scene's. customHand.url is already resolved, `filename` is not
+        // (extension stripped for XRHandMeshModel).
+        const handSourceId = customHand?.url ?? `${loader.path}${filename}.glb`;
+        await registerExtensions(loader, context, handSourceId, handSourceId);
+        const componentsExtension = registerComponentExtension(loader);
+
 
         const handObject = new Object3D();
         setDontDestroy(handObject);
-        // @ts-ignore
         const handmesh = new XRHandMeshModel(handObject, hand, loader.path, filename, loader, (object: Object3D) => {
 
             const gltf = componentsExtension?.gltf;
-            // The XRHandMeshController removes the hand from the gltf before calling this callback
-            // we need this in the GLTF scene however for creating the builtin components 
+            // XRHandMeshModel reparents the hand out of the gltf scene before calling this
+            // callback; we need it back in the scene so the builtin components are created on it
             if (gltf?.scene.children?.length === 0) {
                 gltf.scene.children[0] = object;
             }
 
             // console.log(controller.side, componentsExtension.gltf, object, componentsExtension.gltf.scene?.children)
             if (componentsExtension?.gltf)
-                getLoader().createBuiltinComponents(comp.context, comp.sourceId || filename, componentsExtension.gltf, null, componentsExtension);
+                getLoader().createBuiltinComponents(comp.context, handSourceId, componentsExtension.gltf, null, componentsExtension);
 
             // The hand mesh should not receive raycasts
             object.traverse(child => {