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

package/dist/needle-engine.d.ts

@@ -114,12 +114,12 @@ import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerM
 import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
+/* Excluded from this release type: _$BbU */
+
 export declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
-/* Excluded from this release type: _$SVo */
-
 export declare class __Ignore {
 }
 
@@ -4119,8 +4119,9 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
      * 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
      * @param args Event data for the XR session
@@ -5805,6 +5806,8 @@ export declare class DocumentExtension implements IUSDExporterExtension {
     onAfterBuildDocument(_context: any): void;
 }
 
+/* Excluded from this release type: DpVN */
+
 /**
  * [DragControls](https://engine.needle.tools/docs/api/DragControls) enables interactive dragging of objects in 2D (screen space) or 3D (world space).
  *
@@ -9052,8 +9055,8 @@ export declare type INeedleXRSession = NeedleXRSession;
 export declare 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;
@@ -18040,8 +18043,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 +21476,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
@@ -23982,9 +23996,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 +24013,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 +24035,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 +24161,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,10 +24840,10 @@ 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;
 
+     /* Excluded from this release type: _WXkIc */
+
      /** Button names as used in the xr profile */
      export declare type XRControllerButtonName = "thumbrest" | "xr-standard-trigger" | "xr-standard-squeeze" | "xr-standard-thumbstick" | "xr-standard-touchpad" | "menu" | GamepadButtonName | StylusButtonName;
 
@@ -24922,6 +24954,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 +24986,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;