three-elements-xr

WebXR components and helpers for three-elements.

Usage no npm install needed!

<script type="module">
  import threeElementsXr from 'https://cdn.skypack.dev/three-elements-xr';
</script>

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, or oculus_lowpoly. Default is oculus.
  • 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