deprecate useControllerLocomotion in favor of useXRControllerLocomotion

Author: bbohlender

docs/getting-started/all-hooks.md

@@ -141,7 +141,7 @@ Hook for getting the geometry from the detected plane.
 
 Hook for getting all detected planes with the provided semantic label.
 
-### `useControllerLocomotion`
+### `useXRControllerLocomotion`
 
 Hook for abstracting boilerplate needed to use controller based locomotion in XR.
 
@@ -159,7 +159,7 @@ Hook for abstracting boilerplate needed to use controller based locomotion in XR
 // Example showing basic usage
 export const userMovement = () => {
   const originRef = useRef<THREE.Group>(null);
-   useControllerLocomotion(originRef);
+   useXRControllerLocomotion(originRef);
   return <XROrigin ref={originRef} />
 }
 
@@ -176,7 +176,7 @@ export const userMovementWithPhysics = () => {
     }
   }
 
-  useControllerLocomotion(userMove)
+  useXRControllerLocomotion(userMove)
 
   return <>
     <RigidBody

examples/minecraft/src/VRPlayerControl.tsx

@@ -1,6 +1,6 @@
 import { useFrame } from '@react-three/fiber'
 import { Vector3Object } from '@react-three/rapier'
-import { useControllerLocomotion, useXRInputSourceState, XROrigin } from '@react-three/xr'
+import { useXRControllerLocomotion, useXRInputSourceState, XROrigin } from '@react-three/xr'
 import * as THREE from 'three'
 
 export function VRPlayerControl({
@@ -32,7 +32,7 @@ export function VRPlayerControl({
     })
   }
 
-  useControllerLocomotion(physicsMove, { speed: 5 })
+  useXRControllerLocomotion(physicsMove, { speed: 5 })
 
   useFrame(() => {
     if (controllerRight?.gamepad?.['a-button']?.state === 'pressed') {

examples/rag-doll/src/App.jsx

@@ -4,7 +4,7 @@ import { Physics, usePlane } from '@react-three/cannon'
 import { Cursor } from './helpers/Drag.js'
 import { Guy } from './components/Guy.jsx'
 import { Mug, Chair, Table, Lamp } from './components/Furniture.jsx'
-import { createXRStore, noEvents, useControllerLocomotion, XR, XROrigin, PointerEvents } from '@react-three/xr'
+import { createXRStore, noEvents, useXRControllerLocomotion, XR, XROrigin, PointerEvents } from '@react-three/xr'
 import { useRef, Suspense } from 'react'
 
 const store = createXRStore({
@@ -72,7 +72,7 @@ export function App() {
 
 function ControlledXROrigin() {
   const ref = useRef(null)
-  useControllerLocomotion(ref, { speed: 10 })
+  useXRControllerLocomotion(ref, { speed: 10 })
   return <XROrigin ref={ref} scale={10} />
 }
 

packages/react/xr/src/controller-locomotion.ts

@@ -2,9 +2,9 @@ import { RootState, useFrame } from '@react-three/fiber'
 import { RefObject, useMemo } from 'react'
 import { Vector3, Object3D } from 'three'
 import {
-  type ControllerLocomotionRotationOptions,
-  type ControllerLocomotionTranslationOptions,
-  createControllerLocomotionUpdate,
+  type XRControllerLocomotionRotationOptions,
+  type XRControllerLocomotionTranslationOptions,
+  createXRControllerLocomotionUpdate,
 } from '@pmndrs/xr/internals'
 import { useXRStore } from './xr.js'
 
@@ -20,16 +20,16 @@ import { useXRStore } from './xr.js'
  * @param rotationOptions.speed If `type` is 'smooth', this specifies the speed at which the user's view rotates.
  * @param translationControllerHand Specifies which hand will control the movement. Can be either 'left' or 'right'.
  */
-export function useControllerLocomotion(
+export function useXRControllerLocomotion(
   target:
     | RefObject<Object3D>
     | ((velocity: Vector3, rotationVelocityY: number, deltaTime: number, state: RootState, frame?: XRFrame) => void),
-  translationOptions: ControllerLocomotionTranslationOptions = {},
-  rotationOptions: ControllerLocomotionRotationOptions = {},
+  translationOptions: XRControllerLocomotionTranslationOptions = {},
+  rotationOptions: XRControllerLocomotionRotationOptions = {},
   translationControllerHand: Exclude<XRHandedness, 'none'> = 'left',
 ) {
   const store = useXRStore()
-  const update = useMemo(() => createControllerLocomotionUpdate(), [])
+  const update = useMemo(() => createXRControllerLocomotionUpdate(), [])
   useFrame((state, delta, frame: XRFrame | undefined) =>
     update(
       typeof target === 'function' ? target : target.current,

packages/xr/src/controller-locomotion.ts

@@ -1,18 +1,18 @@
 import { Vector3, Quaternion, Euler, MathUtils, Object3D, Camera } from 'three'
 import { XRControllerState, XRInputSourceState, XRStore } from './internals.js'
 
-export type ControllerLocomotionTranslationOptions =
+export type XRControllerLocomotionTranslationOptions =
   | {
       speed?: number
     }
   | boolean
-export type ControllerLocomotionRotationOptions =
+export type XRControllerLocomotionRotationOptions =
   | ({
       deadZone?: number
     } & ({ type?: 'snap'; degrees?: number } | { type: 'smooth'; speed?: number }))
   | boolean
 
-// useControllerLocomotion defaults and constants
+// useXRControllerLocomotion defaults and constants
 const defaultSpeed = 2
 const defaultSmoothTurningSpeed = 2
 const defaultSnapDegrees = 45
@@ -37,15 +37,15 @@ const scaleHelper = new Vector3()
  * @param rotationOptions.speed If `type` is 'smooth', this specifies the speed at which the user's view rotates.
  * @param translationControllerHand Specifies which hand will control the translation. Can be either 'left' or 'right'.
  */
-export function createControllerLocomotionUpdate() {
+export function createXRControllerLocomotionUpdate() {
   let canRotate = true
   return <T extends Array<any>>(
     target: Object3D | undefined | null | ((velocity: Vector3, rotationVelocityY: number, ...params: T) => void),
     store: XRStore<any>,
     camera: Camera,
     delta: number,
-    translationOptions: ControllerLocomotionTranslationOptions = {},
-    rotationOptions: ControllerLocomotionRotationOptions = {},
+    translationOptions: XRControllerLocomotionTranslationOptions = {},
+    rotationOptions: XRControllerLocomotionRotationOptions = {},
     translationControllerHand: Exclude<XRHandedness, 'none'> = 'left',
     ...params: T
   ) => {