Roadmap for planned tutorials and docs updates

[taeuscherpferd]

Summary

A list of all of the current components in the React Three XR library, tracking which examples / tutorials exist for them, and which tutorials / examples still need to be written. This is intended to be a living document that gets updated as things change and tasks get completed. By the end of this, the docs should be pretty robust ;)

Current State

• ✅ - Completely covered with a fully filled out jsdoc
• ☑️ - Completely covered with existing examples and tutorials
• 🟨 - Partially covered by either an example or tutorial
• ⛔ - Not covered by either an example or a tutorial

Anchors
useRequestXRAnchor ⛔
useXRAnchor 🟨: Needs Example

Hit Testing
XRHitTest ✅
useXRHitTest ✅
useXRHitTestSource ✅
useXRRequestHitTest ✅

Physics based AR interactions
useInitRoomCapture ⛔

Movement
useXRControllerLocomotion ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
TeleportTarget ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc

Customizing Controller
XRControllerComponent 🟨: Needs tutorial
XRControllerModel 🟨: Needs tutorial
useLoadXRControllerLayout 🟨: Needs tutorial
useLoadXRControllerModel 🟨: Needs tutorial
useXRControllerButtonEvent ⛔
DefaultXRController ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
DefaultXRControllerGrabPointer ⛔
DefaultXRGaze 🟨: Needs example
DefaultXRInputSourceRayPointer ⛔
DefaultXRInputSourceTeleportPointer ⛔
DefaultXRScreenInput 🟨: Needs example
DefaultXRTransientPointer 🟨: Needs example

Customizing Hands
XRHandModel ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
DefaultXRHandGrabPointer ⛔
DefaultXRHandTouchPointer ⛔
DefaultXRHand ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc

Customizing Pointer
Input Methods
useHover 🟨: Needs tutorial
CombinedPointer ⛔
PointerCursorModel 🟨: Needs example
PointerRayModel ⛔
useGrabPointer ⛔
useLinesPointer ⛔
usePointerXRInputSourceEvents ⛔
useRayPointer ⛔
useTouchPointer 🟨: Needs example
useXRInputSourceEvent ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc. Could use a better tutorial

Overlays / HUD
XRDomOverlay ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
NotInXR 🟨: Needs tutorial

Guards and Checks
IfFacingCamera ⛔
ShowIfFacingCamera ⛔
IfSessionVisible ⛔
ShowIfSessionVisible ⛔
IfInSessionMode ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
ShowIfInSessionMode ⛔
IfSessionModeSupported ⛔
ShowIfSessionModeSupported ⛔
useXRSessionFeatureEnabled ⛔
useXRSessionModeSupported ⛔
useXRSessionVisibilityState ⛔

XR Layers, what they are and when to use them
XRLayer ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
XRSpace ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
XRSpaceType ⛔
useApplyXRSpaceMatrix ⛔
useGetXRSpaceMatrix ⛔
useXRSpace ⛔

Starting a Session and general flow of XR
XROrigin ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
XR ☑️ : Needs usage snippet, better description, and links to tutorial and example in jsdoc
createXRStore ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
useXR ☑️ : Needs usage snippet, and links to tutorial and example in jsdoc
useXRStore ⛔

XRGeometry? (Not sure what these do)
XRMeshModel 🟨: Needs example
useXRMeshGeometry ⛔
useXRMeshes 🟨: Needs example
XRPlaneModel 🟨: Needs example
useXRPlaneGeometry ⛔
useXRPlanes 🟨: Needs example

Planned Tutorials

Tutorials that are planned to cover the items above that still need a tutorial

• Object Detection: Update the existing Object Detection tutorial to better explain what these components are, why you would want to use them, and include useXRPlaneGeometry and useXRMeshGeometry

  • (useXRPlaneGeometry, useXRMeshGeometry)

• XRSpaces Primer: Update the new XRSpaces Primer tutorial to touch on all of the hooks available for accessing and using spaces in WebXR, and when you would use each in WebXR

  • (XRSpace, XRSpaceType, useApplyXRSpaceMatrix, useGetXRSpaceMatrix, useXRSpace)

• Guards: Update the current Guards tutorial to touch on all of the other relevant guards

  • (IfFacingCamera, ShowIfFacingCamera, IfSessionVisible, ShowIfSessionVisible, IfInSessionMode, ShowIfInSessionMode, IfSessionModeSupported, ShowIfSessionModeSupported, useXRSessionFeatureEnabled, useXRSessionModeSupported, useXRSessionVisibilityState)

• Heads up Display: A tutorial explaining how to create the HUD example

• Pointers: A tutorial explaining the various components and how to use them to customize things

  • (CombinedPointer, PointerCursorModel, PointerRayModel, useGrabPointer, useLinesPointer, usePointerXRInputSourceEvents, useRayPointer, useTouchPointer, DefaultXRInputSourceTeleportPointer, DefaultXRControllerGrabPointer, DefaultXRInputSourceRayPointer, DefaultXRHandGrabPointer, DefaultXRHandTouchPointer DefaultXRTransientPointer)

• Inputs and Events in WebXR: A lot of people get confused about this. It would be good to create a tutorial about how events work in React Three XR, how they relate to DOM events, and what the developer can do to customize/use them.

  • (useHover)

• Customizing Controllers and Hands: Update the existing tutorial to be clearer and easier to follow. Also include a section for updating the controllers

  • (XRControllerComponent, XRControllerModel, useLoadXRControllerLayout, useLoadXRControllerModel, DefaultXRController, DefaultXRGaze, DefaultXRScreenInput, XRHandModel, DefaultXRHand, DefaultXRInputSourceTeleportPointer)

• Grabbing/Equiping tutorial: Seems like a common use case that people would want to implement in their applications. Should touch on both physics and non physics scenarios

✅ Hit Test: Update the current hist testing tutorial to touch on the rest of the components in the library: (useXRHitTest, useXRHitTestSource, useXRRequestHitTest)

• Anchors: Update the anchor tutorial to touch on the other anchor component as well
  • (useRequestXRAnchor)

Planned Examples

Examples that are planned to cover the items above that still need a tutorial

• Guards and checks Playground: An example that showcases all of the different guards and checks that WebXR supports

  • (IfFacingCamera, ShowIfFacingCamera, IfSessionVisible, ShowIfSessionVisible, IfInSessionMode, ShowIfInSessionMode, IfSessionModeSupported, ShowIfSessionModeSupported, useXRSessionFeatureEnabled, useXRSessionModeSupported, useXRSessionVisibilityState)

• XRGeometry showcase: Not sure what this would entail but these needed an example

  • (XRMeshModel, useXRMeshGeometry, useXRMeshes, XRPlaneModel, useXRPlaneGeometry, useXRPlanes)

• Object detection example: An example to show off the XR geometry mesh and plane capabilitys in WebXR

  • (XRMeshModel, useXRMeshGeometry, useXRMeshes, XRPlaneModel, useXRPlaneGeometry, useXRPlanes)

• XRSpaces Primer: Update the new XRSpaces Primer example to include usages of the XR spaces hooks OR make a new example showing off the capabilities

  • (XRSpace, XRSpaceType, useApplyXRSpaceMatrix, useGetXRSpaceMatrix, useXRSpace)

• Heads Up Display: An example showing how to efficiently create a HUD. Many people have been asking for this

• Pointers: An example showing off all of the cool pointer stuff that you can use in react three XR (Maybe a lazer pointer that you can swap out the colors of, and toggle what it affects)

  • (CombinedPointer, PointerCursorModel, PointerRayModel, useGrabPointer, useLinesPointer, usePointerXRInputSourceEvents, useRayPointer, useTouchPointer)

• Hand / Controller swap demo: An example where the user can swap out a number of different hands and controllers

  • (XRControllerComponent, XRControllerModel, useLoadXRControllerLayout, useLoadXRControllerModel, DefaultXRController, DefaultXRGaze, DefaultXRScreenInput, XRHandModel, DefaultXRHand, DefaultXRInputSourceTeleportPointer)

• Grabbing/Equiping example: Seems like a common use case that people would want to implement in their applications. Should touch on both physics and non physics scenarios

✅ Hit testing: Modify the duck example to include showcases for these components: (useXRHitTest, useXRHitTestSource, useXRRequestHitTest)

• Anchors: An example for creating and placing anchors. Perhaps a virtual picture hanging application?
  • (useRequestXRAnchor, useXRAnchor)

[joaomelorodrigues]

This will be very very helpful!

[micronic85]

ready to participate in testing

[bbohlender]

@taeuscherpferd

this list is awesome!

I think there should be 3 types of documentation elements.

• API Docs - generated based on all available components and hooks (you already did that)
• API Tutorials - tutorials for building examples with the available components and hooks bundled for a specific area (e.g. pointers)
• Explainers - introduction into specific topics assuming zero 3D and XR knowledge

Based on peoples knowledge they should be routed from the README into these 3 categories, while Explainers route people to API Tutorials and API Tutorials route people further to the API Docs.

Explainers are for people just getting started
API Tutorials are for people knowing about 3D and XR but not used react-three/xr
API Docs are for people familiar with react-three/xr who just want to search a function they forgot about

let me know what you think

[taeuscherpferd]

Good suggestions!

I feel like that was format that I was already working towards 👍 The only difference is that I'm also making sure that there are example usages of each component in the example projects that we provide.

I think what I've outlined above will definitely cover the first two points, as for the explainers, I think that I would need a little more info on what exactly you're looking for. I've tried a couple of times to write a bit of a primer on getting started concepts, but I don't think that I'm quite on the same page on what you're looking for. I've updated the Spaces tutorial with your suggestions, is that tutorial what you're thinking for explainers?

If you could let me know if you want to change anything on how I'm doing the API tutorials, and a list of explainers that you would like to see, I'll do my best to implement it all 🙂👍