Develop

Teleportation

Updated: Sep 4, 2026

Teleportation uses a parabolic guide and a validated landing marker. LocomotionSystem creates TeleportSystem after its shared locomotor is initialized.

Enable teleportation

Enable the parent locomotion feature and register walkable geometry.

import { EnvironmentType, LocomotionEnvironment, World } from '@iwsdk/core';

const world = await World.create(container, {
  features: { locomotion: true },
});

const floor = world.createTransformEntity(floorModel);
floor.addComponent(LocomotionEnvironment, {
  type: EnvironmentType.STATIC,
});

The parent system supplies TeleportSystem with both required dependencies: its Locomotor instance and shared action input provider.

Aim and commit

The controller binding uses the locomotion teleport action to start aiming. While active, the system:

Reads the right ray origin and direction.

Requests a parabolic hit test from the locomotor.

Draws the guide and landing marker.

Accepts a hit when the surface normal’s Y component is greater than 0.7.

Teleports on deactivation when the last target is valid.

The system suppresses teleport aiming while the right ray is busy with another captured interaction.

Configure the arc

Change the parent system’s rayGravity signal. The parent forwards the value to the locomotor and teleport child.

import { LocomotionSystem } from '@iwsdk/core';

const locomotion = world.getSystem(LocomotionSystem)!;
locomotion.config.rayGravity.value = -0.5;

More-negative values bend the arc downward faster. Use one value for both the visual guide and collision query; the parent system keeps them aligned.

Surface requirements

Teleport targets come from entities registered as LocomotionEnvironment. A visible hit is not sufficient when the surface is too steep; the upward-normal test rejects it.

import { EnvironmentType, LocomotionEnvironment } from '@iwsdk/core';

walkableEntity.addComponent(LocomotionEnvironment, {
  type: EnvironmentType.STATIC,
});

Use clean collision geometry and verify the intended floors, ramps, and platforms on device.

System ownership

Do not register TeleportSystem by itself unless application code provides a compatible locomotor and inputProvider. The supported application path is to enable or register LocomotionSystem and let it own its child systems.

See Locomotion overview and Turning.