@realitycollective/webxr-interactions
The core of the Reality Collective Interaction Extensions. It holds all the interaction logic for WebXR and contains no 3D engine code at all.
Two words are used throughout. An interactable is an object that can be interacted with, such as a button. An interactor is the thing doing the interacting: a hand, controller, ray or mouse.
npm install @realitycollective/webxr-interactions
You usually do not install this directly. Install an adapter for your engine instead. Each adapter re-exports everything here, so your app depends on one package:
threejs-interactions·iwsdk-interactions·xrblocks-interactions
What it provides
| Area | Detail |
|---|---|
| Behaviours | Ready-made interaction types: press (with an optional latching mode that stays down until pressed again), pulse, hinge, dial, slide, grab, and tossScore for throw-and-catch scoring |
| Gaze | Optional look-to-activate. Require the user to be looking before an object responds, or let a sustained look trigger the press by itself |
| Targeting | Picks one target per hand, trying the platform's own answer first, then a close-range touch, then a pointing ray. A short delay stops the target flickering between two objects on a boundary |
| Capability checks | If the headset cannot do what a behaviour needs, the behaviour switches itself off and reports behaviourDisabled, rather than silently doing nothing |
| Events | The core never calls into your code. It emits events and you subscribe |
| Feedback | The core asks for a haptic pulse or a sound. Playing it is your app's job. routeHapticsToProvider is an opt-in helper that sends those requests straight to the controller |
All input arrives through the shared @realitycollective/webxr-input types, so the same core runs on any runtime that has an adapter.
Design rules
- No engine imports. No
three, no@iwsdk/*, noxrblocks. The adapter supplies the code that works out what a ray hits, and the code that moves an object. - Events out, never callbacks in. The core never reaches into your objects.
- Fail loudly, not silently. A behaviour the hardware cannot support reports
behaviourDisabledinstead of quietly doing nothing.
Live demo
The interaction playground - the full station set, mouse-capable on desktop, VR button for headsets: webxr-interactions.pages.dev
Documentation
Full architecture notes, the behaviour catalogue and the playground demo live in the repository README.
License
MIT - see LICENSE.
Classes
| Class | Description |
|---|---|
| DialBehaviour | - |
| DwellState | - |
| Emitter | Minimal synchronous emitter (insertion-ordered, unsubscribe-safe). |
| GrabBehaviour | - |
| HingeBehaviour | - |
| InteractionRuntime | - |
| 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. |
| 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. |
| 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. |
| 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. |