docs: Improve locomotion hook documentation

packages/react/xr/package.json

@@ -33,7 +33,7 @@
   },
   "devDependencies": {
     "@react-three/fiber": "rc",
-    "typedoc": "^0.28.3",
+    "typedoc": "^0.28.7",
     "typedoc-plugin-frontmatter": "^1.3.0",
     "typedoc-plugin-markdown": "^4.6.3"
   },

packages/react/xr/plugins/pretty-md.mjs

@@ -1,25 +1,25 @@
 import fs from 'fs'
 import { dirname, join, resolve } from 'path'
+import { fileURLToPath } from 'url'
 import { Converter } from 'typedoc'
 import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown'
-import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
 const kindsToExclude = [
-  1, //"Project"
-  2, //"Module"
-  4, //"Namespace"
-  8388608, //"Document"
+  1, // "Project"
+  2, // "Module"
+  4, // "Namespace"
+  8388608, // "Document"
 ]
 
 export const load = (app) => {
-  app.converter.on(Converter.EVENT_RESOLVE_END, (whatami) => {
+  app.converter.on(Converter.EVENT_RESOLVE_END, () => {
     // Happens before the MarkdownPageEvents
   })
 
   app.renderer.markdownHooks.on('page.begin', (page) => {
-    let deprecatedTag = undefined
+    let deprecatedTag
     if (page.page?.model?.comment) {
       deprecatedTag = page.page.model.comment.blockTags.find((t) => t.tag === '@deprecated')
     } else if (page.page?.model?.signatures) {
@@ -28,7 +28,6 @@ export const load = (app) => {
     if (deprecatedTag) {
       return `> [!CAUTION]\n> Deprecated: ${deprecatedTag.content.reduce((p, x) => p + x.text, '')}\n\n`
     }
-    return
   })
 
   app.renderer.on(MarkdownPageEvent.BEGIN, (page) => {
@@ -67,13 +66,15 @@ export const load = (app) => {
       /#### `(.*)` - (.*)/g,
       '<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**$1**</span>\n\n$2\n',
     )
+
     // Shrink headers that should be smaller, and tweak the color
     // page.contents = page.contents.replace(/####? (.*)\n/g, '**$1**\n')
     // NOTE: This here is another option for the above, tweaks the param color and size
     page.contents = page.contents.replace(
       /####? (.*)\n/g,
       '<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**$1**</span>\n',
     )
+
     // Add a divider after Returns
     page.contents = page.contents.replace(/## Returns\n\n/g, '## Returns\n---\n')
   })

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

@@ -23,6 +23,46 @@ import { useXRStore } from './xr.js'
  * #### `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'.
+ * @example 
+ * // Example showing basic usage
+ * export const userMovement = () => {
+ *   const originRef = useRef<THREE.Group>(null);
+ *   useXRControllerLocomotion(originRef);
+ *   return <XROrigin ref={originRef} />
+ * }
+ *
+ * // Example using rapier physics
+ * export const userMovementWithPhysics = () => {
+ *   const userRigidBodyRef = useRef<RapierRigidBody>(null);
+ *
+ *   const userMove = (inputVector: Vector3, rotationInfo: Euler) => {
+ *   if (userRigidBodyRef.current) {
+ *      const currentLinvel = userRigidBodyRef.current.linvel()
+ *      const newLinvel = { x: inputVector.x, y: currentLinvel.y, z: inputVector.z }
+ *      userRigidBodyRef.current.setLinvel(newLinvel, true)
+ *      userRigidBodyRef.current.setRotation(new Quaternion().setFromEuler(rotationInfo), true)
+ *    }
+ *  }
+
+ *  useXRControllerLocomotion(userMove)
+
+ *  return <>
+ *    <RigidBody
+ *      ref={userRigidBodyRef}
+ *      colliders={false}
+ *      type='dynamic'
+ *      position={[0, 2, 0]}
+ *      enabledRotations={[false, false, false]}
+ *      canSleep={false}
+ *    >
+ *      <CapsuleCollider args={[.3, .5]} />
+ *      <XROrigin position={[0, -1, 0]} />
+ *    </RigidBody>
+ *  </>
+ * } 
+ * 
+ * @see {@link https://pmndrs.github.io/xr/examples/minecraft/ | demo}
+ * @see {@link https://github.com/pmndrs/xr/blob/main/examples/minecraft/src/VRPlayerControl.tsx | source for demo}
  */
 export function useXRControllerLocomotion(
   target:

packages/react/xr/src/xr.tsx

@@ -154,7 +154,8 @@ export function UNSAFE_useXRStore() {
 }
 
 /**
- * Hook for reading the state from the xr store
+ * Used to access all state related to the XR session.
+ * @see {@link https://pmndrs.github.io/xr/docs/tutorials/store}
  */
 export function useXR<T = XRState>(
   selector: (s: XRState) => T = (state) => state as unknown as T,