Develop

Locomotion Overview

Updated: Sep 4, 2026

IWSDK combines slide, teleport, and turn behavior under LocomotionSystem. The system owns a shared @iwsdk/locomotor engine and an action-based input provider.

Enable locomotion

Use the World feature option for the standard configuration.

import { SessionMode, TurningMethod, World } from '@iwsdk/core';

const world = await World.create(document.getElementById('scene')!, {
  xr: { sessionMode: SessionMode.ImmersiveVR },
  features: {
    locomotion: {
      useWorker: true,
      comfortAssistLevel: 0.5,
      turningMethod: TurningMethod.SnapTurn,
      enableJumping: true,
    },
  },
  level: '/scenes/main.iwsdk.scene.json',
});

Import locomotion components and systems from the @iwsdk/core package root.

Mark walkable geometry

Add LocomotionEnvironment to a transform entity that contains collision geometry.

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

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

Use EnvironmentType.KINEMATIC for a moving platform whose world transform changes after registration.

Movement systems

Slide reads the locomotion.move action, applies planar velocity, and supports jumping and a comfort vignette.

Teleport draws a parabolic guide, validates a walkable target, and moves the player.

Turn applies snap or smooth yaw to the player rig.

LocomotionSystem registers these child systems and supplies their shared input provider and locomotor. Do not register a child system without those dependencies.

Tune the running system

The parent system exposes configuration signals.

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

const locomotion = world.getSystem(LocomotionSystem)!;
locomotion.config.slidingSpeed.value = 4;
locomotion.config.turningMethod.value = TurningMethod.SmoothTurn;
locomotion.config.turningSpeed.value = 120;
locomotion.config.rayGravity.value = -0.4;

TurningMethod has two values: SnapTurn and SmoothTurn.

Input actions

The standard provider consumes these actions:

locomotion.move
locomotion.turn
locomotion.jump
locomotion.teleportAim

locomotion.teleportCommit is reserved in InputActions. The standard input provider commits a teleport when locomotion.teleportAim is released and does not read the reserved action.

XR bindings are enabled by the locomotion system. Set browserControls: true in the World locomotion option to add keyboard and standard browser-gamepad bindings.