@needle-tools/engine 5.1.6 → 5.1.8

package/dist/needle-engine.d.ts

@@ -118,13 +118,13 @@ export declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
-/* Excluded from this release type: _$SVo */
-
 export declare class __Ignore {
 }
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
+/* Excluded from this release type: __sKHtRdk */
+
 /** Data describing the accessible semantics for a 3D object or component. */
 declare type AccessibilityData = {
     /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
@@ -11155,6 +11155,8 @@ declare class LowPassFilter {
     reset(value?: number): void;
 }
 
+/* Excluded from this release type: LuMYUbW */
+
 declare type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
 
 export declare class MainModule {
@@ -18040,8 +18042,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          evaluate(t01: number, t: number): number;
      }
 
-     /* Excluded from this release type: _RTmnPEj */
-
      export declare function sanitizeString(str: any): string;
 
      /** Download a image (must be a data url).
@@ -21475,23 +21475,36 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * 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
@@ -23538,6 +23551,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private updateDarkness;
      }
 
+     /* Excluded from this release type: _VIq */
+
      /**
       * Action to show or hide an object.
       * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
@@ -23982,9 +23997,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
          autoPlace: boolean;
          /** When enabled the scene center will be automatically calculated from the content in the scene */
          autoCenter: boolean;
-         /** 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;
          /** true if we're currently placing the scene */
@@ -23998,12 +24014,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private readonly _placementScene;
          /** the reticles used for placement */
          private readonly _reticle;
-         /** needs to be in sync with the reticles */
-         private readonly _hits;
+         /** 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;
          private _placementStartTime;
          private _rigPlacementMatrix?;
          /** if useAnchor is enabled this is the anchor we have created on placing the scene using the placement hit */
          private _anchor;
+         /** the placement pose (reference space) waiting for anchor creation on the next animation frame */
+         private _pendingAnchorPose;
+         /** the last anchor pose (in rig space) that has been applied to the rig */
+         private readonly _anchorLastLocalPose;
          /** user input is used for ar touch transform */
          private userInput?;
          onEnable(): void;
@@ -24015,7 +24036,19 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private onPlaceScene;
          private onSetScale;
          private onRevertSceneChanges;
-         private onCreateAnchor;
+         /**
+          * 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;
          private upVec;
          private lookPoint;
          private worldUpVec;
@@ -24129,9 +24162,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          arScale: number;
          /**
-          * 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
           */
          useXRAnchor: boolean;
          /**
@@ -24808,8 +24841,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          constructor(context: WebXRImageTracking, trackedImage: WebXRImageTrackingModel, bitmap: ImageBitmap, measuredSize: number, state: "tracked" | "emulated", pose: any);
      }
 
-     /* Excluded from this release type: _wHm */
-
      export declare type WriteCallback = (data: any, prop: string) => void;
 
      /** Button names as used in the xr profile */
@@ -24922,6 +24953,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * 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
@@ -24945,7 +24985,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @default true
           */
          usePinchToTeleport: boolean;
-         /** 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
           */
          useTeleportTarget: boolean;