@threlte/xr
Getting Started
The package @threlte/xr provides tools and abstractions to more easily create VR and AR experiences.
Installation
Terminal
npm install @threlte/xrUsage
@threlte/xr is in beta. Major API changes at this point are not expected, but some breaking
changes may occur before it reaches 1.0.0.
Setup
The following adds a button to start your session and controllers inside an XR manager to prepare your scene for WebXR rendering and interaction.
Scene.svelte
<script>
import { Canvas } from '@threlte/core'
import { VRButton } from '@threlte/xr'
import Scene from './scene.svelte'
</script>
<Canvas>
<Scene />
</Canvas>
<VRButton />Then, in scene.svelte:
<script>
import { XR, Controller, Hand } from '@threlte/xr'
</script>
<XR />
<Controller left />
<Controller right />
<Hand left />
<Hand right />This will set up your project to be able to enter a VR session with controllers and hand inputs added.
If you want hands, controllers, or any other objects to be added to your THREE.Scene only when the XR session starts, make them children of the <XR> component:
<script>
import { XR, Controller, Hand } from '@threlte/xr'
</script>
<XR>
<Controller left />
<Controller right />
<Hand left />
<Hand right />
</XR>The <XR>, <Controller>, and <Hand> components can provide a powerful foundation when composed with other Threlte components.
For example, it doesn’t take much more to get to the point of a simple BeatSaber-inspired experience:
<script lang="ts">
import { Canvas } from '@threlte/core'
import { World } from '@threlte/rapier'
import { VRButton } from '@threlte/xr'
import Scene from './Scene.svelte'
</script>
<div>
<Canvas>
<World gravity={[0, 0, 0]}>
<Scene />
</World>
</Canvas>
<VRButton />
</div>
<style>
div {
height: 100%;
}
</style><script lang="ts">
import * as THREE from 'three'
import { T } from '@threlte/core'
import { InstancedMesh, Instance, RoundedBoxGeometry } from '@threlte/extras'
import { Collider, RigidBody } from '@threlte/rapier'
const colors = [
'#ff5252',
'#ff4081',
'#d500f9',
'#3d5afe',
'#40c4ff',
'#18ffff',
'#f9a825',
'#ffd740',
'#bf360c'
] as const
const positions = [
[-1, -1],
[-1, 0],
[-1, 1],
[0, -1],
[0, 0],
[0, 1],
[1, -1],
[1, 0],
[1, 1]
] as const
type Block = {
position: THREE.Vector3
color: string
}
let cubes: Block[] = []
let numCubes = 100
const margin = 0.4
const spacing = 8
for (let i = 0; i < numCubes; i += 1) {
const [x, y] = positions[Math.trunc(Math.random() * positions.length)]!
cubes.push({
position: new THREE.Vector3(x - margin, y - margin, -i * spacing),
color: colors[i % colors.length]!
})
}
const boxRadius = 0.15
const boxSize = 0.6
const offsetY = 1.5
const offsetZ = 50
const speed = 12
</script>
<InstancedMesh limit={numCubes}>
<RoundedBoxGeometry
radius={boxRadius}
args={[boxSize, boxSize, boxSize]}
/>
<T.MeshStandardMaterial
roughness={0}
metalness={0.2}
/>
{#each cubes as { position, color }, index (index)}
<T.Group
position.x={position.x}
position.y={position.y + offsetY}
position.z={position.z - offsetZ}
>
<RigidBody linearVelocity={[0, 0, speed]}>
<Collider
shape="cuboid"
mass={0.5}
args={[boxSize / 2, boxSize / 2, boxSize / 2]}
/>
<Instance {color} />
</RigidBody>
</T.Group>
{/each}
</InstancedMesh><script lang="ts">
import { Mesh, Vector3, Quaternion } from 'three'
import { T, useTask } from '@threlte/core'
import { Collider, RigidBody } from '@threlte/rapier'
import type { RigidBody as RapierRigidBody } from '@dimforge/rapier3d-compat'
import { Controller, Hand, useXR } from '@threlte/xr'
const { isHandTracking } = useXR()
let rigidBodyLeft: RapierRigidBody
let rigidBodyRight: RapierRigidBody
const sabers: { left: Mesh; right: Mesh } = { left: undefined!, right: undefined! }
const handSabers: { left: Mesh; right: Mesh } = {
left: undefined!,
right: undefined!
}
const v3 = new Vector3()
const q = new Quaternion()
useTask(() => {
const left = isHandTracking.current ? handSabers.left : sabers.left
const right = isHandTracking.current ? handSabers.right : sabers.right
if (left) {
rigidBodyLeft.setTranslation(left.getWorldPosition(v3), true)
rigidBodyLeft.setRotation(left.getWorldQuaternion(q), true)
}
if (right) {
rigidBodyRight.setTranslation(right.getWorldPosition(v3), true)
rigidBodyRight.setRotation(right.getWorldQuaternion(q), true)
}
})
const saberRadius = 0.02
const saberLength = 1.4
</script>
<Controller left>
<T.Mesh
rotation.x={Math.PI / 2}
position.z={-saberLength / 2}
oncreate={({ ref }) => (sabers.left = ref)}
>
<T.CylinderGeometry args={[saberRadius, saberRadius, saberLength]} />
<T.MeshPhongMaterial color="red" />
</T.Mesh>
</Controller>
<Controller right>
<T.Mesh
rotation.x={Math.PI / 2}
position.z={-saberLength / 2}
oncreate={({ ref }) => (sabers.right = ref)}
>
<T.CylinderGeometry args={[saberRadius, saberRadius, saberLength]} />
<T.MeshStandardMaterial
roughness={0}
color="red"
/>
</T.Mesh>
</Controller>
<Hand left>
{#snippet wrist()}
<T.Mesh
rotation.x={Math.PI / 2}
position.z={-saberLength / 2}
oncreate={({ ref }) => (handSabers.left = ref)}
>
<T.CylinderGeometry args={[saberRadius, saberRadius, saberLength]} />
<T.MeshStandardMaterial
roughness={0}
color="red"
/>
</T.Mesh>
{/snippet}
</Hand>
<Hand right>
{#snippet wrist()}
<T.Mesh
rotation.x={Math.PI / 2}
position.z={-saberLength / 2}
oncreate={({ ref }) => (handSabers.right = ref)}
>
<T.CylinderGeometry args={[saberRadius, saberRadius, saberLength]} />
<T.MeshPhongMaterial color="red" />
</T.Mesh>
{/snippet}
</Hand>
<RigidBody
type="kinematicPosition"
bind:rigidBody={rigidBodyLeft}
>
<Collider
shape="capsule"
args={[saberLength / 2, saberRadius]}
/>
</RigidBody>
<RigidBody
type="kinematicPosition"
bind:rigidBody={rigidBodyRight}
>
<Collider
shape="capsule"
args={[saberLength / 2, saberRadius]}
/>
</RigidBody><script lang="ts">
import { T } from '@threlte/core'
import { XR } from '@threlte/xr'
import Sabers from './Sabers.svelte'
import Blocks from './Blocks.svelte'
</script>
<XR>
<Sabers />
<Blocks />
</XR>
<T.AmbientLight />
<T.DirectionalLight />
<T.PerspectiveCamera
makeDefault
position={[0, 1.8, 1]}
oncreate={({ ref }) => ref.lookAt(0, 1.8, 0)}
/>
<!-- floor -->
<T.Mesh position.y={-50}>
<T.CylinderGeometry args={[2, 2, 100]} />
<T.MeshStandardMaterial color="white" />
</T.Mesh>