From c9574290a23ae64b85edd53fa966b4f549e19ee0 Mon Sep 17 00:00:00 2001 From: Kailean O'Keefe Date: Sat, 28 Jun 2025 10:20:46 -0600 Subject: [PATCH 1/2] docs: - Updated the controller-locomotion documentation - Updated the useXR hook - Updated some of the formatting settings --- .vscode/settings.json | 10 ++--- packages/react/xr/plugins/pretty-md.mjs | 17 ++++---- .../react/xr/src/controller-locomotion.ts | 40 +++++++++++++++++++ packages/react/xr/src/xr.tsx | 21 +++++++++- 4 files changed, 73 insertions(+), 15 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 8501715..dcfc44e 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,14 +1,12 @@ { - // enable ESLint only for this workspace "eslint.enable": true, - // Run the equivalent of `eslint --fix` each time you save + // Run the equivalent of `eslint --fix` each time you save, and disable vscode's + // built-in “Organize Imports” so it doesn’t fight ESLint. "editor.codeActionsOnSave": { - "source.fixAll.eslint": true + "source.organizeImports": "never", + "source.fixAll.eslint": "explicit" }, - - // Disable the built‑in “Organize Imports” so it doesn’t fight ESLint "editor.formatOnSave": false, - "typescript.preferences.organizeImports": false, } diff --git a/packages/react/xr/plugins/pretty-md.mjs b/packages/react/xr/plugins/pretty-md.mjs index 865ab3a..404c9bb 100644 --- a/packages/react/xr/plugins/pretty-md.mjs +++ b/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,6 +66,7 @@ export const load = (app) => { /#### `(.*)` - (.*)/g, '**$1**\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 @@ -74,6 +74,7 @@ export const load = (app) => { /####? (.*)\n/g, '**$1**\n', ) + // Add a divider after Returns page.contents = page.contents.replace(/## Returns\n\n/g, '## Returns\n---\n') }) diff --git a/packages/react/xr/src/controller-locomotion.ts b/packages/react/xr/src/controller-locomotion.ts index be97c67..639dc4b 100644 --- a/packages/react/xr/src/controller-locomotion.ts +++ b/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(null); + * useXRControllerLocomotion(originRef); + * return + * } + * + * // Example using rapier physics + * export const userMovementWithPhysics = () => { + * const userRigidBodyRef = useRef(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 <> + * + * + * + * + * + * } + * + * @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: diff --git a/packages/react/xr/src/xr.tsx b/packages/react/xr/src/xr.tsx index 02a53bd..f3aefc7 100644 --- a/packages/react/xr/src/xr.tsx +++ b/packages/react/xr/src/xr.tsx @@ -154,7 +154,26 @@ export function UNSAFE_useXRStore() { } /** - * Hook for reading the state from the xr store + * Used to access all state related to the XR session. + * @param body + * @param mode + * @param session + * @param origin + * @param originReferenceSpace + * @param domOverlayRoot + * @param detectedMeshes + * @param detectedPlanes + * @param frameRate + * @param visibilityState + * @param layerEntries + * @param emulator + * @param mediaBinding + * @param hand + * @param controller + * @param transientPointer + * @param gaze + * @param screenInput + * @function */ export function useXR( selector: (s: XRState) => T = (state) => state as unknown as T, From 052b4c5a8a5c743b8e5b7da11c2cb997b917eada Mon Sep 17 00:00:00 2001 From: Kailean O'Keefe Date: Mon, 7 Jul 2025 10:20:28 -0600 Subject: [PATCH 2/2] chore: Linked to the store tutorial in the useXR hook to give some visibility to the props --- packages/react/xr/package.json | 2 +- packages/react/xr/src/xr.tsx | 20 +------- pnpm-lock.yaml | 86 +++++++++++++++++----------------- 3 files changed, 45 insertions(+), 63 deletions(-) diff --git a/packages/react/xr/package.json b/packages/react/xr/package.json index 03cd65d..fe52b22 100644 --- a/packages/react/xr/package.json +++ b/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" }, diff --git a/packages/react/xr/src/xr.tsx b/packages/react/xr/src/xr.tsx index f3aefc7..83d9936 100644 --- a/packages/react/xr/src/xr.tsx +++ b/packages/react/xr/src/xr.tsx @@ -155,25 +155,7 @@ export function UNSAFE_useXRStore() { /** * Used to access all state related to the XR session. - * @param body - * @param mode - * @param session - * @param origin - * @param originReferenceSpace - * @param domOverlayRoot - * @param detectedMeshes - * @param detectedPlanes - * @param frameRate - * @param visibilityState - * @param layerEntries - * @param emulator - * @param mediaBinding - * @param hand - * @param controller - * @param transientPointer - * @param gaze - * @param screenInput - * @function + * @see {@link https://pmndrs.github.io/xr/docs/tutorials/store} */ export function useXR( selector: (s: XRState) => T = (state) => state as unknown as T, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8a0be4c..0fd619b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -432,14 +432,14 @@ importers: specifier: rc version: 9.0.0-rc.5(@types/react@19.0.8)(react-dom@19.0.0(react@19.0.0))(react@19.0.0)(three@0.173.0) typedoc: - specifier: ^0.28.3 - version: 0.28.3(typescript@5.7.3) + specifier: ^0.28.7 + version: 0.28.7(typescript@5.7.3) typedoc-plugin-frontmatter: specifier: ^1.3.0 - version: 1.3.0(typedoc-plugin-markdown@4.6.3(typedoc@0.28.3(typescript@5.7.3))) + version: 1.3.0(typedoc-plugin-markdown@4.6.3(typedoc@0.28.7(typescript@5.7.3))) typedoc-plugin-markdown: specifier: ^4.6.3 - version: 4.6.3(typedoc@0.28.3(typescript@5.7.3)) + version: 4.6.3(typedoc@0.28.7(typescript@5.7.3)) packages/xr: dependencies: @@ -751,8 +751,8 @@ packages: '@fortawesome/fontawesome-svg-core': ~1 || ~6 react: '>=16.3' - '@gerrit0/mini-shiki@3.3.0': - resolution: {integrity: sha512-frvArO0+s5Viq68uSod5SieLPVM2cLpXoQ1e07lURwgADXpL/MOypM7jPz9otks0g2DIe2YedDAeVrDyYJZRxA==} + '@gerrit0/mini-shiki@3.7.0': + resolution: {integrity: sha512-7iY9wg4FWXmeoFJpUL2u+tsmh0d0jcEJHAIzVxl3TG4KL493JNnisdLAILZ77zcD+z3J0keEXZ+lFzUgzQzPDg==} '@humanwhocodes/config-array@0.13.0': resolution: {integrity: sha512-DZLEEqFWQFiyK6h5YIeynKx7JlvCYWL0cImfSRXZ9l4Sg2efkFGTuFf6vzXjK1cq6IYkU+Eg/JizXw+TD2vRNw==} @@ -1051,17 +1051,17 @@ packages: '@rtsao/scc@1.1.0': resolution: {integrity: sha512-zt6OdqaDoOnJ1ZYsCYGt9YmWzDXl4vQdKTyJev62gFhRGKdx7mcT54V9KIjg+d2wi9EXsPvAPKe7i7WjfVWB8g==} - '@shikijs/engine-oniguruma@3.3.0': - resolution: {integrity: sha512-l0vIw+GxeNU7uGnsu6B+Crpeqf+WTQ2Va71cHb5ZYWEVEPdfYwY5kXwYqRJwHrxz9WH+pjSpXQz+TJgAsrkA5A==} + '@shikijs/engine-oniguruma@3.7.0': + resolution: {integrity: sha512-5BxcD6LjVWsGu4xyaBC5bu8LdNgPCVBnAkWTtOCs/CZxcB22L8rcoWfv7Hh/3WooVjBZmFtyxhgvkQFedPGnFw==} - '@shikijs/langs@3.3.0': - resolution: {integrity: sha512-zt6Kf/7XpBQKSI9eqku+arLkAcDQ3NHJO6zFjiChI8w0Oz6Jjjay7pToottjQGjSDCFk++R85643WbyINcuL+g==} + '@shikijs/langs@3.7.0': + resolution: {integrity: sha512-1zYtdfXLr9xDKLTGy5kb7O0zDQsxXiIsw1iIBcNOO8Yi5/Y1qDbJ+0VsFoqTlzdmneO8Ij35g7QKF8kcLyznCQ==} - '@shikijs/themes@3.3.0': - resolution: {integrity: sha512-tXeCvLXBnqq34B0YZUEaAD1lD4lmN6TOHAhnHacj4Owh7Ptb/rf5XCDeROZt2rEOk5yuka3OOW2zLqClV7/SOg==} + '@shikijs/themes@3.7.0': + resolution: {integrity: sha512-VJx8497iZPy5zLiiCTSIaOChIcKQwR0FebwE9S3rcN0+J/GTWwQ1v/bqhTbpbY3zybPKeO8wdammqkpXc4NVjQ==} - '@shikijs/types@3.3.0': - resolution: {integrity: sha512-KPCGnHG6k06QG/2pnYGbFtFvpVJmC3uIpXrAiPrawETifujPBv0Se2oUxm5qYgjCvGJS9InKvjytOdN+bGuX+Q==} + '@shikijs/types@3.7.0': + resolution: {integrity: sha512-MGaLeaRlSWpnP0XSAum3kP3a8vtcTsITqoEPYdt3lQG3YCdQH4DnEhodkYcNMcU0uW0RffhoD1O3e0vG5eSBBg==} '@shikijs/vscode-textmate@10.0.2': resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} @@ -3088,8 +3088,8 @@ packages: peerDependencies: typedoc: 0.28.x - typedoc@0.28.3: - resolution: {integrity: sha512-5svOCTfXvVSh6zbZKSQluZhR8yN2tKpTeHZxlmWpE6N5vc3R8k/jhg9nnD6n5tN9/ObuQTojkONrOxFdUFUG9w==} + typedoc@0.28.7: + resolution: {integrity: sha512-lpz0Oxl6aidFkmS90VQDQjk/Qf2iw0IUvFqirdONBdj7jPSN9mGXhy66BcGNDxx5ZMyKKiBVAREvPEzT6Uxipw==} engines: {node: '>= 18', pnpm: '>= 10'} hasBin: true peerDependencies: @@ -3272,16 +3272,16 @@ packages: yallist@3.1.1: resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==} - yaml@2.7.0: - resolution: {integrity: sha512-+hSoy/QHluxmC9kCIJyL/uyFmLmc+e5CFR5Wa+bpIhIj85LVb9ZH2nVnqrHoSvKogwODv0ClqZkmiSSaIH5LTA==} - engines: {node: '>= 14'} - hasBin: true - yaml@2.7.1: resolution: {integrity: sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==} engines: {node: '>= 14'} hasBin: true + yaml@2.8.0: + resolution: {integrity: sha512-4lLa/EcQCB0cJkyts+FpIRx5G/llPxfP6VQU5KByHEhLxY3IJCH0f0Hy1MHI8sClTvsIb8qwRJ6R/ZdlDJ/leQ==} + engines: {node: '>= 14.6'} + hasBin: true + yargs-parser@20.2.9: resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==} engines: {node: '>=10'} @@ -3588,12 +3588,12 @@ snapshots: prop-types: 15.8.1 react: 18.3.1 - '@gerrit0/mini-shiki@3.3.0': + '@gerrit0/mini-shiki@3.7.0': dependencies: - '@shikijs/engine-oniguruma': 3.3.0 - '@shikijs/langs': 3.3.0 - '@shikijs/themes': 3.3.0 - '@shikijs/types': 3.3.0 + '@shikijs/engine-oniguruma': 3.7.0 + '@shikijs/langs': 3.7.0 + '@shikijs/themes': 3.7.0 + '@shikijs/types': 3.7.0 '@shikijs/vscode-textmate': 10.0.2 '@humanwhocodes/config-array@0.13.0': @@ -3983,20 +3983,20 @@ snapshots: '@rtsao/scc@1.1.0': {} - '@shikijs/engine-oniguruma@3.3.0': + '@shikijs/engine-oniguruma@3.7.0': dependencies: - '@shikijs/types': 3.3.0 + '@shikijs/types': 3.7.0 '@shikijs/vscode-textmate': 10.0.2 - '@shikijs/langs@3.3.0': + '@shikijs/langs@3.7.0': dependencies: - '@shikijs/types': 3.3.0 + '@shikijs/types': 3.7.0 - '@shikijs/themes@3.3.0': + '@shikijs/themes@3.7.0': dependencies: - '@shikijs/types': 3.3.0 + '@shikijs/types': 3.7.0 - '@shikijs/types@3.3.0': + '@shikijs/types@3.7.0': dependencies: '@shikijs/vscode-textmate': 10.0.2 '@types/hast': 3.0.4 @@ -5674,7 +5674,7 @@ snapshots: postcss-load-config@4.0.2(postcss@8.4.31)(ts-node@10.9.2(@types/node@22.13.0)(typescript@5.7.3)): dependencies: lilconfig: 3.1.3 - yaml: 2.7.0 + yaml: 2.7.1 optionalDependencies: postcss: 8.4.31 ts-node: 10.9.2(@types/node@22.13.0)(typescript@5.7.3) @@ -6291,23 +6291,23 @@ snapshots: possible-typed-array-names: 1.0.0 reflect.getprototypeof: 1.0.10 - typedoc-plugin-frontmatter@1.3.0(typedoc-plugin-markdown@4.6.3(typedoc@0.28.3(typescript@5.7.3))): + typedoc-plugin-frontmatter@1.3.0(typedoc-plugin-markdown@4.6.3(typedoc@0.28.7(typescript@5.7.3))): dependencies: - typedoc-plugin-markdown: 4.6.3(typedoc@0.28.3(typescript@5.7.3)) + typedoc-plugin-markdown: 4.6.3(typedoc@0.28.7(typescript@5.7.3)) yaml: 2.7.1 - typedoc-plugin-markdown@4.6.3(typedoc@0.28.3(typescript@5.7.3)): + typedoc-plugin-markdown@4.6.3(typedoc@0.28.7(typescript@5.7.3)): dependencies: - typedoc: 0.28.3(typescript@5.7.3) + typedoc: 0.28.7(typescript@5.7.3) - typedoc@0.28.3(typescript@5.7.3): + typedoc@0.28.7(typescript@5.7.3): dependencies: - '@gerrit0/mini-shiki': 3.3.0 + '@gerrit0/mini-shiki': 3.7.0 lunr: 2.3.9 markdown-it: 14.1.0 minimatch: 9.0.5 typescript: 5.7.3 - yaml: 2.7.1 + yaml: 2.8.0 typescript@5.7.3: {} @@ -6507,10 +6507,10 @@ snapshots: yallist@3.1.1: {} - yaml@2.7.0: {} - yaml@2.7.1: {} + yaml@2.8.0: {} + yargs-parser@20.2.9: {} yargs-unparser@2.0.0: