Develop

Chapter 6: Built-in Interactions

Updated: Sep 4, 2026

IWSDK can handle browser pointers, XR controller rays, hand input, grabbing, and locomotion. Enable the systems that your app needs, then add interaction components to scene entities.

Enable input features

Configure grabbing and locomotion in iwsdk.config.json:

{
  "world": {
    "xr": {
      "mode": "vr",
      "features": {
        "handTracking": true
      }
    },
    "input": {
      "canvasPointerEvents": true
    },
    "features": {
      "grabbing": true,
      "locomotion": true
    }
  }
}

Canvas pointer events are enabled by default. They let browser clicks and XR rays use the same pointer-event path.

Make an entity selectable

Add RayInteractable for ray or browser-pointer input:

import {
  BoxGeometry,
  Mesh,
  MeshStandardMaterial,
  RayInteractable,
} from '@iwsdk/core';

const cube = new Mesh(
  new BoxGeometry(0.4, 0.4, 0.4),
  new MeshStandardMaterial({ color: 0x3355ff }),
);

world.createTransformEntity(cube).addComponent(RayInteractable);

InputSystem adds the transient Hovered and Pressed tags as pointer state changes. Query those tags from an application system.

Use PokeInteractable for near touch or poke input.

Add grabbing

Grabbing must be enabled in the project manifest. Add one of these components to an entity that can receive pointer hits:

OneHandGrabbable: Moves or rotates an object with one grip.

TwoHandsGrabbable: Supports two-handed manipulation.

DistanceGrabbable: Moves, rotates, or scales an object from a distance.

For example:

import {
  DistanceGrabbable,
  MovementMode,
  RayInteractable,
} from '@iwsdk/core';

world
  .createTransformEntity(mesh)
  .addComponent(RayInteractable)
  .addComponent(DistanceGrabbable, {
    movementMode: MovementMode.MoveFromTarget,
  });

Add locomotion surfaces

When locomotion is enabled, mark walkable scene objects with LocomotionEnvironment:

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

world
  .createTransformEntity(environmentMesh)
  .addComponent(LocomotionEnvironment, {
    type: EnvironmentType.STATIC,
  });

The left thumbstick moves the player. The right thumbstick turns the player. The locomotion system handles collision and ground contact against registered environments.

Enable browser locomotion

A browser-first app can bind keyboard and browser gamepad input to locomotion actions:

{
  "world": {
    "xr": false,
    "features": {
      "locomotion": {
        "browserControls": true
      }
    }
  }
}

The default bindings include WASD, arrow keys, Space, and standard browser gamepads. IWSDK does not supply a browser camera-look mode. Your app remains responsible for pointer lock, orbit, touch-look, or third-person camera behavior.

Troubleshooting

An entity does not receive pointer events

Symptom: A ray or browser pointer reaches the object, but its state does not change.

Solution: Add RayInteractable and confirm that the object’s mesh can be raycast. Also confirm that input is enabled for the selected runtime mode.