pmndrs
Roadmap for planned tutorials and docs updates
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
useXRPlaneGeometryanduseXRMeshGeometry- (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)
@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
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 🙂👍