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

package/dist/needle-engine.d.ts

@@ -114,9 +114,9 @@ import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerM
 import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
-export declare const $componentName: unique symbol;
+/* Excluded from this release type: _$BbU */
 
-/* Excluded from this release type: _$lAjTeY */
+export declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
@@ -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).
  *
@@ -6376,8 +6379,6 @@ export declare class EnvironmentScene extends Scene {
     createAreaLightMaterial(intensity: number): MeshBasicMaterial;
 }
 
-/* Excluded from this release type: _ERXbX */
-
 /** An Euler value, either as a Three.js Euler or as a `[x, y, z]` tuple (radians) */
 declare type EulerValue = Euler | [number, number, number];
 
@@ -9054,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;
@@ -14747,8 +14748,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          effectDistance?: Vector2;
      }
 
-     /* Excluded from this release type: _owM */
-
      /** The Needle Engine networking server supports the concept of ownership that can be requested.
       * This enum contains possible outgoing (Request*) and incoming (Response*) events for communicating ownership.
       *
@@ -21477,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
@@ -24830,6 +24842,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      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;
 
@@ -24940,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
@@ -24963,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;