pmndrs · taeuscherpferd · Jul 19, 2025 · Jul 19, 2025 · Jul 20, 2025 · Jul 26, 2025
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -4,7 +4,7 @@
 
   // Run the equivalent of `eslint --fix` each time you save
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true
+    "source.fixAll.eslint": "explicit"
   },
 
   // Disable the built‑in “Organize Imports” so it doesn’t fight ESLint

diff --git a/docs/tutorials/3d-concepts-for-2d-web-developers.md b/docs/tutorials/3d-concepts-for-2d-web-developers.md
@@ -0,0 +1,106 @@
+---
+title: Introduction to XR development
+description: A quick introduction to basic XR concepts for developers
+nav: 8
+---
+
+The Internet is one of the most freeing ways for developers to be able to express themselves. Since web development first began, developers have been using it to unleash their creativity and push the boundaries of what a web browser is capable of. 2D development has long been the standard of developing creative content on the web, but with advances in hardware and frameworks, it is now possible to build everything from AR artwork anchored to a physical wall, to entire virtual worlds that can be explored with a VR headset, all contained and run from within a webpage. React-Three-XR is a library designed to make developing these XR experiences as simple as possible. This guide is here to help developers with a primarily 2D web development background to get up and running making 3D experiences as quickly as possible. Here are some 3D concepts that you will need to understand before moving on to developing full web applications. 
+
+## Understanding the Basics of 3D Graphics
+
+### Coordinate Systems
+
+In 3D development, everything exists within a **three-dimensional coordinate system**, typically represented by three axes:
+
+- **X-axis:** Left and right
+- **Y-axis:** Up and down
+- **Z-axis:** Forward and backward
+
+All 3D objects are positioned, rotated, and scaled based on these three axes.
+
+*Note: Some 3D editors will change which axis represents which direction, however in Three.js, X is horizontal, Y is vertical, and Z is forward and backward*
+
+### Scenes
+
+All 3D elements are contained inside of scenes. Typically a scene represents an environment such as a room or street. You can loosely picture scenes as levels in a video game, where each level is represented by a scene. **Cameras**, **Models**, and **Lighting** are all elements that can be found within a scene.
+
+### Cameras 
+
+Cameras act as the viewer's eye into the scene. Common camera types include:
+
+- **Perspective:** (realistic, depth-based view) This is the camera most 3d games use. 
+- **Orthographic:** (no depth distortion) This camera makes everything appear flat.
+
+In React-Three-XR you typically do not have to worry about the camera much as the user's device is usually acting as the camera, and they control where it points.
+
+### Models, Meshes, Materials, and Geometry
+
+Objects in 3D space are known as 3D models. A 3D model in the context of Three.js typically includes the following elements: 
+
+- **Models:** Models are the wrapper for all of the components of a 3D object
+	- **Meshes**: Meshes are the fundamental building blocks of 3D elements. They include the following properties:
+		- **Geometry:** Geometry defines the shape of an object (cube, sphere, plane).
+		- **Materials:** Materials control how the surface of a geometry looks (color, reflectivity, texture).
+	- **Armature:** The Armature represents any bones and joints that your model might have.
+	- **Animations:** Animations are saved onto your model and can be played in your scene.
+
+### Lighting
+
+Lighting brings your 3D scene to life, providing depth and realism. Common light types are:
+
+- **Ambient:** Soft, global illumination.
+- **Directional:** Simulates sunlight, casting parallel rays.
+- **Point:** Emits light in all directions from a single point.
+
+There are other lighting types but they are typically less common. [You can find the full list here](https://threejs.org/manual/#en/lights)
+
+## How Does React Three XR Fit In?
+
+**React-Three-XR** bridges traditional React development with immersive WebXR technologies (VR and AR). It is built upon:
+
+- **React Three Fiber:** Allows you to use Three.js with the familiar React framework. 3D elements are created and organized as React components.
+- **WebXR:** Enables virtual and augmented reality experiences directly within web browsers.
+
+React-Three-XR also includes a number of helpful pre built components that make getting started with XR development in the web much easier
+
+
+### Simple Example of React Three Fiber XR
+
+Here's a basic example of a React Three Fiber XR scene:
+
+```jsx
+import React from 'react';
+import { Canvas } from '@react-three/fiber';
+import { XR, createXRStore } from '@react-three/xr';
+
+const store = createXRStore()
+
+export const App = () => {
+  return (
+    <>
+      <button onClick＝{() => store.enterAR()}/>
+      <Canvas>
+        <XR>
+          <ambientLight />
+          <mesh position={[0, 0, -2]}>
+            <boxGeometry />
+            <meshStandardMaterial color="blue" />
+          </mesh>
+        </XR>
+      </Canvas>
+    </>
+  );
+}
+```
+
+In this example:
+
+- `<Canvas>` Sets up the rendering context. WebXR scenes all exist within an HTML canvas.
+- `<XR>` Wraps your XR-enabled components.
+- `<button>` Provides a button for you user to enter your scene on an XR enabled device.
+- `<mesh>` Creates a box and inserts it into your scene.
+- `<ambientLight>` Puts a light into your scene so that your objects can be seen.
+
+## Next Steps
+
+This guide has armed you with the basic knowledge that you need to understand how a 3D scene is structured. From here you should be able to check out some of the other tutorials found on this site and start making your own XR experiences on the web. Happy coding :)
diff --git a/docs/tutorials/anchors.md b/docs/tutorials/anchors.md
@@ -1,7 +1,7 @@
 ---
 title: Anchors
 description: How to create and manage anchors in your AR experience?
-nav: 17
+nav: 18
 ---
 
 Anchors allow to anchor virtual objects into the physical world in AR experiences. `react-three/xr` offers a multitude of ways to create and manage anchors. A simple solution is `useXRAnchor`, which works similarly to `useState` as it returns the current anchor and a function to request a new anchor as a tuple.

diff --git a/docs/tutorials/custom-inputs.md b/docs/tutorials/custom-inputs.md
@@ -1,7 +1,7 @@
 ---
 title: Custom Hands/Controllers/...
 description: Customize interactions and style of inputs such as hands, controllers, and more
-nav: 16
+nav: 17
 ---
 
 @react-three/xr provides a set of default hands, controllers, transient pointers, gazes, and screen input that can be configured and completely exchanged with your own implementation. The following example shows how to configure the ray color of the ray pointer in the users hand.

diff --git a/docs/tutorials/dom-overlay.md b/docs/tutorials/dom-overlay.md
@@ -1,7 +1,7 @@
 ---
 title: Dom Overlay
 description: How to add HTML elements for hand-held AR experiences with Dom overlay?
-nav: 18
+nav: 19
 ---
 
 For hand-held AR experiences, such as those using a Smartphone, WebXR offers the dom overlay capability, allowing developers to use HTML code overlayed over the experience. In case scene 3D overlays or overlays in non-handheld AR/VR experiences are needed, check out [pmndrs/uikit](https://github.com/pmndrs/uikit).

diff --git a/docs/tutorials/gamepad.md b/docs/tutorials/gamepad.md
@@ -1,7 +1,7 @@
 ---
 title: Gamepad
 description: How to use the XRControllers gamepad?
-nav: 13
+nav: 14
 ---
 
 All XR controllers are part of the state inside the xr store. The existing controllers can be read using the `useXR` hook. Alternatively, a specific xr controller can be retrived using `useXRInputSourceState("controller", "left")`.

diff --git a/docs/tutorials/guards.md b/docs/tutorials/guards.md
@@ -1,7 +1,7 @@
 ---
 title: Guards
 description: Render and show parts of your application conditionally using guards
-nav: 20
+nav: 21
 ---
 
 Guards allow to conditionally display or include content. For instance, the `IfInSessionMode` guard allows only displaying a background when the session is not an AR session. The `IfInSessionMode` can receive either a list of `allow` session modes or a list of `deny` session modes.

diff --git a/docs/tutorials/hit-test.md b/docs/tutorials/hit-test.md
@@ -1,7 +1,7 @@
 ---
 title: Hit Test
 description: How to add hit testing capabilities to your AR experiences?
-nav: 19
+nav: 20
 ---
 
 Hit testing allows to check intersections with real-world geometry in AR experiences. `@react-three/xr` provides various hooks and components for setting up hit testing.

diff --git a/docs/tutorials/interactions.md b/docs/tutorials/interactions.md
@@ -1,7 +1,7 @@
 ---
 title: Interactions
 description: Build interactions that work across XR and non-XR web applications
-nav: 9
+nav: 10
 ---
 
 On this page, you can learn the basics behind pointer events and interactions in react-three/xr. From experience, we found that many people are interested in more high level interactions, which can be build with the concept of handles. Check out the [handles pages](../handles/introduction.md) to learn more about the concept and the library we built for it.

diff --git a/docs/tutorials/layers.md b/docs/tutorials/layers.md
@@ -1,7 +1,7 @@
 ---
 title: Layers
 description: How to use display images, videos, and custom renders at high quality on quad, cylinder, and equirect shapes?
-nav: 15
+nav: 16
 ---
 
 Layers allow to render videos, images, and complete scenes with higher performance and higher quality while preserving battery life and latency for quad, cylinder, and equirect shapes using the WebXR Layer API. Layers are perfect for use cases that display flat, high-quality content, such as videos, images, and user interfaces. The following example illustrates how to create a layer that renders a video.

diff --git a/docs/tutorials/object-detection.md b/docs/tutorials/object-detection.md
@@ -1,7 +1,7 @@
 ---
 title: Object Detection
 description: Use detected objects such as meshes and planes for rendering, scene understanding, physics, and more
-nav: 10
+nav: 11
 ---
 
 @react-three/xr allows to use the devices mesh and plane detection functionality to detect the meshes and planes in the environment to modify the rendering, allow physics interactions with the environment, and more.

diff --git a/docs/tutorials/origin.md b/docs/tutorials/origin.md
@@ -1,7 +1,7 @@
 ---
 title: Origin
 description: Control the user's transformation by setting the XR session origin
-nav: 11
+nav: 12
 ---
 
 The origin of an XR session is a 3D transformation that represents the position of the feet when the user recenters the session. Therefore, we recommend treating the session origin as the position of the feet. @react-three/xr provides the `XROrigin` component to control this transformation and place it anywhere inside the scene.

diff --git a/docs/tutorials/secondary-input-sources.md b/docs/tutorials/secondary-input-sources.md
@@ -1,7 +1,7 @@
 ---
 title: Secondary Input Sources
 description: How to use primary and secondary input sources (multiple controllers and hands) simultaneously?
-nav: 14
+nav: 15
 ---
 
 Most standalone XR headsets support hand and controller tracking. While typical XR experiences often support both input methods, they only use the primary inputs, which refers to one input per hand and limits the inputs to `2`. However, the headset often also tracks the secondary input sources. By enabling the `secondaryInputSources` flag when creating an xr store, we can access the secondary input sources and use them to track real-world objects, for example.

diff --git a/docs/tutorials/store.md b/docs/tutorials/store.md
@@ -1,7 +1,7 @@
 ---
 title: Store
 description: What is the XR Store for?
-nav: 8
+nav: 9
 ---
 
 The xr store is the central part of all `@react-three/xr` experiences and allows to configure those experiences using a large set of options, control the experience using various functions, and provide access to the current state of the xr experience.

diff --git a/docs/tutorials/teleport.md b/docs/tutorials/teleport.md
@@ -1,7 +1,7 @@
 ---
 title: Teleportation
 description: Allow users to move through the scene using teleportation
-nav: 12
+nav: 13
 ---
 
 First we need to enable the teleport pointer inside the hands and controllers.