@needle-tools/engine 5.1.6 → 5.1.8

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/WebARSessionRoot.ts

@@ -18,6 +18,22 @@ const debug = getParam("debugwebxr");
 
 const invertForwardMatrix = new Matrix4().makeRotationY(Math.PI);
 
+/** a XRRigidTransform pose stored as plain values — XR hit test results and frames are only
+ * valid within the animation frame that produced them, so poses that need to survive until a
+ * later frame (or an input event) must be snapshotted */
+type XRAnchorRefPose = { x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number };
+
+const unitScale = new Vector3(1, 1, 1);
+const tempAnchorPose = new Matrix4();
+const tempAnchorDelta = new Matrix4();
+
+function matrixApproximatelyEquals(a: Matrix4, b: Matrix4, epsilon: number = 1e-6): boolean {
+    for (let i = 0; i < 16; i++) {
+        if (Math.abs(a.elements[i] - b.elements[i]) > epsilon) return false;
+    }
+    return true;
+}
+
 
 /**
  * The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.  
@@ -101,11 +117,12 @@ export class WebARSessionRoot extends Behaviour {
     /** When enabled the scene center will be automatically calculated from the content in the scene */
     autoCenter: boolean = false;
 
-    /** Experimental: When enabled we will create a XR anchor for the scene placement    
-     * and make sure the scene is at that anchored point during a XR session 
-     * @default false
+    /** When enabled a XR anchor is created at the scene placement position and the scene
+     * stays at that anchored point while tracking refines during the XR session.
+     * On platforms without WebXR anchor support this gracefully falls back to plain placement.
+     * @default true
      **/
-    useXRAnchor: boolean = false;
+    useXRAnchor: boolean = true;
 
     /** true if we're currently placing the scene */
     private _isPlacing = true;
@@ -125,13 +142,18 @@ export class WebARSessionRoot extends Behaviour {
 
     /** the reticles used for placement */
     private readonly _reticle: IGameObject[] = [];
-    /** needs to be in sync with the reticles */
-    private readonly _hits: XRHitTestResult[] = [];
+    /** reference-space hit poses, in sync with the reticles — captured while placing when {@link useXRAnchor}
+     * is enabled, because hit test results can not be used outside the animation frame that produced them */
+    private readonly _hitRefPoses: (XRAnchorRefPose | undefined)[] = [];
 
     private _placementStartTime: number = -1;
     private _rigPlacementMatrix?: Matrix4;
     /** if useAnchor is enabled this is the anchor we have created on placing the scene using the placement hit */
     private _anchor: XRAnchor | null = null;
+    /** the placement pose (reference space) waiting for anchor creation on the next animation frame */
+    private _pendingAnchorPose: XRAnchorRefPose | null = null;
+    /** the last anchor pose (in rig space) that has been applied to the rig */
+    private readonly _anchorLastLocalPose = new Matrix4();
     /** user input is used for ar touch transform */
     private userInput?: WebXRSessionRootUserInput;
 
@@ -147,6 +169,8 @@ export class WebARSessionRoot extends Behaviour {
         if (debug) console.log("ENTER WEBXR: SessionRoot start...");
 
         this._anchor = null;
+        this._pendingAnchorPose = null;
+        this._hitRefPoses.length = 0;
         WebARSessionRoot._hasPlaced = false;
 
         // if (_args.xr.session.enabledFeatures?.includes("image-tracking")) {
@@ -205,8 +229,9 @@ export class WebARSessionRoot extends Behaviour {
         // TODO: WebARSessionRoot doesnt work when we enter passthrough and leave XR without having placed the session!!!
         this.context.input.removeEventListener("pointerup", this.onPlaceScene, { queue: InputEventQueue.Early });
         this.onRevertSceneChanges();
-        // this._anchor?.delete();
+        // no explicit anchor.delete() — anchors are released by the platform when the session ends
         this._anchor = null;
+        this._pendingAnchorPose = null;
         WebARSessionRoot._hasPlaced = false;
         this._rigPlacementMatrix = undefined;
     }
@@ -252,20 +277,8 @@ export class WebARSessionRoot extends Behaviour {
 
         }
         else {
-            // Update anchors, if any
-            if (this._anchor && args.xr.referenceSpace) {
-                const pose = args.xr.frame.getPose(this._anchor.anchorSpace, args.xr.referenceSpace);
-                if (pose && this.context.time.frame % 20 === 0) {
-                    // apply the anchor pose to one of the reticles
-                    const converted = args.xr.convertSpace(pose.transform);
-                    const reticle = this._reticle[0];
-                    if (reticle) {
-                        reticle.position.copy(converted.position);
-                        reticle.quaternion.copy(converted.quaternion);
-                        this.onApplyPose(reticle);
-                    }
-                }
-            }
+            // create the anchor (deferred from placement) and keep the scene glued to it
+            if (this.useXRAnchor) this.updateXRAnchor(args.xr);
 
             // Scene has been placed
             if (this.arTouchTransform) {
@@ -286,9 +299,20 @@ export class WebARSessionRoot extends Behaviour {
         }
     }
 
-    private updateReticleAndHits(_xr: NeedleXRSession, i: number, hit: NeedleXRHitTestResult, scale: number) {
-        // save the hit test
-        this._hits[i] = hit.hit;
+    private updateReticleAndHits(xr: NeedleXRSession, i: number, hit: NeedleXRHitTestResult, scale: number) {
+        // capture the reference-space hit pose while the XRFrame that produced the hit is still
+        // active — it can not be queried anymore during placement (which runs from an input event)
+        if (this.useXRAnchor) {
+            const referenceSpace = xr.referenceSpace;
+            const rawPose = referenceSpace ? hit.hit.getPose(referenceSpace) : undefined;
+            if (rawPose) {
+                let pose = this._hitRefPoses[i];
+                if (!pose) pose = this._hitRefPoses[i] = { x: 0, y: 0, z: 0, qx: 0, qy: 0, qz: 0, qw: 1 };
+                const { position, orientation } = rawPose.transform;
+                pose.x = position.x; pose.y = position.y; pose.z = position.z;
+                pose.qx = orientation.x; pose.qy = orientation.y; pose.qz = orientation.z; pose.qw = orientation.w;
+            }
+        }
         let reticle = this._reticle[i];
         if (!reticle) {
             if (this.customReticle) {
@@ -392,14 +416,14 @@ export class WebARSessionRoot extends Behaviour {
             return;
         }
 
-        let hit = this._hits[0];
+        let hitIndex = 0;
 
         if (evt && evt.origin instanceof NeedleXRController) {
             // until we can use hit testing for both controllers and have multple reticles we only allow placement with the first controller
             const controllerReticle = this._reticle[evt.origin.index];
             if (controllerReticle) {
                 reticle = controllerReticle;
-                hit = this._hits[evt.origin.index];
+                hitIndex = evt.origin.index;
             }
         }
 
@@ -423,7 +447,15 @@ export class WebARSessionRoot extends Behaviour {
         WebARSessionRoot._hasPlaced = true;
 
         if (this.useXRAnchor) {
-            this.onCreateAnchor(NeedleXRSession.active!, hit);
+            // anchor creation is deferred to the next animation frame — see updateXRAnchor
+            const refPose = this._hitRefPoses[hitIndex];
+            if (refPose) {
+                this._pendingAnchorPose = { ...refPose };
+            }
+            else {
+                console.warn("[WebARSessionRoot] can not create a XR anchor: no hit pose was captured for the placement");
+                if (isDevEnvironment()) showBalloonWarning("Can not create XR anchor: no hit pose available");
+            }
         }
 
         if (this.context.xr) {
@@ -464,19 +496,73 @@ export class WebARSessionRoot extends Behaviour {
         }
     }
 
-    private async onCreateAnchor(session: NeedleXRSession, hit: XRHitTestResult) {
-        if (hit.createAnchor === undefined) {
-            console.warn("Hit does not support creating an anchor", hit);
-            if (isDevEnvironment()) showBalloonWarning("Hit does not support creating an anchor");
+    /**
+     * Deferred anchor creation and per-frame anchor tracking. Called from {@link onUpdateXR} after the scene has been placed.
+     *
+     * Creation can not happen during placement: `XRHitTestResult.createAnchor` only works while the animation
+     * frame that produced the hit is active, and placement runs from an input event where that frame is already
+     * over (`XRFrame.createAnchor` equally requires an active animation frame). So {@link onPlaceScene} only
+     * records the reference-space pose and the anchor is created here, on the next animation frame.
+     *
+     * Once the anchor exists, its pose *changes* (delta in rig space) are applied to the XR rig: the world pose
+     * of the anchored point stays constant while tracking refines, without discarding other rig modifications
+     * ({@link arTouchTransform} user adjustments, {@link arScale}).
+     */
+    private updateXRAnchor(xr: NeedleXRSession) {
+        const referenceSpace = xr.referenceSpace;
+        if (!referenceSpace) return;
+        const frame = xr.frame;
+
+        if (this._pendingAnchorPose) {
+            const pending = this._pendingAnchorPose;
+            this._pendingAnchorPose = null;
+            if (typeof frame.createAnchor !== "function" || xr.session.enabledFeatures?.includes("anchors") === false) {
+                // dev-only: useXRAnchor is enabled by default, so platforms without anchor
+                // support (e.g. iOS) would otherwise warn in every production session
+                if (debug || isDevEnvironment()) {
+                    console.warn("[WebARSessionRoot] useXRAnchor is enabled but WebXR anchors are not supported by this session");
+                    showBalloonWarning("WebXR anchors are not supported by this session");
+                }
+                return;
+            }
+            const transform = new XRRigidTransform({ x: pending.x, y: pending.y, z: pending.z }, { x: pending.qx, y: pending.qy, z: pending.qz, w: pending.qw });
+            // the anchor is created exactly at this pose — remember it (in rig space) as the baseline for deltas
+            const initialPose = xr.convertSpace(transform);
+            this._anchorLastLocalPose.compose(initialPose.position, initialPose.quaternion, unitScale);
+            frame.createAnchor(transform, referenceSpace).then(anchor => {
+                if (xr.running && !this._isPlacing) {
+                    this._anchor = anchor;
+                    if (debug) console.log("[WebARSessionRoot] created XR anchor", anchor);
+                }
+                else anchor.delete();
+            }).catch((err: unknown) => {
+                console.warn("[WebARSessionRoot] failed to create XR anchor", err);
+                if (isDevEnvironment()) showBalloonWarning("Failed to create XR anchor");
+            });
             return;
         }
-        else {
-            // @ts-ignore
-            const anchor = await hit.createAnchor(session.viewerPose!.transform);
-            // make sure the session is still active
-            if (session.running && anchor) {
-                this._anchor = anchor;
-            }
+
+        if (!this._anchor) return;
+        const rig = xr.rig?.gameObject;
+        if (!rig) return;
+        const pose = frame.getPose(this._anchor.anchorSpace, referenceSpace);
+        // the anchor may temporarily not be tracked — keep the last applied correction then
+        if (!pose) return;
+
+        const current = xr.convertSpace(pose.transform);
+        tempAnchorPose.compose(current.position, current.quaternion, unitScale);
+        if (matrixApproximatelyEquals(tempAnchorPose, this._anchorLastLocalPose)) return;
+
+        // rig_new = rig_old · lastPose · currentPose⁻¹ — keeps the world pose of the anchored
+        // point (rigWorld · anchorRigSpacePose) constant across tracking refinements
+        tempAnchorDelta.copy(tempAnchorPose).invert().premultiply(this._anchorLastLocalPose);
+        this._anchorLastLocalPose.copy(tempAnchorPose);
+        rig.updateMatrix();
+        rig.matrix.multiply(tempAnchorDelta);
+        rig.matrix.decompose(rig.position, rig.quaternion, rig.scale);
+        if (debug) {
+            const dx = tempAnchorDelta.elements[12], dy = tempAnchorDelta.elements[13], dz = tempAnchorDelta.elements[14];
+            console.log(`[WebARSessionRoot] applied XR anchor correction: ${(Math.hypot(dx, dy, dz) * 1000).toFixed(2)}mm`);
         }
     }
 

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

@@ -152,12 +152,12 @@ export class WebXR extends Behaviour {
     arScale: number = 1;
 
     /**
-     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.  
-     * This can help with spatial persistence in AR experiences.
-     * @experimental
+     * When enabled, an XRAnchor is created at the AR placement position and the scene stays glued to it while tracking refines.
+     * On platforms without WebXR anchor support this gracefully falls back to plain placement.
+     * @default true
      */
     @serializable()
-    useXRAnchor: boolean = false;
+    useXRAnchor: boolean = true;
 
     /**
      * When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,

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()