@iwsdk/locomotor

Locomotion engine for Three.js WebXR applications. Provides physics-based movement, teleportation, and collision detection with BVH-accelerated mesh queries.

Features

• 🚶 Smooth Locomotion - Continuous movement with configurable speed and gravity
• 🎯 Teleportation - Parabolic ray casting for point-and-teleport navigation
• 💥 Collision Detection - BVH-accelerated mesh collision using three-mesh-bvh
• 🌍 Gravity & Physics - Configurable gravity, ground detection, and jump support
• ⚡ Worker Support - Optional Web Worker for off-main-thread physics calculations
• 🎮 Input Agnostic - Works with any input system (controllers, hands, keyboard)

Installation

npm install @iwsdk/locomotor three three-mesh-bvh

Quick Start

import { Locomotor, EnvironmentType } from '@iwsdk/locomotor';
import { Mesh, Vector3 } from 'three';

// Create the locomotion engine
const locomotor = new Locomotor({
  initialPlayerPosition: new Vector3(0, 2, 0),
  useWorker: true, // Run physics in a Web Worker
  rayGravity: -0.4,
  maxDropDistance: 5.0,
  jumpHeight: 1.5,
});

// Initialize (required before use)
await locomotor.initialize();

// Add collision meshes
const floor = new Mesh(/* ... */);
locomotor.addEnvironment(floor, EnvironmentType.STATIC);

// Add moving platforms
const platform = new Mesh(/* ... */);
const platformHandle = locomotor.addEnvironment(
  platform,
  EnvironmentType.KINEMATIC,
);

Update Loop

function update(delta: number) {
  // Request movement from thumbstick input
  locomotor.requestUpdate(
    thumbstickX, // strafe
    thumbstickY, // forward/back
    headPosition,
    headQuaternion,
    shouldJump,
  );

  // Update kinematic (moving) environments
  locomotor.updateKinematicEnvironment(platformHandle, platform);

  // Get resulting position
  const playerPos = locomotor.position;
  const grounded = locomotor.isGrounded;
}

Teleportation

// Cast a parabolic ray for teleportation
locomotor.requestRaycast(rayOrigin, rayDirection, (result) => {
  if (result.hit) {
    // Show teleport indicator at result.point
    teleportMarker.position.copy(result.point);
    teleportMarker.visible = true;
  }
});

// Execute teleport
locomotor.teleportTo(targetPosition);

Configuration Options

interface LocomotorConfig {
  initialPlayerPosition?: Vector3; // Starting position
  updateFrequency?: number; // Physics updates per second (default: 60)
  rayGravity?: number; // Gravity for teleport arc (default: -0.4)
  maxDropDistance?: number; // Max fall distance (default: 5.0)
  jumpHeight?: number; // Jump height in meters (default: 1.5)
  jumpCooldown?: number; // Time between jumps (default: 0.1)
  useWorker?: boolean; // Use Web Worker (default: true)
}

Environment Types

import { EnvironmentType } from '@iwsdk/locomotor';

// Static environments (floors, walls, terrain)
locomotor.addEnvironment(mesh, EnvironmentType.STATIC);

// Kinematic environments (moving platforms, elevators)
locomotor.addEnvironment(mesh, EnvironmentType.KINEMATIC);

Peer Dependencies

• three >= 0.160.0
• three-mesh-bvh >= 0.9.1

Documentation

For more information, visit: https://iwsdk.dev

License

MIT © Meta Platforms, Inc.