@realitycollective/iwsdk-interactions
The Meta IWSDK adapter for the Reality Collective Interaction Extensions. It connects the @realitycollective/webxr-interactions core to Meta's Immersive Web SDK.
npm install @realitycollective/iwsdk-interactions @iwsdk/core
It re-exports everything from the core, so this is the only interaction package your app needs.
What it binds
| Layer | Detail |
|---|---|
| Input | IWSDK's player rig, controller state and hand joints |
| Targeting | IWSDK already knows what is being pressed or grabbed, through its Pressed and Grabbed tags. The adapter passes that answer straight through instead of working it out again with rays |
| Grab | Where the app has IWSDK grabbing or physics turned on, IWSDK performs the grab itself |
| Setup | One call: registerInteractions(world) |
Usage
import { registerInteractions } from "@realitycollective/iwsdk-interactions";
const interactions = registerInteractions(world);
interactions.register({ id: "handle", behaviours: [{ kind: "grab" }] }, entity);
interactions.runtime.onEvent((event) => console.log(event.type));
registerInteractions is idempotent per world and registers the bridge system for you; the render loop is driven by IWSDK, so there is no update call to make.
Peer dependencies
@iwsdk/core >=0.5.0 <0.6.0. The adapter is source-compatible with 0.4.x, but 0.5 is the only line CI exercises, so that is the only line supported.
@iwsdk/xr-input >=0.5.0 <0.6.0 and three >=0.170.0. Every IWSDK application already has both: @iwsdk/core installs @iwsdk/xr-input, and IWSDK projects carry three (aliased to super-three). The adapter imports three.js classes from three and InputComponent from @iwsdk/xr-input directly, rather than through @iwsdk/core's star re-exports, so it prebundles even when an application excludes one of those packages from Vite's dependency optimizer to transform its source.
Live demo
The interaction playground - the full station set, mouse-capable on desktop, VR button for headsets: webxr-interactions.pages.dev
Documentation
See the repository README.
License
MIT - see LICENSE.
Classes
| Class | Description |
|---|---|
| DialBehaviour | - |
| DwellState | - |
| Emitter | Minimal synchronous emitter (insertion-ordered, unsubscribe-safe). |
| GrabBehaviour | - |
| HingeBehaviour | - |
| InteractionBridgeSystem | The per-frame bridge: IWSDK tags → provider hints → runtime tick. |
| InteractionRuntime | - |
| IWSDKInputProvider | - |
| IWSDKInteractions | - |
| IWSDKTransformPort | The transform/effect surface of ONE interactable's scene object. Behaviours write through this; the adapter owns how writes land (Object3D fields, ECS components, …). |
| PressBehaviour | - |
| PulseBehaviour | - |
| SlideBehaviour | - |
| TossScoreBehaviour | - |
| VelocityTracker | - |
Interfaces
| Interface | Description |
|---|---|
| Behaviour | - |
| BehaviourContext | Everything a behaviour can reach during a tick or a routed moment. |
| BehaviourFactoryContext | - |
| DialConfig | - |
| DwellConfig | Gaze support - first-class, per the design decision that gaze serves two roles: |
| DwellTick | - |
| FeedbackAudioSink | Whatever the client uses to play a sound. Deliberately tiny: an id the client resolved to a buffer/sample of its own, and a gain. The core never loads, decodes or owns audio. |
| FeedbackIntent | - |
| GazeConfig | - |
| GrabConfig | - |
| HingeConfig | - |
| HitTester | Resolves which interactable a ray or a proximity probe touches. Implemented by the adapter (three.js Raycaster, engine BVH, …). A provider that pre-resolves targeting (IWSDK) may make this redundant - provider hints always take precedence over hit-tester results. |
| InteractableDescriptor | - |
| InteractableHit | - |
| InteractableState | - |
| InteractionDescriptor | - |
| InteractionEvent | - |
| InteractionRuntimeOptions | - |
| InteractorInfo | The slice of a live interactor a behaviour may consume. |
| IWSDKProviderOptions | - |
| IWSDKRegisterEntityOptions | - |
| IWSDKRegisterOptions | - |
| PointerBridge | - |
| PressConfig | - |
| PulseConfig | - |
| RegisterPorts | - |
| SlideConfig | - |
| TossScoreConfig | - |
| TransformPort | The transform/effect surface of ONE interactable's scene object. Behaviours write through this; the adapter owns how writes land (Object3D fields, ECS components, …). |
| VelocityTrackerOptions | - |
Type Aliases
| Type Alias | Description |
|---|---|
| BehaviourConfig | - |
| FeedbackCue | A named moment a client may want to sonify/hapticise. |
| FeedbackListener | - |
| GrabFulfilment | - |
| InteractionEventListener | - |
| InteractionEventType | - |
| TransformOwnership | Who owns the interactable's transform while this behaviour is active. |
Variables
| Variable | Description |
|---|---|
| DWELL_DEFAULTS | - |
| HEAD_GAZE_INTERACTOR_ID | Interactor id used when gaze is synthesized from the head pose. |
Functions
| Function | Description |
|---|---|
| centeredUnit | Map a centered hinge angle in `[- |
| clamp01 | Clamp to the unit interval. |
| clampDeadzone | Zero out a signal below threshold, leaving larger values untouched. |
| clampSym | Clamp a value to the symmetric range `[- |
| createBehaviour | - |
| createPointerBridge | Create a pointer stream from the runtime's sampled sources. match picks which source drives it (default: any source with a ray - first pressed wins and holds until release). |
| decay | Exponential decay of value toward 0 over dt at ratePerSec. |
| easeOutBounce | Penner's ease-out-bounce on t ∈ [0,1]. |
| hingeAngleToHand | Hinge angle for a position-driven lever: given the hand's offset from the pivot resolved into the hinge plane - alongRest (toward the arm's rest direction) and alongSwing (the in-plane perpendicular) - the angle the arm should take to point at the hand, clamped to `± |
| holderPoint | Hand position a hand-driven behaviour should track, best available. |
| interactionsFor | - |
| normalize01 | Normalize a measured displacement/angle against a signed range to 0..1. Sign-agnostic: a range of -π/2 maps -π/2 → 1. |
| passedThroughHoop | Did a tossed object pass through a hoop this frame? True when it crossed the hoop plane in the scoring direction (downward - prev above, curr at/below) while inside the ring (radial <= radius). |
| quatConjugate | - |
| quatFromAxisAngle | Quaternion from an axis (normalised) and an angle in radians. |
| quatMultiply | - |
| rayAngleTo | Angular offset (radians) between a ray direction and the direction to a point. |
| rayPointDistance | Closest-approach distance from a ray to a point, and the along-ray t. |
| registerBehaviourKind | - |
| registerDescriptor | Build a runtime's interactables from a portable descriptor. |
| registerInteractions | Register the Interaction Extensions on an IWSDK world (one call). |
| resolveDwellConfig | - |
| routeAudioToSink | Client opt-in: play a sound for the feedback intents named in cueMap. Cues absent from the map are ignored, so an app sonifies only the moments it has sounds for. Gain is the intent's intensity scaled by gainScale, capped at 1. Returns the unsubscribe. |
| routeHapticsToProvider | Client opt-in: forward the haptic half of feedback intents to the input provider's pulse (which no-ops on sources without actuators - hands). Returns the unsubscribe. Audio remains entirely the client's concern. |
| springStep | One step of a damped harmonic oscillator (semi-implicit Euler). out[0] = next value, out[1] = next velocity. An under-damped spring (damping ratio ≈ 0.3-0.5) is what gives a pressed button its bounce. dt is clamped to 1/30 s so a long frame can't blow the integrator up. |
| vAdd | - |
| vApplyQuat | Rotate a vector by a quaternion. |
| vCross | - |
| vDistance | - |
| vDot | - |
| vLength | - |
| vNormalize | - |
| vScale | - |
| vSub | - |
| worldToLocal | Transform a world-space point into the local frame of pose. |