Note: If you are just getting started with this Meta XR feature, we recommend that you use Building Blocks, a Unity extension for Meta XR SDKs, to quickly add features to your project.

How does Teleport Interaction work?

The teleport interaction consists of two components, TeleportInteractor and TeleportInteractable. These two components communicate to determine whether a Teleport interaction has taken place and how the interaction should behave.

TeleportInteractor

TeleportInteractor is the Interactor class of the teleport interaction and is included in the TeleportHandInteractor prefab. It controls the shape of the arc, how to move the player, and how to select an interactable. TeleportInteractor uses an IPolyline (TeleportArc) and an external selector to find the best interactable and then emit an event requesting a teleport to that interactable.

Property	Description
Selector	A selector indicating when the interactor should select or unselect the best available interactable. When using controllers, this selector is driven by the joystick value. When using hands, it’s driven by the index pinch value.
Arc Origin	A transform indicating the position and direction (forward) from where the arc is cast.
Teleport Arc	An `IPolyline` that specifies the shape of the arc used to detect available interactables. For more details, see TeleportArc.

ComputeCandidateDelegate

In some scenarios it is desirable to create custom logic to define how the best Candidate will be hovered, for example modifying the final trayectory of the provided Arc so it snap to surfaces. The TeleportInteractor.InjectOptionalCandidateComputer allows overriding the ComputeCandidate logic of the TeleportInteractor so new behaviours other than the default are possible.

The default implementation is the TeleportCandidateComputer and allows blocking the arc if the line between a transform and the arc origin is blocked, preventing players from clipping their hands through walls in order to teleport to the other side.

TeleportArc

The TeleportArc property defines the shape and trajectory of the arc used for raycasting and finding valid teleport targets. The default implementation is TeleportArcGravity, but it is possible to create custom arcs by simply implementing the IPolyline interface.

Shoulder Stabilization

When selecting a distant object to teleport to, using just the hand can be too noisy. To reduce noise, the TeleportHandInteractor prefab includes shoulder stabilization. Shoulder stabilization uses the estimated position of the shoulder to stabilize the rotation of the arc and increase or decrease its max range. As a result, the user can adjust the arc position by moving their hand towards or away from their shoulder. The TeleportHandInteractor prefab also remaps the pitch of the arc so the user can reach vertical arcs without extending their arm straight upwards. Even when using controllers, it can be interesting to use a Shoulder Stabilization for simply adjusting the max range of the arc when the user extends their arm.

TeleportInteractable

TeleportInteractable is the Interactable class of the teleport interaction. It represents a teleport location. TeleportInteractable uses its Surface property to detect hits from the teleport arc. If the surface is hit, it provides the hit point and the normal and desired orientation of the player (if any). This allows the interactables to have different configurations that affect the final pose of the player when teleporting to them.

Property	Description
Allow Teleport	Indicates if the interactable is a valid teleport location. You can set this to false to block the arc.
Equal Distance To Blocker Override (optional)	An override for the interactor Equal Distance Threshold used when comparing the interactable against other interactables that do not allow teleportation (that is, when Allow Teleport is false).
Tie Breaker Score	Establishes the priority when several interactables are hit at the same time (Equal Distance Threshold) by the arc.
Surface	The `ISurface` that detects the arc. Once the arc hits this surface, the surface provides the hit point and the normal and desired orientation of the player (if any). For a list of ways to use teleports with different surfaces, see Teleporting and Different Surfaces.
Target Point (optional)	The point in space where the player should teleport to.
Face Target Direction	When true, the player will face the same direction as the Target Point’s Z axis.
Eye Level (optional)	When true, it will align the player’s head instead of aligning the player’s feet to the Target Point.

Teleporting and Different Surfaces

Since TeleportInteractable’s Surface property defines the shape of the interactable, you can use different surface components to achieve specific teleportation goals. These surface components are demonstrated in the LocomotionExamples sample scene:

Teleport Type	Description
Hotspot	A `ColliderSurface` can define hotspots in the scene that position the user at a preset location, and optionally set eye height and orientation. In the sample scene, each TeleportHotspot GameObject does this using its `ColliderSurface` component and `TeleportInteractable`’s Target Point, Eye Level, and Face Target Direction properties.
Plane	A `PlaneSurface` component can act as a fallback for the floor. In the sample scene, the HotspotVoidFloor GameObject is the fallback. To act as a fallback, the GameObject should be an infinite plane at the world origin with an extremely low Tie Breaker Score, like -100. The GameObject should also have a `TeleportInteractable` component with the Allow Teleport property unchecked. This way it can act as a blocker for the arc (so it does not fall through the floor) or allow teleporting all around the world floor.
NavMesh	A `NavMeshSurface` bakes precise areas of the scene by defining which meshes of the scene are navigation static and which are not. Nav Mesh Surfaces can reference specific areas of the baked navigation data so the arc can hit them. In the sample scene, the NavMeshHotspotUpstairs GameObject uses a `NavMeshSurface` component.
Physics Layer	A `PhysicsLayerSurface` checks all colliders in the scene in an specific Layer such as the `Default` layer. Physics Layer Surfaces are extremely useful to quickly make all colliders in a scene a teleport target or a blocker for the teleport arc.