Merge branch 'main' into feature/body-tracking

.github/workflows/alpha.yml

@@ -0,0 +1,113 @@
+name: Deploy Beta Packages
+
+on:
+  push:
+    branches:
+      - develop
+
+jobs:
+  deploy-packages:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - uses: pnpm/action-setup@v2
+        name: Install pnpm
+        with:
+          version: 9
+          run_install: false
+
+      - uses: gittools/actions/gitversion/setup@v0
+        with:
+          versionSpec: '5.x'
+
+      - name: Install Dependencies
+        run: pnpm install
+
+      - name: Check
+        run: |
+          pnpm -r check:prettier
+          pnpm -r check:eslint
+
+      #      - name: Test
+      #        run: |
+      #          pnpm exec playwright install chromium
+      #          pnpm -r test
+
+      - name: Gitversion
+        id: gitversion
+        uses: gittools/actions/gitversion/execute@v0
+
+      - name: Build
+        run: |
+          pnpm -r copy
+          pnpm -F './packages/**/*' build
+
+      - name: Copy README
+        run: cp ./README.md packages/react/xr
+
+      - name: Set Version
+        run: pnpm -F './packages/**/*' exec json -f "package.json" -I -e 'this.version = "${{ steps.gitversion.outputs.fullSemVer }}"'
+
+      - name: Set publishing config
+        run: pnpm config set '//registry.npmjs.org/:_authToken' "${{ secrets.NPM_TOKEN }}"
+
+      - id: check-pointer-events
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/pointer-events/
+
+      - name: Deploy pointer events Package
+        if: steps.check-pointer-events.outputs.is-new-version == 'true'
+        working-directory: ./packages/pointer-events
+        run: pnpm publish --access public --no-git-checks --tag alpha
+
+      - id: check-handle-vanilla
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/handle/
+
+      - name: Deploy Handle Vanilla Package
+        if: steps.check-handle-vanilla.outputs.is-new-version == 'true'
+        working-directory: ./packages/handle
+        run: pnpm publish --access public --no-git-checks --tag alpha
+
+      - id: check-xr-vanilla
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/xr/
+
+      - name: Deploy XR Vanilla Package
+        if: steps.check-xr-vanilla.outputs.is-new-version == 'true'
+        working-directory: ./packages/xr
+        run: pnpm publish --access public --no-git-checks --tag alpha
+
+      - id: check-handle-react
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/react/handle/
+
+      - name: Deploy Handle React Package
+        if: steps.check-handle-react.outputs.is-new-version == 'true'
+        working-directory: ./packages/react/handle
+        run: pnpm publish --access public --no-git-checks --tag alpha
+
+      - id: check-xr-react
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/react/xr/
+
+      - name: Deploy XR React Package
+        if: steps.check-xr-react.outputs.is-new-version == 'true'
+        working-directory: ./packages/react/xr
+        run: pnpm publish --access public --no-git-checks --tag alpha

.github/workflows/packages.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: pnpm/action-setup@v2
         name: Install pnpm
         with:
-          version: 8
+          version: 9
           run_install: false
 
       - uses: gittools/actions/gitversion/setup@v0
@@ -50,6 +50,7 @@ jobs:
 
       - name: Build
         run: |
+          pnpm -r copy
           pnpm -F './packages/**/*' build
 
       - name: Copy README
@@ -71,6 +72,16 @@ jobs:
         working-directory: ./packages/pointer-events
         run: pnpm publish --access public --no-git-checks --tag latest
 
+      - id: check-handle-vanilla
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/handle/
+
+      - name: Deploy Handle Vanilla Package
+        if: steps.check-handle-vanilla.outputs.is-new-version == 'true'
+        working-directory: ./packages/handle
+        run: pnpm publish --access public --no-git-checks --tag latest
+
       - id: check-xr-vanilla
         uses: PostHog/check-package-version@v2
         with:
@@ -81,6 +92,16 @@ jobs:
         working-directory: ./packages/xr
         run: pnpm publish --access public --no-git-checks --tag latest
 
+      - id: check-handle-react
+        uses: PostHog/check-package-version@v2
+        with:
+          path: ./packages/react/handle/
+
+      - name: Deploy Handle React Package
+        if: steps.check-handle-react.outputs.is-new-version == 'true'
+        working-directory: ./packages/react/handle
+        run: pnpm publish --access public --no-git-checks --tag latest
+
       - id: check-xr-react
         uses: PostHog/check-package-version@v2
         with:
@@ -90,3 +111,4 @@ jobs:
         if: steps.check-xr-react.outputs.is-new-version == 'true'
         working-directory: ./packages/react/xr
         run: pnpm publish --access public --no-git-checks --tag latest
+

.github/workflows/static.yml

@@ -36,6 +36,7 @@ jobs:
       # Examples
       - name: Building Examples
         run: |
+          pnpm -r copy
           pnpm -r build
 
       - name: Copy Examples
@@ -48,6 +49,9 @@ jobs:
           mkdir -p public/examples/room-with-shadows
           mkdir -p public/examples/layers
           mkdir -p public/examples/secondary-input-sources
+          mkdir -p public/examples/editor
+          mkdir -p public/examples/hit-testing
+          mkdir -p public/examples/uikit
           cp -r ./examples/minecraft/dist/* ./public/examples/minecraft
           cp -r ./examples/pingpong/dist/* ./public/examples/pingpong
           cp -r ./examples/rag-doll/dist/* ./public/examples/rag-doll
@@ -56,6 +60,9 @@ jobs:
           cp -r ./examples/room-with-shadows/dist/* ./public/examples/room-with-shadows
           cp -r ./examples/layers/dist/* ./public/examples/layers
           cp -r ./examples/secondary-input-sources/dist/* ./public/examples/secondary-input-sources
+          cp -r ./examples/editor/dist/* ./public/examples/editor
+          cp -r ./examples/hit-testing/dist/* ./public/examples/hit-testing
+          cp -r ./examples/uikit/dist/* ./public/examples/uikit
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v4

.mocharc.json

@@ -0,0 +1,3 @@
+{
+  "node-option": ["experimental-specifier-resolution=node", "loader=ts-node/esm/transpile-only"]
+}

CONTRIBUTING.md

@@ -6,6 +6,7 @@ To get started, make sure you have [Node](https://nodejs.org) and [PNPM](https:/
 
 ```bash
 pnpm i
+pnpm -r copy
 pnpm -r build
 ```
 

GitVersion.yml

@@ -3,5 +3,4 @@ branches:
   main:
     increment: None
   develop:
-    tag: beta
     increment: None

README.md

@@ -66,7 +66,8 @@ export function App() {
 ## Tutorials
 
 - 💾 [Store](https://docs.pmnd.rs/xr/tutorials/store)
-- 👌 [Interactions](https://docs.pmnd.rs/xr/tutorials/interactions)
+- 👆 [Interactions](https://docs.pmnd.rs/xr/tutorials/interactions)
+- 👌 [Handles](https://docs.pmnd.rs/xr/handles/introduction)
 - 🔧 [Options](https://docs.pmnd.rs/xr/tutorials/options)
 - 🧊 [Object Detection](https://docs.pmnd.rs/xr/tutorials/object-detection)
 - ✴ [Origin](https://docs.pmnd.rs/xr/tutorials/origin)
@@ -80,11 +81,14 @@ export function App() {
 - 🎯 [Hit Test](https://docs.pmnd.rs/xr/tutorials/hit-test)
 - ⛨ [Guards](https://docs.pmnd.rs/xr/tutorials/guards)
 
+## External Tutorials
+
+- 🥇 [**WebXR First Steps React** by Meta Quest](https://github.com/meta-quest/webxr-first-steps-react)
+
 ## Roadmap
 
 - 🤳 XR Gestures
 - 🕺 Tracked Body
-- ↕ react-three/controls
 
 ## Migration guides
 

docs/getting-started/all-components.md

@@ -84,6 +84,10 @@ Component for rendering high quality quad, cylinder, or equirectangular layers i
 
 The component also accepts properties for changing the scale, position, rotation, and more.
 
+### `NotInXR`
+
+Component for hiding the xr context to all children component. Can be used to create virtual displays and similar allowing the components inside the display to think they are not inside an XR environment, making them behave like when outside XR.
+
 ## Pointer
 
 The core interaction concept is based on (touch/grab/ray) pointers.

docs/getting-started/all-hooks.md

@@ -54,7 +54,14 @@ Inputs are a key aspect of react-three/fiber. The following hooks provide access
 
 ### `useXRInputSourceEvent`
 
-Hook for listening to xr input source events.
+Hook for listening to xr input source events. [List of events](https://developer.mozilla.org/en-US/docs/Web/API/XRInputSourceEvent).
+
+ - `inputSource`: The input source to listen to, or 'all' to listen to all input sources
+ - `event`: The event to listen to. ([List of events](https://developer.mozilla.org/en-US/docs/Web/API/XRInputSourceEvent))
+ - `fn`: Callback function called when the event is triggered.
+ - `deps`: Retriggers the binding of the event when the dependencies change.
+
+ex: `useXRInputSourceEvent('all', "selectstart", (event) => console.log(event))`
 
 ### `useXRInputSourceStateContext`
 

docs/getting-started/development-setup.md

@@ -29,7 +29,7 @@ Now with vite and ssl setup, we can host out application by starting executing `
 
 Developing WebXR experiences often requires testing WebXR-specific features, which either require an actual device or an emulator. An emulator allows testing without a specific device and without continuously switching a headset on and off.
 
-`react-three/xr` includes the [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md) emulator out of the box, which is in its 0.x status and very much experimental in its current stage. The emulator builds on [IWER by Meta Quest](https://github.com/meta-quest/immersive-web-emulation-runtime/) and adds a easy to use overlay on top of your application. The emulator is activated if no WebXR support is detected on `localhost` or by pressing `Window/Command + Alt/Option + E`.
+`react-three/xr` includes the [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md) emulator out of the box, which is in its 0.x status and very much experimental in its current stage. The emulator builds on [IWER by Meta Quest](https://github.com/meta-quest/immersive-web-emulation-runtime/) and adds a easy to use overlay on top of your application. The emulator is automatically injected if the `emulate` config has `inject` set to `true`, or if the app is served on `localhost` and if no WebXR support is detected. In case the emulator was not injected automatically, the user can inject it by pressing `Window/Command + Alt/Option + E`. After the emulator is injected, the user can press the button to enter the XR experience provided by the application.
 
 ![iwer/devui](./emulator.gif)
 

docs/getting-started/examples.md

@@ -4,7 +4,7 @@ description: Examples made with @react-three/xr
 nav: 3
 ---
 
-<Grid cols={2}>
+<Grid cols={3}>
   <li>
     [![Screenshot from Room demo](./room-demo.gif)](https://pmndrs.github.io/xr/examples/room-with-shadows/)
   </li>
@@ -29,4 +29,14 @@ nav: 3
   <li>
     [![Screenshot from Secondary Input Sources demo](./secondary-input-sources.gif)](https://pmndrs.github.io/xr/examples/secondary-input-sources/)
   </li>
+  <li>
+    [![Screenshot from the React-three-handle Editor demo](./editor.gif)](https://pmndrs.github.io/xr/examples/editor/)
+  </li>
+  <li>
+    [![Screenshot from the hit testing demo](./hit-testing.gif)](https://pmndrs.github.io/xr/examples/hit-testing/)
+    by [Sung Powley](https://bsky.app/profile/sung-powley.bsky.social) 
+  </li>
+  <li>
+    [![Screenshot from the uikit + handle demo](./uikit.gif)](https://pmndrs.github.io/xr/examples/uikit/)
+  </li>
 </Grid>

docs/getting-started/faq.md

@@ -16,32 +16,35 @@ useFrame((state) => console.log(state.camera.getWorldPosition(new Vector3())))
 
 In contrast to non-immersive 3D applications, the camera transformation in MR/VR/AR applications should never be directly controlled by the developer since the user's head movement must control the camera's transformation. Therefore, pmndrs/xr provides the XROrigin component, which allows to control where the session's origin is placed inside the 3D scene. The session origin is at the users' feet once they recenter their session. This allows to implicitly control the camera position but prevents the user from getting motion sick when their movement is not reflected in the camera's movement.
 
+##
+
 ## Having problems accessing the camera position or rotation.
 
-Check if you have OrbitControls, CameraControls, or other controls in your scene and make sure to place an `<IfInSessionMode deny={['immersive-ar', 'immersive-vr']}>` guard around them when in XR. This prevents overwriting the camera transformation which is controlled through WebXR when inside an immersive session and allows to access the correct transformation.
+Check if you have OrbitControls, CameraControls from `@react-three/drei`, or other controls in your scene and make sure to place an `<IfInSessionMode deny={['immersive-ar', 'immersive-vr']}>` guard around them when in XR or replace them with `OrbitHandles` or `MapHandles` from `@react-three/handle`. This prevents overwriting the camera transformation which is controlled through WebXR when inside an immersive session and allows to access the correct transformation.
 
 ```tsx
-const OrbitControlsWrapper = () => {
-  return (
-    <IfInSessionMode deny={['immersive-ar', 'immersive-vr']} >
-        <OrbitControls />
-    </IfInSessionMode>
-  )
-}
+import { OrbitHandles } from '@react-three/handles'
+import { noEvents, PointerEvents } from '@react-three/xr'
+
+<Canvas events={noEvents}>
+  <PointerEvents />
+  <OrbitHandles />
+</Canvas>
 ```
 
 ## I cannot enter the XR session!
 
 1. **Missing Https**  
-If you are trying to enter the AR or VR modus and nothing is happening, make sure that you are accessing the website using `https://`.
-In case you are using vite, we recommend using the `@vitejs/plugin-basic-ssl` to try out your vite application on your device while developing.
+   If you are trying to enter the AR or VR modus and nothing is happening, make sure that you are accessing the website using `https://`.
+   In case you are using vite, we recommend using the `@vitejs/plugin-basic-ssl` to try out your vite application on your device while developing.
 
 2. **Missing XR component**  
-If you made sure that the website is accessed using `https://` and still nothing happens when executing `enterAR` or `enterVR`, it is likely that the `<XR>` component is missing. Be sure to add the `<XR>` component directly into the `<Canvas>` and make sure both the `<Canvas>` and the `<XR>` component are present when the button is pressed.
+   If you made sure that the website is accessed using `https://` and still nothing happens when executing `enterAR` or `enterVR`, it is likely that the `<XR>` component is missing. Be sure to add the `<XR>` component directly into the `<Canvas>` and make sure both the `<Canvas>` and the `<XR>` component are present when the button is pressed.
 
 3. **Entering while loading content**  
-If you cannot enter the VR or AR experience, there might be assets in your scene that are loading.
-Make sure to place a suspense boundary around your scene. With this setup, the `<XR>` component stays mounted while your scene loads.
+   If you cannot enter the VR or AR experience, there might be assets in your scene that are loading.
+   Make sure to place a suspense boundary around your scene. With this setup, the `<XR>` component stays mounted while your scene loads.
+
 ```tsx
 <Canvas>
   <XR>
@@ -68,7 +71,7 @@ For non-handheld VR and AR experiences, you can use [react-three/uikit](https://
 
 ## Does it work on iOS?
 
-WebXR for VR experiences is supported on Safari for Apple Vision Pro. 
+WebXR for VR experiences is supported on Safari for Apple Vision Pro.
 WebXR is not supported on iOS Safari yet. The alternative is to use products such as [Variant Launch](https://launch.variant3d.com/), which allow to build WebXR experiences for iOS.
 
 ## XRSpace
@@ -78,4 +81,3 @@ If you are placing `<XRSpace>` components outside of the `<XROrigin>` while chan
 ## `onClick` does not play video or allow file uploading (in certain browsers)
 
 As a performance optimization the react-three/xr event system batches html user events per frame. This only applies if you are using `PointerEvents`, `forwardHtmlEvents`, or `forwardObjectEvents`. This can cause issue when executing functions that require a user action. For instance, uploading a file through a input element in a safari can only be triggered manually when immediately caused by a user input. For these use cases, please disable the event batching performance optimization through the options by setting `batchEvents` to `false`.
-

docs/getting-started/introduction.md

@@ -47,7 +47,8 @@ export function App() {
 ## Tutorials
 
 - 💾 [Store](../tutorials/store.md)
-- 👌 [Interactions](../tutorials/interactions.md)
+- 👆 [Interactions](../tutorials/interactions.md)
+- 👌 [Handles](../handles/introduction.md)
 - 🧊 [Object Detection](../tutorials/object-detection.md)
 - ✴ [Origin](../tutorials/origin.md)
 - 🪄 [Teleport](../tutorials/teleport.md)
@@ -60,13 +61,14 @@ export function App() {
 - 🎯 [Hit Test](../tutorials/hit-test.md)
 - ⛨ [Guards](../tutorials/guards.md)
 
+## External Tutorials
+
+- 🥇 [**WebXR First Steps React** by Meta Quest](https://github.com/meta-quest/webxr-first-steps-react)
+
 ## Roadmap
 
 - 🤳 XR Gestures
-- ➕ Multimodal
-- 📺 Layers
 - 🕺 Tracked Body
-- ↕ react-three/controls
 
 ## Migration guides