@needle-tools/engine 4.1.1 → 4.2.2

package/src/engine-components/export/usdz/extensions/behavior/Behaviour.ts

@@ -120,19 +120,21 @@ export class BehaviorExtension implements IUSDExporterExtension {
                 if (actionModel.tokenId === "StartAnimation") {
                     playAnimationActions.add(actionModel);
                 }
+                let actionType = actionModel.tokenId;
+                if (actionModel.type !== undefined) actionType += ":" + actionModel.type;
                 const affected = actionModel.affectedObjects;
                 if (affected) {
                     if (Array.isArray(affected)) {
                         for (const a of affected) {
                             actionTargets.add(a as Target);
                             //@ts-ignore
-                            if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}] -- ${actionModel.tokenId} --> ${a.uuid}(("${a.displayName || a.name || a.uuid}"))\n`;
+                            if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}\n${actionType}] -- ${actionType} --> ${a.uuid}(("${a.displayName || a.name || a.uuid}"))\n`;
                         }
                     }
                     else if (typeof affected === "object") {
                         actionTargets.add(affected as Target);
                         //@ts-ignore
-                        if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}] -- ${actionModel.tokenId} --> ${affected.uuid}(("${affected.displayName || affected.name || affected.uuid}"))\n`;
+                        if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}\n${actionType}] -- ${actionType} --> ${affected.uuid}(("${affected.displayName || affected.name || affected.uuid}"))\n`;
                     }
                     else if (typeof affected === "string") {
                         actionTargets.add({uuid: affected} as any as Target);
@@ -144,7 +146,7 @@ export class BehaviorExtension implements IUSDExporterExtension {
                     if (typeof xform === "object") {
                         actionTargets.add(xform as Target);
                         //@ts-ignore
-                        if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}] -- ${actionModel.tokenId} --> ${xform.uuid}(("${xform.displayName || xform.name || xform.uuid}"))\n`;
+                        if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${actionModel.id}[${actionModel.id}\n${actionType}] -- ${actionType} --> ${xform.uuid}(("${xform.displayName || xform.name || xform.uuid}"))\n`;
                     }
                     else if (typeof xform === "string") {
                         actionTargets.add({uuid: xform} as any as Target);
@@ -159,19 +161,21 @@ export class BehaviorExtension implements IUSDExporterExtension {
                     collectTrigger(t, action);
             }
             else if (trigger instanceof TriggerModel) {
+                let triggerType = trigger.tokenId;
+                if (trigger.type !== undefined) triggerType += ":" + trigger.type;
                 if (typeof trigger.targetId === "object") {
                     triggerSources.add(trigger.targetId as Target);
                     //@ts-ignore
-                    if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${trigger.targetId.uuid}(("${trigger.targetId.displayName}")) --> ${trigger.id}[${trigger.id}]\n`;
+                    if (createMermaidGraphForDebugging) mermaidGraphTopLevel += `${trigger.targetId.uuid}(("${trigger.targetId.displayName}")) --> ${trigger.id}[${trigger.id}\n${triggerType}]\n`;
                 }
                 //@ts-ignore
-                if (createMermaidGraphForDebugging) mermaidGraph += `${trigger.id}((${trigger.id})) -- ${trigger.tokenId}${trigger.type ? ":" + trigger.type : ""} --> ${action.id}[${action.tokenId || action.id}]\n`;
+                if (createMermaidGraphForDebugging) mermaidGraph += `${trigger.id}((${trigger.id})) -- ${triggerType} --> ${action.id}[${action.tokenId || action.id}]\n`;
             }
         }
 
         // collect all targets of all triggers and actions
         for (const beh of this.behaviours) {
-            if (createMermaidGraphForDebugging) mermaidGraph += `subgraph Behavior_${beh.id}\n`;
+            if (createMermaidGraphForDebugging) mermaidGraph += `subgraph ${beh.id}\n`;
             collectAction(beh.action);
             collectTrigger(beh.trigger, beh.action);
             if (createMermaidGraphForDebugging) mermaidGraph += `end\n`;
@@ -180,10 +184,12 @@ export class BehaviorExtension implements IUSDExporterExtension {
         
         if (createMermaidGraphForDebugging) {
             console.log("All USDZ behaviours", this.behaviours);
-            console.warn("The Mermaid graph can be pasted into https://massive-mermaid.glitch.me/ or https://mermaid.live/edit. It should be in your clipboard already!");
-            console.log(mermaidGraph);
-            // copy to clipboard, can be pasted into https://massive-mermaid.glitch.me/ or https://mermaid.live/edit
-            navigator.clipboard.writeText(mermaidGraph);
+            if (this.behaviours.length) {
+                console.warn("The Mermaid graph can be pasted into https://massive-mermaid.glitch.me/ or https://mermaid.live/edit. It should be in your clipboard already!");
+                console.log(mermaidGraph);
+                // copy to clipboard, can be pasted into https://massive-mermaid.glitch.me/ or https://mermaid.live/edit
+                navigator.clipboard.writeText(mermaidGraph);
+            }
         }
 
         {
@@ -212,7 +218,7 @@ export class BehaviorExtension implements IUSDExporterExtension {
                 }
             }
 
-            if (createMermaidGraphForDebugging) {
+            if (createMermaidGraphForDebugging && playAnimationActions.size) {
                 console.log(animationsGraph);
             }
 

package/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -17,7 +17,7 @@ import { makeNameSafeForUSD,USDDocument, USDObject, USDZExporterContext } from "
 import { AnimationExtension, RegisteredAnimationInfo, type UsdzAnimation } from "../Animation.js";
 import { AudioExtension } from "./AudioExtension.js";
 import type { BehaviorExtension, UsdzBehaviour } from "./Behaviour.js";
-import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType,type IBehaviorElement, Target, TriggerBuilder } from "./BehavioursBuilder.js";
+import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType,GroupActionModel,type IBehaviorElement, Target, TriggerBuilder } from "./BehavioursBuilder.js";
 
 const debug = getParam("debugusdzbehaviours");
 
@@ -203,10 +203,10 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
     }
 
     onPointerEnter(_args: PointerEventData) {
-        this.context.input.setCursorPointer();
+        this.context.input.setCursor("pointer");
     }
     onPointerExit(_: PointerEventData) {
-        this.context.input.setCursorNormal();
+        this.context.input.unsetCursor("pointer");
     }
     onPointerClick(args: PointerEventData) {
         args.use();
@@ -251,7 +251,8 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
     private targetModels!: USDObject[];
 
     private static _materialTriggersPerId: { [key: string]: ChangeMaterialOnClick[] } = {}
-
+    private static _startHiddenBehaviour: BehaviorModel | null = null;
+    private static _parallelStartHiddenActions: USDObject[] = [];
 
     async beforeCreateDocument(_ext: BehaviorExtension, _context) {
         this.targetModels = [];
@@ -309,23 +310,25 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
     }
 
     private createAndAttachBehaviors(ext: BehaviorExtension, myVariants: Array<USDObject>, otherVariants: Array<USDObject>) {
-        const start: ActionModel[] = [];
         const select: ActionModel[] = [];
 
         const fadeDuration = Math.max(0, this.fadeDuration);
 
         select.push(ActionBuilder.fadeAction([...this.targetModels, ...otherVariants], fadeDuration, false));
-        start.push(ActionBuilder.fadeAction(myVariants, fadeDuration, false));
         select.push(ActionBuilder.fadeAction(myVariants, fadeDuration, true));
 
         ext.addBehavior(new BehaviorModel("Select_" + this.selfModel.name,
             TriggerBuilder.tapTrigger(this.selfModel),
             ActionBuilder.parallel(...select))
         );
-        ext.addBehavior(new BehaviorModel("StartHidden_" + this.selfModel.name,
-            TriggerBuilder.sceneStartTrigger(),
-            ActionBuilder.parallel(...start))
-        );
+        ChangeMaterialOnClick._parallelStartHiddenActions.push(...myVariants);
+        if (!ChangeMaterialOnClick._startHiddenBehaviour) {
+            ChangeMaterialOnClick._startHiddenBehaviour =  
+                new BehaviorModel("StartHidden_" + this.selfModel.name,
+                    TriggerBuilder.sceneStartTrigger(),
+                    ActionBuilder.fadeAction(ChangeMaterialOnClick._parallelStartHiddenActions, fadeDuration, false));
+            ext.addBehavior(ChangeMaterialOnClick._startHiddenBehaviour);
+        }
     }
 
     private static getMaterialName(material: Material) {
@@ -526,9 +529,9 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                     sequence.push(ActionBuilder.fadeAction(selfModel, 0, false));
                 sequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));
 
-                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_toggleTo" + (targetState ? "On" : "Off"),
+                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"),
                     TriggerBuilder.tapTrigger(selfModel),
-                    ActionBuilder.parallel(...sequence)
+                    sequence.length > 1 ? ActionBuilder.parallel(...sequence) : sequence[0],
                 ));
             }
             // We have a toggleModel, so we need to set up two sequences:
@@ -540,7 +543,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                 toggleSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, true));
                 toggleSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));
 
-                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_toggleTo" + (targetState ? "On" : "Off"),
+                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"),
                     TriggerBuilder.tapTrigger(selfModel),
                     ActionBuilder.parallel(...toggleSequence)
                 ));
@@ -550,7 +553,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                 reverseSequence.push(ActionBuilder.fadeAction(selfModel, 0, true));
                 reverseSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, !targetState));
 
-                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_toggleTo" + (!targetState ? "On" : "Off"),
+                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (!targetState ? "On" : "Off"),
                     TriggerBuilder.tapTrigger(this.toggleModel),
                     ActionBuilder.parallel(...reverseSequence)
                 ));
@@ -565,10 +568,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
             if (this.toggleModel)
                 objectsToHide.push(this.toggleModel);
 
-            ext.addBehavior(new BehaviorModel("HideOnStart_" + this.gameObject.name,
-                TriggerBuilder.sceneStartTrigger(),
-                ActionBuilder.fadeAction(objectsToHide, 0, false)
-            ));
+            HideOnStart.add(objectsToHide, ext);
         }
     }
 
@@ -595,6 +595,27 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
  */
 export class HideOnStart extends Behaviour implements UsdzBehaviour {
 
+    private static _fadeBehaviour?: BehaviorModel;
+    private static _fadeObjects: Array<USDObject | Object3D> = [];
+
+    static add(target: Target, ext: BehaviorExtension) {
+        const arr = Array.isArray(target) ? target : [target];
+        for (const entry of arr) {
+            if (!HideOnStart._fadeObjects.includes(entry)) {
+                console.log("adding hide on start", entry);
+                HideOnStart._fadeObjects.push(entry);
+            }
+        }
+        if (HideOnStart._fadeBehaviour === undefined) {
+            HideOnStart._fadeBehaviour = new BehaviorModel("HideOnStart",
+                TriggerBuilder.sceneStartTrigger(),
+                //@ts-ignore
+                ActionBuilder.fadeAction(HideOnStart._fadeObjects, 0, false)
+            );
+            ext.addBehavior(HideOnStart._fadeBehaviour);
+        }
+    }
+
     start() {
         GameObject.setActive(this.gameObject, false);
     }
@@ -603,10 +624,7 @@ export class HideOnStart extends Behaviour implements UsdzBehaviour {
         if (model.uuid === this.gameObject.uuid) {
             // we only want to mark the object as HideOnStart if it's still hidden
             if (!this.wasVisible) {
-                ext.addBehavior(new BehaviorModel("HideOnStart_" + this.gameObject.name,
-                    TriggerBuilder.sceneStartTrigger(),
-                    ActionBuilder.fadeAction(model, 0, false)
-                ));
+                HideOnStart.add(model, ext);
             }
         }
     }
@@ -752,7 +770,7 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
             // automatically play audio on start too if the referenced AudioSource has playOnAwake enabled
             if (this.target && this.target.playOnAwake && this.target.enabled) {
                 if (anyChildHasGeometry && this.trigger === "tap") {
-                    // HACK Currently (20240509) we MUST not emit this behaviour if we're also expecting the tap trigger to work.
+                    // WORKAROUND Currently (20240509) we MUST not emit this behaviour if we're also expecting the tap trigger to work.
                     // Seems to be a regression in QuickLook... audio clips can't be stopped anymore as soon as they start playing.
                     console.warn("USDZExport: Audio sources that are played on tap can't also auto-play at scene start due to a QuickLook bug.");
                 }

package/src/engine-components/export/usdz/extensions/behavior/BehavioursBuilder.ts

@@ -199,11 +199,14 @@ function addInputTargetComponent(model: USDObject, options: { direct: boolean, i
 
 export class TriggerBuilder {
 
+    private static __sceneStartTrigger?: TriggerModel; 
+
     static sceneStartTrigger(): TriggerModel {
-        const trigger = new TriggerModel();
-        trigger.targetId = undefined;
+        if (this.__sceneStartTrigger !== undefined) return this.__sceneStartTrigger;
+        const trigger = new TriggerModel(undefined, "SceneStart");
         trigger.tokenId = "SceneTransition";
         trigger.type = "enter";
+        this.__sceneStartTrigger = trigger;
         return trigger;
     }
 

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

@@ -90,7 +90,7 @@ export class Button extends Behaviour implements IPointerEventHandler {
         else if (this.transition === Transition.ColorTint && this.colors) {
             this._image?.setState("hovered");
         }
-        if (canSetCursor) this.context.input.setCursorPointer();
+        if (canSetCursor) this.context.input.setCursor("pointer");
     }
 
     onPointerExit() {
@@ -107,7 +107,7 @@ export class Button extends Behaviour implements IPointerEventHandler {
         else if (this.transition === Transition.ColorTint && this.colors) {
             this._image?.setState("normal");
         }
-        this.context.input.setCursorNormal();
+        this.context.input.unsetCursor("pointer");
     }
 
     onPointerDown(_) {
@@ -211,7 +211,7 @@ export class Button extends Behaviour implements IPointerEventHandler {
     }
 
     onDestroy(): void {
-        if (this._isHovered) this.context.input.setCursorNormal();
+        if (this._isHovered) this.context.input.unsetCursor("pointer");
     }
 
     private _requestedAnimatorTrigger?: string;

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

@@ -1,11 +1,12 @@
-import { type Intersection, Mesh,Object3D } from "three";
+import { type Intersection, Mesh, Object3D } from "three";
 
 import { isDevEnvironment, showBalloonMessage } from "../../engine/debug/index.js";
-import { type InputEventNames, InputEvents, NEPointerEvent, NEPointerEventIntersection,PointerType } from "../../engine/engine_input.js";
+import { type InputEventNames, InputEvents, NEPointerEvent, NEPointerEventIntersection, PointerType } from "../../engine/engine_input.js";
+import { onInitialized } from "../../engine/engine_lifecycle_api.js";
 import { Mathf } from "../../engine/engine_math.js";
 import { RaycastOptions, type RaycastTestObjectReturnType } from "../../engine/engine_physics.js";
 import { Context } from "../../engine/engine_setup.js";
-import type { IComponent } from "../../engine/engine_types.js";
+import { HideFlags, type IComponent } from "../../engine/engine_types.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour, GameObject } from "../Component.js";
 import { $shadowDomOwner } from "./BaseUIComponent.js";
@@ -30,47 +31,15 @@ export declare type AfterHandleInputEvent = {
 
 declare type IComponentCanMaybeReceiveEvents = IPointerEventHandler & IComponent & { interactable?: boolean };
 
+onInitialized((ctx) => {
+    EventSystem.createIfNoneExists(ctx);
+})
+
 /**
  * @category User Interface
  * @group Components
  */
 export class EventSystem extends Behaviour {
-    private static _eventSystemMap = new Map<Context, EventSystem[]>();
-
-    static didSearchEventSystem: boolean = false;
-    static createIfNoneExists(context: Context) {
-        if (!this.didSearchEventSystem) {
-            this.didSearchEventSystem = true;
-            if (EventSystem.systems.length <= 0) {
-                EventSystem.systems.push(...GameObject.findObjectsOfType(EventSystem, context));
-            }
-        }
-        for (const sys of EventSystem.systems) {
-            if (sys.context === context) return; // exists
-        }
-        const go = new Object3D();
-        GameObject.addComponent(go, EventSystem);
-        context.scene.add(go);
-    }
-
-    static get systems(): EventSystem[] {
-        const context = Context.Current;
-        if (!this._eventSystemMap.has(context)) {
-            this._eventSystemMap.set(context, []);
-        }
-        return this._eventSystemMap.get(context)!;
-    }
-
-    static get(ctx: Context): EventSystem | null {
-        const systems = this._eventSystemMap.get(ctx);
-        if (systems && systems.length > 0) return systems[0];
-        return null;
-    }
-
-    static get instance(): EventSystem | null {
-        return this.systems[0];
-    }
-
     //@ts-ignore
     static ensureUpdateMeshUI(instance, context: Context, force: boolean = false) {
         MeshUIHelper.update(instance, context, force);
@@ -79,32 +48,22 @@ export class EventSystem extends Behaviour {
         MeshUIHelper.markDirty();
     }
 
-    private raycaster: Raycaster[] = [];
-
-    constructor() {
-        super();
-        EventSystem.systems.push(this);
+    static createIfNoneExists(context: Context) {
+        if (!context.scene.getComponent(EventSystem)) {
+            context.scene.addComponent(EventSystem);
+        }
     }
 
-    get hasActiveUI() { return this.currentActiveMeshUIComponents.length > 0; }
-    get isHoveringObjects() { return this.hoveredByID.size > 0; }
-
-    onDestroy(): void {
-        EventSystem.systems.splice(EventSystem.systems.indexOf(this), 1);
+    static get(ctx: Context): EventSystem | null {
+        this.createIfNoneExists(ctx);
+        return ctx.scene.getComponent(EventSystem);
     }
 
-    start() {
-        if (this.raycaster.length <= 0) {
-            const res = GameObject.findObjectOfType(Raycaster, this.context);
-            if (!res) {
-                const rc = GameObject.addComponent(this.context.scene, ObjectRaycaster);
-                this.raycaster.push(rc);
-                if (isDevEnvironment() || debug)
-                    console.warn("Added an ObjectRaycaster to the scene because no raycaster was found.");
-            }
-        }
+    static get instance(): EventSystem | null {
+        return this.get(Context.Current);
     }
 
+    private readonly raycaster: Raycaster[] = [];
     register(rc: Raycaster) {
         if (rc && this.raycaster && !this.raycaster.includes(rc))
             this.raycaster?.push(rc);
@@ -116,6 +75,23 @@ export class EventSystem extends Behaviour {
         }
     }
 
+    get hasActiveUI() { return this.currentActiveMeshUIComponents.length > 0; }
+    get isHoveringObjects() { return this.hoveredByID.size > 0; }
+
+    awake(): void {
+        // We only want ONE eventsystem on the root scene
+        // as long as this component is not implemented in core we need to check this here
+        if (this.gameObject as Object3D !== this.context.scene) {
+            this.enabled = false;
+        }
+    }
+
+    start() {
+        if (!this.context.scene.getComponent(Raycaster)) {
+            this.context.scene.addComponent(ObjectRaycaster);
+        }
+    }
+
     onEnable(): void {
         this.context.input.addEventListener(InputEvents.PointerDown, this.onPointerEvent);
         this.context.input.addEventListener(InputEvents.PointerUp, this.onPointerEvent);
@@ -183,7 +159,6 @@ export class EventSystem extends Behaviour {
             options.screenPoint = this.context.input.getPointerPositionRC(pointerEvent.pointerId)!;
         }
 
-
         const hits = this.performRaycast(options) as Array<NEPointerEventIntersection>;
         if (hits) {
             for (const hit of hits) {
@@ -242,6 +217,14 @@ export class EventSystem extends Behaviour {
         // TODO: this implementation below should be removed and we should regularly raycast objects in the scene unless marked as "do not raycast"
         // with the introduction of the mesh-bvh based raycasting the performance impact should be greatly reduced. But this needs further testing 
 
+        const raycasterOnObject = obj && "getComponent" in obj ? obj.getComponent(Raycaster) : null;
+        if (raycasterOnObject && raycasterOnObject != this._currentlyActiveRaycaster) {
+            return false;
+        }
+        // if (this._currentPointerEventName == "pointermove") {
+        //     console.log(this.context.time.frame, obj.name, obj.type, obj.guid)
+        // }
+
         // check if this object is actually a UI shadow hierarchy object
         let uiOwner: Object3D | null = null;
         const isUI = isUIObject(obj);
@@ -450,7 +433,7 @@ export class EventSystem extends Behaviour {
                     isShadow = true;
                 }
             }
-            
+
             // adding this to have a way for allowing to receive events on TMUI elements without shadow hierarchy
             // if(parent["needle:use_eventsystem"] == true){
             //     // if use_eventsystem is true, we want to handle the event
@@ -671,7 +654,7 @@ export class EventSystem extends Behaviour {
             comp[symbol] = state;
             return true;
         }
-        else {
+        else {
             if (!state || !state.includes(pointerId)) return false;
             const i = state.indexOf(pointerId);
             if (i !== -1) {

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

@@ -3,7 +3,7 @@ import { FrameEvent } from "../../engine/engine_setup.js";
 import { DeviceUtilities, getParam } from "../../engine/engine_utils.js";
 import { Behaviour, GameObject } from "../Component.js";
 import { EventList } from "../EventList.js";
-import { type IPointerEventHandler } from "./PointerEvents.js";
+import { type IPointerEventHandler,PointerEventData } from "./PointerEvents.js";
 import { Text } from "./Text.js";
 import { tryGetUIComponent } from "./Utils.js";
 
@@ -113,6 +113,14 @@ export class InputField extends Behaviour implements IPointerEventHandler {
         this.onDeselected();
     }
 
+    onPointerEnter(_args: PointerEventData) {
+        const canSetCursor = _args.event.pointerType === "mouse" && _args.button === 0;
+        if(canSetCursor) this.context.input.setCursor("text");
+    }
+    onPointerExit(_args: PointerEventData) {
+        this.context.input.unsetCursor("text")
+    }
+
     onPointerClick(_args) {
         if (debug) console.log("CLICK", _args, InputField.active);
         InputField.activeTime = this.context.time.time;

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

@@ -91,12 +91,12 @@ export class OpenURL extends Behaviour implements IPointerClickHandler {
     /** @internal */
     onPointerEnter(args) {
         if (!args.used && this.clickable)
-            this.context.input.setCursorPointer();
+            this.context.input.setCursor("pointer");
     }
     /** @internal */
     onPointerExit() {
         if (this.clickable)
-            this.context.input.setCursorNormal();
+            this.context.input.unsetCursor("pointer");
     }
     /** @internal */
     onPointerClick(args: PointerEventData) {

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

@@ -160,9 +160,13 @@ class ImageTrackingExtension implements IUSDExporterExtension {
     }
 
     onAfterHierarchy(_context: USDZExporterContext, writer: USDWriter) {
+        const iOSVersion = DeviceUtilities.getiOSVersion();
+        const majorVersion = iOSVersion ? parseInt(iOSVersion.split(".")[0]) : 18;
+        const workaroundForFB16119331 = majorVersion >= 18;
+        const multiplier = workaroundForFB16119331 ? 1 : 100;
         writer.beginBlock(`def Preliminary_ReferenceImage "AnchoringReferenceImage"`);
         writer.appendLine(`uniform asset image = @image_tracking/` + this.filename + `@`);
-        writer.appendLine(`uniform double physicalWidth = ` + (this.widthInMeters * 100).toFixed(8));
+        writer.appendLine(`uniform double physicalWidth = ` + (this.widthInMeters * multiplier).toFixed(8));
         writer.closeBlock();
     }
 

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

@@ -364,7 +364,7 @@ export class WebXRPlaneTracking extends Behaviour {
                     if (newPlane instanceof Mesh) {
                         disposeObjectResources(newPlane.geometry);
                         newPlane.geometry = this.createGeometry(data);
-                        this.makeOccluder(newPlane, newPlane.material, this.occluder);
+                        this.makeOccluder(newPlane, newPlane.material, this.occluder && !this.dataTemplate);
                     }
                     else if (newPlane instanceof Group) {
                         // We want to process only one level of children on purpose here
@@ -372,7 +372,7 @@ export class WebXRPlaneTracking extends Behaviour {
                             if (ch instanceof Mesh) {
                                 disposeObjectResources(ch.geometry);
                                 ch.geometry = this.createGeometry(data);
-                                this.makeOccluder(ch, ch.material, this.occluder);
+                                this.makeOccluder(ch, ch.material, this.occluder && !this.dataTemplate);
                             }
                         }
                     }

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

@@ -71,6 +71,9 @@ export class XRControllerFollow extends Behaviour {
 
     /** @internal */
     onUpdateXR(args: NeedleXREventArgs): void {
+        // explicit check since we're overriding activeAndEnabled
+        if (!this.enabled) return;
+
         // try to get the controller
         const ctrl = args.xr.getController(this.side);
         if (ctrl) {

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

@@ -113,6 +113,7 @@ export class XRControllerModel extends Behaviour {
             }
         }
     }
+
     onXRControllerRemoved(args: NeedleXRControllerEventArgs): void {
         console.debug("XR Controller Removed", args.controller.side, args.controller.index);
         // we need to find the index by the controller because if controller 0 is removed first then args.controller.index 1 will be at index 0
@@ -128,6 +129,19 @@ export class XRControllerModel extends Behaviour {
             entry.model = undefined;
         }
     }
+
+    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
+        // When a custom hand model is used, we want to ensure we're requesting hand tracking,
+        // even when the platform default doesn't include it (for example, on VisionOS we don't
+        // request hand tracking by default because there's an additional permissions dialogue.
+        if (this.createHandModel && (this.customLeftHand || this.customRightHand)) {
+            args.optionalFeatures = args.optionalFeatures || [];
+            if (!args.optionalFeatures.includes("hand-tracking")) {
+                args.optionalFeatures.push("hand-tracking");
+            }
+        }
+    }
+
     onLeaveXR(_args: NeedleXREventArgs): void {
         for (const entry of this._models) {
             if (!entry) continue;
@@ -145,6 +159,7 @@ export class XRControllerModel extends Behaviour {
         }
         this._models.length = 0;
     }
+
     onBeforeRender() {
         if (!NeedleXRSession.active) return;