README
three-elements-xr
WebXR components and helpers for three-elements
. See the live demo.
Table of Contents
Get Started
Make sure you have three-elements
installed. Add dependencies with:
npm install three-elements three-elements-xr
# or
yarn add three-elements three-elements-xr
Then, simply import it into your project.
import 'three-elements';
import 'three-elements-xr';
Finally, add some components to your project.
<three-xr-game button>
<three-scene>
<three-ambient-light intensity="1.2"></three-ambient-light>
<three-grid-helper args="4 4"></three-grid-helper>
<three-xr-controllers></three-xr-controllers>
<three-xr-hands></three-xr-hands>
</three-scene>
</three-xr-game>
Check out the full demo and its source here.
Components
A list of WebXR components and their properties.
three-xr-game
A modified <three-game />
element that sets up a XR session and handles session events.
<three-xr-game
button
sessionstart="console.log('sessionstart', this)"
sessionend="console.log('sessionend', this)"
>
...
</three-xr-game>
Attributes:
- button (boolean): Generates a session button to enter and leave an XR session. Default is
false
. - sessionstart (function): A function to be executed when an XR session emits
sessionstart
(see session events). - sessionend (function): A function to be executed when an XR session emits
sessionend
(see session events).
three-xr-controllers
An element for default headset controllers, handling controller events.
<three-xr-controllers
connected="console.log('connected', this)"
disconnected="console.log('disconnected', this)"
select="console.log('select', this)"
selectstart="console.log('selectstart', this)"
selectend="console.log('selectend', this)"
squeeze="console.log('squeeze', this)"
squeezestart="console.log('squeezestart', this)"
squeezeend="console.log('squeezeend', this)"
/>
Attributes:
- connected (function): A function to be executed when an XR controller emits
connected
(see controller events). - disconnected (function): A function to be executed when an XR controller emits
disconnected
(see controller events). - select (function): A function to be executed when an XR controller emits
select
(see controller events). - selectstart (function): A function to be executed when an XR controller emits
selectstart
(see controller events). - selectend (function): A function to be executed when an XR controller emits
selectend
(see controller events). - squeeze (function): A function to be executed when an XR controller emits
squeeze
(see controller events). - squeezestart (function): A function to be executed when an XR controller emits
squeezestart
(see controller events). - squeezeend (function): A function to be executed when an XR controller emits
squeezeend
(see controller events).
Properties:
- controllers (group): An array of XR controllers.
three-xr-hands
An element for hand tracking if available, handling controller events.
<three-xr-hands
connected="console.log('connected', this)"
disconnected="console.log('disconnected', this)"
select="console.log('select', this)"
selectstart="console.log('selectstart', this)"
selectend="console.log('selectend', this)"
squeeze="console.log('squeeze', this)"
squeezestart="console.log('squeezestart', this)"
squeezeend="console.log('squeezeend', this)"
/>
Attributes:
- path (string): The path to generate hands from. Defaults to three.js models.
- profile (string): The hand profile used to generate hands. Options are
spheres
,boxes
,oculus
, oroculus_lowpoly
. Default isoculus
. - connected (function): A function to be executed when an XR hand emits
connected
(see controller events). - disconnected (function): A function to be executed when an XR hand emits
disconnected
(see controller events). - select (function): A function to be executed when an XR hand emits
select
(see controller events). - selectstart (function): A function to be executed when an XR hand emits
selectstart
(see controller events). - selectend (function): A function to be executed when an XR hand emits
selectend
(see controller events). - squeeze (function): A function to be executed when an XR hand emits
squeeze
(see controller events). - squeezestart (function): A function to be executed when an XR hand emits
squeezestart
(see controller events). - squeezeend (function): A function to be executed when an XR hand emits
squeezeend
(see controller events).
Properties:
- controllers (group): An array of XR controllers.
Events
A list of native and custom WebXR session and controller events.
Session Events
Events fired by an WebXR session.
- sessionstart: Fired when a XR session starts presenting.
- sessionend: Fired when a XR session ends presenting.
Controller Events
Events fired by an WebXR controller or hand.
- connected: Fired when an XR controller is recognized and connected
- disconnected: Fired when a XR controller disconnects
- select: Fired on a XR controller completes a primary action
- selectstart: Fired when a XR controller begins a primary action
- selectend: Fired when a XR controller ends a primary action
- squeeze: Fired when a XR controller completes a primary squeeze action
- squeezestart: Fired when a XR controller begins a primary squeeze action
- squeezeend: Fired when a XR controller ends its primary squeeze action