@directivegames/genesys.js 3.1.24

package/src/xr/VRPawn.ts

@@ -0,0 +1,815 @@
+/**
+ * VRPawn - a pawn specifically designed for VR experiences.
+ *
+ * Detailed explanation:
+ * - Extends the base Pawn class with VR-specific features
+ * - Manages VR controllers through VRControllerManager with visual representation
+ * - Integrates VR input with the unified InputManager system
+ * - Provides delegates for VR session and controller events
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use in VR games where controller representation and tracking is needed
+ * - Handle VR input through standard IInputHandler interface (PlayerController)
+ * - Subscribe to controller/session delegates for VR-specific events
+ */
+
+
+import * as THREE from 'three';
+
+import { Pawn } from '../actors/Pawn.js';
+import { CAMERA_FAR, CAMERA_FOV, CAMERA_NEAR, CHARACTER_HEIGHT } from '../const.js';
+import { EngineClass } from '../systems/ClassRegistry.js';
+import { Delegate } from '../utils/Delegate.js';
+
+// Target detection now based on components rather than VR-specific actor subclasses
+import { VRGrabbableComponent } from './actor-components/VRGrabbableComponent.js';
+import { VRInteractableComponent } from './actor-components/VRInteractableComponent.js';
+import { VRControllerManager } from './VRControllerManager.js';
+
+import type { VRActor } from './VRActor.js';
+import type { ControllerInfo, VRControllerOptions, XRAxis , XRButton, XRSqueezeEvent } from './VRControllerManager.js';
+import type { Actor } from '../actors/Actor.js';
+import type { PawnOptions } from '../actors/Pawn.js';
+
+export interface VRPawnOptions extends PawnOptions {
+  /** Options for the VR controller manager */
+  controllerOptions?: VRControllerOptions;
+  /** Enable teleportation feature */
+  enableTeleportation?: boolean;
+  /** Enable snap turning feature */
+  enableSnapTurn?: boolean;
+  /** Snap turn angle in degrees */
+  snapTurnAngle?: number;
+  /** Maximum teleportation distance */
+  maxTeleportDistance?: number;
+}
+
+/**
+ * Interface for actors that want to handle VR input
+ */
+export interface IVRInputHandler {
+  handleVRButtonDown?(inputSource: XRInputSource, button: XRButton, value: number): boolean;
+  handleVRButtonUp?(inputSource: XRInputSource, button: XRButton): boolean;
+  handleVRAxisChange?(inputSource: XRInputSource, axis: XRAxis, value: number): boolean;
+  handleSelectStart?(event: XRSqueezeEvent): boolean;
+  handleSelect?(event: XRSqueezeEvent): boolean;
+  handleSelectEnd?(event: XRSqueezeEvent): boolean;
+  handleSqueezeStart?(event: XRSqueezeEvent): boolean;
+  handleSqueeze?(event: XRSqueezeEvent): boolean;
+  handleSqueezeEnd?(event: XRSqueezeEvent): boolean;
+}
+
+
+@EngineClass('VRPawn')
+export class VRPawn extends Pawn<VRPawnOptions> {
+
+  private controllerManager: VRControllerManager | null = null;
+  private xrRenderer: THREE.WebGLRenderer | null = null;
+
+  // Registered VR input handlers with priorities
+  private vrInputHandlers: { handler: IVRInputHandler; priority: number; seq: number }[] = [];
+  private vrHandlerSeq: number = 0;
+
+  // WebXR reference space management
+  private baseReferenceSpace: XRReferenceSpace | null = null;
+  private currentReferenceSpace: XRReferenceSpace | null = null;
+
+  // Tracking space management for proper rotation around player
+  private trackingSpaceOriginInWorldSpace = new THREE.Vector3(0, 0, 0);
+  private trackingSpaceHeadingDegrees = 0;
+
+  // VR hand attachment state moved to VRGrabComponent
+
+  // Controller state (visibility flags) and velocity tracking
+  private hiddenControllers: Map<'left' | 'right', boolean> = new Map();
+  private controllerVelocities: Map<'left' | 'right', THREE.Vector3> = new Map();
+  private previousControllerPositions: Map<'left' | 'right', THREE.Vector3> = new Map();
+
+  private hoverActorByHand: { left: VRActor | null; right: VRActor | null } = { left: null, right: null };
+  private pendingTeleportTarget: THREE.Vector3 | null = null;
+  private frozenHeadLocalXZ: THREE.Vector3 | null = null;
+
+
+  /** Delegate fired when VR session starts */
+  public readonly onVRSessionStart: Delegate<[XRSession], void> = new Delegate();
+  /** Delegate fired when VR session ends */
+  public readonly onVRSessionEnd: Delegate<[], void> = new Delegate();
+  /** Delegate fired when a controller is added */
+  public readonly onControllerAdded: Delegate<[ControllerInfo], void> = new Delegate();
+  /** Delegate fired when a controller is removed */
+  public readonly onControllerRemoved: Delegate<[XRInputSource], void> = new Delegate();
+  /** Delegate fired when controller updates */
+  public readonly onControllerUpdated: Delegate<[XRInputSource, THREE.Object3D], void> = new Delegate();
+
+  constructor(options: VRPawnOptions = {} as VRPawnOptions) {
+    // Force a camera if not provided, and set a default position
+    const camera = options.camera ?? new THREE.PerspectiveCamera(CAMERA_FOV, 1, CAMERA_NEAR, CAMERA_FAR);
+    camera.position.set(0, CHARACTER_HEIGHT, 0);
+
+    const vrOptions = {
+      ...options,
+      camera: camera
+    };
+
+    super(vrOptions);
+
+    // Initialize controller manager - will be created when added to world
+    this.controllerManager = null; // Will be set in doBeginPlay
+  }
+
+  //====================================================================================================
+  // Public VR input handler registration
+  //====================================================================================================
+
+  public addVRInputHandler(handler: IVRInputHandler, priority: number = 0): void {
+    if (this.vrInputHandlers.some(e => e.handler === handler)) return;
+    this.vrInputHandlers.push({ handler, priority, seq: this.vrHandlerSeq++ });
+  }
+
+  public removeVRInputHandler(handler: IVRInputHandler): void {
+    const index = this.vrInputHandlers.findIndex(e => e.handler === handler);
+    if (index !== -1) {
+      this.vrInputHandlers.splice(index, 1);
+    }
+  }
+
+  public setVRInputHandlerPriority(handler: IVRInputHandler, priority: number): void {
+    const entry = this.vrInputHandlers.find(e => e.handler === handler);
+    if (entry) entry.priority = priority;
+  }
+
+  private getOrderedVRHandlers(): IVRInputHandler[] {
+    return this.vrInputHandlers
+      .slice()
+      .sort((a, b) => (b.priority - a.priority) || (a.seq - b.seq))
+      .map(e => e.handler);
+  }
+
+  /**
+   * Gets the VR controller manager
+   */
+  public getControllerManager(): VRControllerManager | null {
+    return this.controllerManager ?? null;
+  }
+
+  public isXRPresenting(): boolean {
+    return !!this.xrRenderer?.xr.isPresenting;
+  }
+
+  public isTeleportReady(): boolean {
+    if (!this.xrRenderer?.xr.isPresenting) return false;
+    const frame = this.xrRenderer.xr.getFrame();
+    const referenceSpace = this.xrRenderer.xr.getReferenceSpace();
+    return !!(frame && referenceSpace && this.baseReferenceSpace);
+  }
+
+  /** Capture or clear the head local XZ to use for the next teleport. */
+  public setTeleportHeadLocalXZ(xz: THREE.Vector3 | null): void {
+    this.frozenHeadLocalXZ = xz ? xz.clone() : null;
+  }
+
+  /** Get current head local XZ (relative to reference space), if available. */
+  public getCurrentHeadLocalPositionXZ(): THREE.Vector3 | null {
+    if (!this.xrRenderer?.xr.isPresenting) return null;
+    const frame = this.xrRenderer.xr.getFrame();
+    const referenceSpace = this.baseReferenceSpace ?? this.xrRenderer.xr.getReferenceSpace();
+    if (!frame || !referenceSpace) return null;
+    const viewerPose = frame.getViewerPose(referenceSpace);
+    if (!viewerPose) return null;
+    return new THREE.Vector3(
+      viewerPose.transform.position.x,
+      0,
+      viewerPose.transform.position.z
+    );
+  }
+
+  protected override doBeginPlay(): void {
+    super.doBeginPlay();
+
+    // Create controller manager now that we have a world (if not already created)
+    const world = this.getWorld();
+    if (world && !this.controllerManager) {
+      this.controllerManager = new VRControllerManager(world, this.options.controllerOptions);
+      this.setupControllerEventHandlers();
+    }
+
+    // Auto-setup VR tracking if XR is enabled in the game loop
+    const gameLoop = this.world?.gameLoop;
+    try {
+      if (gameLoop?.isXREnabled()) {
+        const threeRenderer = gameLoop?.renderer?.renderer;
+        if (threeRenderer) {
+          this.setupVRTracking(threeRenderer);
+        }
+      }
+    } catch (_e) {
+      console.error('[VRPawn] Failed to setup VR tracking:', _e);
+    }
+
+    // Always keep controllers updated automatically each frame
+    this.onTickPrePhysics.add(() => {
+      this.updateControllers();
+    });
+    this.onTickPostPhysics.add(() => {
+      if (this.pendingTeleportTarget && this.isTeleportReady()) {
+        const target = this.pendingTeleportTarget.clone();
+        this.pendingTeleportTarget = null;
+        const session = this.xrRenderer!.xr.getSession()!;
+        this.performWebXRTeleportation(session, target);
+      }
+    });
+  }
+
+  /**
+   * Setup event handlers for the controller manager
+   */
+  private setupControllerEventHandlers(): void {
+    // Forward controller manager events
+    this.controllerManager!.onControllerAdded.add((controllerInfo) => {
+      this.onControllerAdded.invoke(controllerInfo);
+    });
+
+    this.controllerManager!.onControllerRemoved.add((inputSource) => {
+      this.onControllerRemoved.invoke(inputSource);
+    });
+
+    this.controllerManager!.onControllerUpdated.add((inputSource, device) => {
+      this.onControllerUpdated.invoke(inputSource, new THREE.Object3D());
+    });
+  }
+
+  /**
+   * Setup direct VR input handling from VRControllerManager
+   */
+  private setupDirectVRInputHandling(): void {
+    if (!this.controllerManager) return;
+
+    // Connect to button events
+    this.controllerManager.onButtonDown.add((event) => {
+      this.handleVRButtonDown(event.inputSource, event.button, event.buttonState.value);
+    });
+
+    this.controllerManager.onButtonUp.add((event) => {
+      this.handleVRButtonUp(event.inputSource, event.button);
+    });
+
+    // Connect to axis events
+    this.controllerManager.onAxisChanged.add((event) => {
+      this.handleVRAxisChange(event.inputSource, event.axis, event.axisValue);
+    });
+
+    // Connect to WebXR gesture events
+    this.controllerManager.onSqueezeStart.add((event) => {
+      this.handleSqueezeStart(event);
+    });
+
+    this.controllerManager.onSqueeze.add((event) => {
+      this.handleSqueeze(event);
+    });
+
+    this.controllerManager.onSqueezeEnd.add((event) => {
+      this.handleSqueezeEnd(event);
+    });
+
+    this.controllerManager.onSelectStart.add((event) => {
+      this.handleSelectStart(event);
+    });
+
+    this.controllerManager.onSelect.add((event) => {
+      this.handleSelect(event);
+    });
+
+    this.controllerManager.onSelectEnd.add((event) => {
+      this.handleSelectEnd(event);
+    });
+  }
+
+  /**
+   * Gets controller info by handedness
+   */
+  public getControllerByHand(handedness: 'left' | 'right'): ControllerInfo | null {
+    return this.controllerManager!.getControllerByHand(handedness);
+  }
+
+  /**
+   * Gets all active controllers
+   */
+  public getControllers(): ControllerInfo[] {
+    return this.controllerManager!.getControllers();
+  }
+
+
+  /**
+   * Gets the target ray pose for a specific hand for raycasting
+   * @param hand The hand to get the ray pose for
+   * @returns Object with ray origin and direction, or null if not available
+   */
+  public getTargetRayPose(hand: 'left' | 'right'): { origin: THREE.Vector3; direction: THREE.Vector3 } | null {
+    if (!this.controllerManager) {
+      return null;
+    }
+
+    // Find the input source for this hand
+    const controller = this.getControllerByHand(hand);
+    if (!controller) {
+      return null;
+    }
+
+    // Get ray pose directly from input source
+    return this.controllerManager.getTargetRayPose(controller.inputSource);
+  }
+
+  /**
+   * Updates controllers (call this every frame)
+   */
+  public updateControllers(): void {
+    this.controllerManager!.updateControllers();
+    this.updateControllerVelocities();
+    (['left','right'] as const).forEach((hand) => this.updateVRHover(hand));
+  }
+
+  private updateVRHover(hand: 'left' | 'right'): void {
+    const rayPose = this.getTargetRayPose(hand);
+    if (!rayPose) return;
+    const target = this.findVRTargetAtRay(rayPose.origin, rayPose.direction);
+    const next = (target?.actor as VRActor) ?? null;
+    this.handleHoverTransition(hand, next, target?.rayHit?.hitLocation);
+  }
+
+  private handleHoverTransition(hand: 'left' | 'right', next: VRActor | null, point?: THREE.Vector3): void {
+    const prev = this.hoverActorByHand[hand];
+    if (prev !== next) {
+      if (prev?.onVRHoverEnd) prev.onVRHoverEnd(hand);
+      if (next?.onVRHoverStart && point) next.onVRHoverStart(hand, point);
+      this.hoverActorByHand[hand] = next;
+    } else if (next?.onVRHover && point) {
+      next.onVRHover(hand, point);
+    }
+  }
+
+
+  /**
+   * Sets up VR tracking with the provided renderer
+   */
+  public setupVRTracking(renderer: THREE.WebGLRenderer): void {
+    if (!renderer.xr.enabled) {
+      return;
+    }
+
+    // Store reference to the renderer for teleportation
+    this.xrRenderer = renderer;
+
+    // Ensure controller manager is created
+    if (!this.controllerManager && this.world) {
+      this.controllerManager = new VRControllerManager(this.world, this.options.controllerOptions);
+      this.setupControllerEventHandlers();
+    }
+
+    // Set up controller manager with the renderer and direct VR input handling
+    if (this.controllerManager) {
+      this.controllerManager.setupWithRenderer(renderer);
+      this.setupDirectVRInputHandling();
+    }
+
+    // Listen for session events to forward them
+    renderer.xr.addEventListener('sessionstart', () => {
+      const session = renderer.xr.getSession();
+      if (session) {
+        this.setupReferenceSpaces(session);
+        this.onVRSessionStart.invoke(session);
+      }
+    });
+
+    renderer.xr.addEventListener('sessionend', () => {
+      this.baseReferenceSpace = null;
+      this.currentReferenceSpace = null;
+      this.onVRSessionEnd.invoke();
+    });
+  }
+
+
+
+  /**
+   * Setup WebXR reference spaces for teleportation
+   */
+  private async setupReferenceSpaces(session: XRSession): Promise<void> {
+    try {
+      // Try to get local-floor reference space first
+      this.baseReferenceSpace = await session.requestReferenceSpace('local-floor');
+    } catch (e) {
+      try {
+        // Fallback to viewer space with floor offset
+        const viewerSpace = await session.requestReferenceSpace('viewer');
+        const floorOffset = new XRRigidTransform({x: 0, y: -1.5, z: 0});
+        this.baseReferenceSpace = viewerSpace.getOffsetReferenceSpace(floorOffset);
+      } catch (e2) {
+        console.error('[VRPawn] Failed to create reference space:', e2);
+        return;
+      }
+    }
+
+    // Initially, current reference space is the same as base
+    this.currentReferenceSpace = this.baseReferenceSpace;
+    // Ensure renderer uses our reference space immediately
+    if (this.xrRenderer) {
+      this.xrRenderer.xr.setReferenceSpace(this.currentReferenceSpace);
+    }
+  }
+
+  /**
+   * Handle VR button down events
+   */
+  public handleVRButtonDown(inputSource: XRInputSource, button: XRButton, value: number): boolean {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleVRButtonDown && handler.handleVRButtonDown(inputSource, button, value)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Handle VR button up events
+   */
+  public handleVRButtonUp(inputSource: XRInputSource, button: XRButton): boolean {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleVRButtonUp && handler.handleVRButtonUp(inputSource, button)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Handle VR axis changes for teleportation and snap turning
+   */
+  public handleVRAxisChange(inputSource: XRInputSource, axis: XRAxis, value: number): boolean {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleVRAxisChange && handler.handleVRAxisChange(inputSource, axis, value)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Perform WebXR teleportation by updating reference space
+   */
+  private performWebXRTeleportation(session: XRSession, targetPosition: THREE.Vector3): void {
+    if (!this.baseReferenceSpace || !this.xrRenderer) {
+      console.error('[VRPawn] No base reference space available');
+      return;
+    }
+
+    try {
+      const frame = this.xrRenderer.xr.getFrame();
+      const referenceSpace = this.baseReferenceSpace;
+      if (!frame || !referenceSpace) {
+        console.error('[VRPawn] No frame or reference space available for teleportation');
+        return;
+      }
+
+      // Get the current viewer pose to understand player's offset from tracking center
+      const viewerPose = frame.getViewerPose(referenceSpace);
+      if (!viewerPose) {
+        console.error('[VRPawn] No viewer pose available for teleportation');
+        return;
+      }
+
+      // Calculate player's feet position in world space using current heading and origin
+      const localXZ = this.frozenHeadLocalXZ ? this.frozenHeadLocalXZ.clone() : new THREE.Vector3(
+        viewerPose.transform.position.x,
+        0,
+        viewerPose.transform.position.z
+      );
+      const worldRotation = new THREE.Matrix4().makeRotationY(this.trackingSpaceHeadingDegrees * Math.PI / 180);
+      const rotatedXZ = localXZ.clone().applyMatrix4(worldRotation);
+      const playerInWorldSpaceOld = this.trackingSpaceOriginInWorldSpace.clone().add(rotatedXZ);
+
+      // Calculate offset from tracking space origin to player's feet (y stays 0)
+      const playerOffsetInWorldSpace = rotatedXZ.clone();
+
+      // Update tracking space origin so that origin + playerOffset == new target position
+      this.trackingSpaceOriginInWorldSpace.subVectors(targetPosition, playerOffsetInWorldSpace);
+
+      // Create the new reference space transform based on current heading and new position
+      const invOrientation = new THREE.Quaternion().setFromAxisAngle(
+        new THREE.Vector3(0, 1, 0),
+        -this.trackingSpaceHeadingDegrees * Math.PI / 180
+      );
+
+      const invPosition = this.trackingSpaceOriginInWorldSpace.clone().negate().applyQuaternion(invOrientation);
+
+      const teleportTransform = new XRRigidTransform(
+        {
+          x: invPosition.x,
+          y: invPosition.y,
+          z: invPosition.z
+        },
+        {
+          x: invOrientation.x,
+          y: invOrientation.y,
+          z: invOrientation.z,
+          w: invOrientation.w
+        }
+      );
+
+      // Create new offset reference space
+      this.currentReferenceSpace = this.baseReferenceSpace.getOffsetReferenceSpace(teleportTransform);
+
+      // Update the renderer's reference space
+      this.xrRenderer.xr.setReferenceSpace(this.currentReferenceSpace);
+
+      // Clear frozen head after applying teleport
+      this.frozenHeadLocalXZ = null;
+
+    } catch (error) {
+      console.error('[VRPawn] WebXR teleportation failed:', error);
+    }
+  }
+
+  //====================================================================================================
+  // Public helpers for rotation/teleportation invoked by components
+  //====================================================================================================
+
+  public getSnapTurnAngleDegrees(): number {
+    return this.options.snapTurnAngle ?? 90;
+  }
+
+  public yawByDegrees(degrees: number): void {
+    if (this.xrRenderer?.xr.isPresenting && this.currentReferenceSpace) {
+      const session = this.xrRenderer.xr.getSession();
+      if (session) {
+        this.performWebXRSnapTurnDegrees(session, degrees);
+        return;
+      }
+    }
+    const radians = (degrees * Math.PI) / 180;
+    this.rootComponent.rotateY(radians);
+  }
+
+  // Allow components to request a WebXR-relative teleport
+  public applyTeleportTo(targetPosition: THREE.Vector3): void {
+    if (this.isXRPresenting()) {
+      if (this.isTeleportReady()) {
+        const session = this.xrRenderer!.xr.getSession()!;
+        this.performWebXRTeleportation(session, targetPosition);
+      } else {
+        this.pendingTeleportTarget = targetPosition.clone();
+      }
+      return;
+    }
+    // In VR-only mode, do nothing if XR isn't presenting
+  }
+
+  /**
+   * Perform WebXR snap turn by an exact degree amount
+   */
+  private performWebXRSnapTurnDegrees(session: XRSession, degrees: number): void {
+    if (!this.baseReferenceSpace || !this.xrRenderer) {
+      console.error('[VRPawn] No base reference space available for snap turn');
+      return;
+    }
+
+    try {
+      const frame = this.xrRenderer.xr.getFrame();
+      const referenceSpace = this.currentReferenceSpace ?? this.baseReferenceSpace;
+      if (!frame || !referenceSpace) {
+        console.error('[VRPawn] No frame or reference space available for snap turn');
+        return;
+      }
+
+      const viewerPose = frame.getViewerPose(referenceSpace);
+      if (!viewerPose) {
+        console.error('[VRPawn] No viewer pose available for snap turn');
+        return;
+      }
+
+      const headPose = { transform: viewerPose.transform };
+
+      const rotationDelta = degrees;
+      const angleRadians = rotationDelta * Math.PI / 180;
+
+      const playerInWorldSpaceOld = new THREE.Vector3(
+        headPose.transform.position.x,
+        0,
+        headPose.transform.position.z
+      );
+
+      const playerOffsetInWorldSpaceOld = new THREE.Vector3();
+      playerOffsetInWorldSpaceOld.subVectors(playerInWorldSpaceOld, this.trackingSpaceOriginInWorldSpace);
+
+      const rotationMatrix = new THREE.Matrix4().makeRotationY(angleRadians);
+      const playerOffsetInWorldSpaceNew = playerOffsetInWorldSpaceOld.clone().applyMatrix4(rotationMatrix);
+
+      this.trackingSpaceHeadingDegrees += rotationDelta;
+
+      this.trackingSpaceOriginInWorldSpace.subVectors(playerInWorldSpaceOld, playerOffsetInWorldSpaceNew);
+
+      const invOrientation = new THREE.Quaternion().setFromAxisAngle(
+        new THREE.Vector3(0, 1, 0),
+        -this.trackingSpaceHeadingDegrees * Math.PI / 180
+      );
+
+      const invPosition = this.trackingSpaceOriginInWorldSpace.clone().negate().applyQuaternion(invOrientation);
+
+      const snapTurnTransform = new XRRigidTransform(
+        {
+          x: invPosition.x,
+          y: invPosition.y,
+          z: invPosition.z
+        },
+        {
+          x: invOrientation.x,
+          y: invOrientation.y,
+          z: invOrientation.z,
+          w: invOrientation.w
+        }
+      );
+
+      this.currentReferenceSpace = this.baseReferenceSpace.getOffsetReferenceSpace(snapTurnTransform);
+      this.xrRenderer.xr.setReferenceSpace(this.currentReferenceSpace);
+
+    } catch (error) {
+      console.error('[VRPawn] WebXR snap turn (degrees) failed:', error);
+    }
+  }
+
+  /**
+   * Get current hover target for a hand (if any)
+   */
+  public getHoverTarget(hand: 'left' | 'right'): { actor: VRActor; rayHit: any } | null {
+    const rayPose = this.getTargetRayPose(hand);
+    if (!rayPose) return null;
+    const target = this.findVRTargetAtRay(rayPose.origin, rayPose.direction);
+    if (target?.actor) {
+      return { actor: target.actor as VRActor, rayHit: target.rayHit };
+    }
+    return null;
+  }
+
+  // Legacy grip press/release removed; handled by external handlers/components
+
+  /**
+   * Handle WebXR squeeze start events (grab/pinch gestures)
+   */
+  private handleSqueezeStart(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSqueezeStart && handler.handleSqueezeStart(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Handle WebXR squeeze events (successful grab/pinch completion)
+   */
+  private handleSqueeze(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSqueeze && handler.handleSqueeze(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Handle WebXR squeeze end events (release gestures)
+   */
+  private handleSqueezeEnd(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSqueezeEnd && handler.handleSqueezeEnd(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Handle WebXR select start events (trigger/tap start)
+   */
+  private handleSelectStart(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSelectStart && handler.handleSelectStart(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Handle WebXR select events (trigger/tap completion)
+   */
+  private handleSelect(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSelect && handler.handleSelect(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Handle WebXR select end events (trigger/tap end)
+   */
+  private handleSelectEnd(event: XRSqueezeEvent): void {
+    for (const handler of this.getOrderedVRHandlers()) {
+      if (handler.handleSelectEnd && handler.handleSelectEnd(event)) {
+        return;
+      }
+    }
+  }
+
+  /**
+   * Unified VR target search along a ray. Prefers grabbables; falls back to interactables.
+   */
+  private findVRTargetAtRay(origin: THREE.Vector3, direction: THREE.Vector3): { type: 'grabbable' | 'interactable'; actor: any; rayHit: any } | null {
+    if (!this.world) return null;
+
+    // 1) Try physics-based hits for interactables (also gives us hit data)
+    const physicsEngine = this.world.getPhysicsEngine();
+    const hitResults = physicsEngine?.performHitTest({
+      origin,
+      direction,
+      maxDistance: 10,
+      stopOnFirstHit: false,
+      collisionProfile: null,
+      ignoredActors: [this],
+      ignoredComponents: []
+    }) ?? [];
+
+    // Prefer the closest grabbable among hits if any component exists on the actor
+    let bestGrabbable: { actor: Actor; distance: number } | null = null;
+    for (const hit of hitResults) {
+      const actor = hit.hitActor as Actor;
+      const comp = actor?.getComponent(VRGrabbableComponent);
+      if (comp) {
+        const dist = origin.distanceTo(hit.hitLocation);
+        if (!bestGrabbable || dist < bestGrabbable.distance) {
+          bestGrabbable = { actor, distance: dist };
+        }
+      }
+    }
+    if (bestGrabbable) {
+      // Recompute rayHit for the chosen actor by using the first hit that matches it
+      const rayHit = hitResults.find(h => h.hitActor === bestGrabbable!.actor) ?? hitResults[0];
+      return { type: 'grabbable', actor: bestGrabbable.actor, rayHit };
+    }
+
+    // 2) Otherwise, return closest interactable in range
+    for (const hit of hitResults) {
+      const actor = hit.hitActor as Actor;
+      const comp = actor?.getComponent(VRInteractableComponent) as VRInteractableComponent | null;
+      if (!comp) continue;
+      const interactionRange = comp.getVRInteractionRange();
+      if (origin.distanceTo(hit.hitLocation) <= interactionRange) {
+        return { type: 'interactable', actor, rayHit: hit };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get the current controller velocity estimate for a hand, if available
+   */
+  public getControllerVelocity(hand: 'left' | 'right'): THREE.Vector3 | null {
+    return this.controllerVelocities.get(hand) ?? null;
+  }
+
+  /**
+   * Track controller velocities for drop physics
+   */
+  private updateControllerVelocities(): void {
+    if (!this.xrRenderer?.xr.isPresenting) return;
+    const frame = this.xrRenderer.xr.getFrame();
+    const referenceSpace = this.xrRenderer.xr.getReferenceSpace();
+    if (!frame || !referenceSpace) return;
+    for (const hand of ['left','right'] as const) {
+      const controller = this.getControllerByHand(hand);
+      if (!controller?.inputSource.gripSpace) continue;
+      const gripPose = frame.getPose(controller.inputSource.gripSpace, referenceSpace);
+      if (!gripPose) continue;
+      const currentPosition = new THREE.Vector3(
+        gripPose.transform.position.x,
+        gripPose.transform.position.y,
+        gripPose.transform.position.z
+      );
+      const previousPosition = this.previousControllerPositions.get(hand);
+      if (previousPosition) {
+        const velocity = currentPosition.clone().sub(previousPosition).multiplyScalar(60);
+        this.controllerVelocities.set(hand, velocity);
+      }
+      this.previousControllerPositions.set(hand, currentPosition.clone());
+    }
+  }
+
+  /**
+   * Override destroy to clean up teleportation visuals and attachments
+   */
+  public override destroy(): void {
+    // Clean up attachments
+    for (const hand of ['left', 'right'] as const) {
+      const grabComps = this.getComponents(THREE.Object3D as any) as any[];
+      const detacher = grabComps.find(c => typeof (c as any).detachActorFromHand === 'function');
+      if (detacher) (detacher as any).detachActorFromHand(hand);
+    }
+    super.destroy();
+  }
+}