Develop

Locomotion Performance

Updated: Sep 4, 2026

IWSDK’s locomotor focuses on character movement: capsule collision, grounding, gravity, jumping, and parabolic hit tests. It is not a general rigid-body solver.

Choose worker or inline execution

Worker execution is enabled by default. It keeps locomotor updates away from rendering work on the main thread.

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

Use inline execution when the application requires same-thread coupling and has measured enough main-thread capacity.

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

The current WorldOptions.features.locomotion and LocomotionSystem schemas do not expose an updateFrequency setting. Do not pass that field to these APIs.

Register collision environments once

Use a static environment for geometry whose world transform does not change.

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

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

The locomotor merges the walkable hierarchy and builds an acceleration structure when the environment is registered. Avoid removing and re-adding static geometry during normal frame updates.

Use kinematic environments for moving surfaces

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

platform.addComponent(LocomotionEnvironment, {
  type: EnvironmentType.KINEMATIC,
});

IWSDK sends updated world transforms for kinematic environments. The locomotor derives platform motion for a grounded player.

Author collision geometry

Remove triangles that the player cannot reach.

Avoid thin collision features near the capsule radius.

Split distant regions when separate bounds improve broad-phase rejection.

Keep moving platforms kinematic instead of rebuilding static environments.

Test stairs, slopes, doorways, and platform edges at headset frame rates.

The default player capsule radius used for locomotion is 0.5 meters. Size traversable spaces with the player collider in mind.

Profile the complete frame

Worker mode reduces main-thread competition, but rendering, input, scene systems, and message handling still share the frame budget. Measure CPU and GPU time with production content on the target device.

See Locomotion overview and Slide locomotion.