Appearance
controller-teleport
The controller-teleport
component enables instant teleportation in VR by pointing at a destination and pressing a controller button. This provides a comfortable locomotion method that minimizes motion sickness for many users.
Example
Below is an example of a basic teleportation setup:
Props
Property | Type | Default | Description |
---|---|---|---|
hand | string | "right" | Which controller to use for teleporting ("left" or "right") |
button | string | "trigger" | Controller button to activate teleport |
cameraHeight | number | 1 | Height offset applied after teleporting (in meters) |
interactionClass | string | "interactive" | CSS class that defines teleportable surfaces |
Controller Buttons
The following buttons can be configured for teleportation:
Button Value | Description |
---|---|
"trigger" | Main trigger button (index finger) |
"grip" | Side grip button (middle finger) |
"a" / "b" | Primary buttons on right controller |
"x" / "y" | Primary buttons on left controller |
Usage Tips
Making Surfaces Teleportable
For teleportation to work, surfaces must be detectable by the controller's raycaster. Make sure surfaces have the "interactive" class or vr-interactive component:
html
<a-plane position="0 0 0" rotation="-90 0 0" width="20" height="20" class="interactive"></a-plane>
If you want to use a different class name for teleportable surfaces, you can specify it using the interactionClass
property:
html
<a-entity controller-teleport="hand: right; interactionClass: teleportable"></a-entity>
<a-plane position="0 0 0" rotation="-90 0 0" width="20" height="20" class="teleportable"></a-plane>
Listening for Teleport Events
You can listen for teleport events to trigger actions when the user teleports:
js
document.querySelector('[controller-teleport]').addEventListener('teleported', ()=>{
// Perform actions based on the interaction
});
Combining with Other Movement Options
For maximum accessibility, combine teleportation with smooth locomotion using the controller-movement component:
html
<a-entity id="rig" position="0 1.6 0" controllers>
<a-camera></a-camera>
<!-- Smooth movement with left hand -->
<a-entity controller-movement="mainHand: left"></a-entity>
<!-- Teleportation with right hand -->
<a-entity controller-teleport="hand: right"></a-entity>
</a-entity>
This allows users to choose their preferred movement method based on comfort preferences.