@realitycollective/xrblocks-interactions
EXPERIMENTAL. The XR Blocks pipeline is young and its API still moves. Treat this adapter as a preview and pin your versions.
The Google XR Blocks adapter for the Reality Collective Interaction Extensions. It feeds XR Blocks' input into the @realitycollective/webxr-interactions core, reusing the three.js adapter's hit-testing and object movement.
npm install @realitycollective/xrblocks-interactions three
It re-exports everything from the core, so this is the only interaction package your app needs.
What it binds
| Layer | Detail |
|---|---|
| Input | Input.getFrame() ray sources and direct touches; XR Blocks Script select events |
| Hit-testing | Shared with the three.js adapter |
| No xrblocks dependency | It matches the shape of the XR Blocks API in TypeScript rather than importing xrblocks, so an upstream release cannot break your install |
| Haptics | XR Blocks has none, so haptic requests are reported but never played |
Structurally typed against xrblocks v0.20.0.
Known constraint
xrblocks declares a peer of three@^0.184 while Meta's IWSDK mandates the super-three@0.181 fork. A bundler resolves a single three per bundle, so the pairing works in practice, but npm's peer check cannot express it - the Reality Collective workspaces set legacy-peer-deps=true for this reason.
Peer dependency
three >= 0.170.0.
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 | - |
| InteractionRuntime | - |
| PressBehaviour | - |
| PulseBehaviour | - |
| SlideBehaviour | - |
| ThreeHitTester | 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. |
| ThreeInteractions | - |
| ThreeTransformPort | The transform/effect surface of ONE interactable's scene object. Behaviours write through this; the adapter owns how writes land (Object3D fields, ECS components, …). |
| TossScoreBehaviour | - |
| VelocityTracker | - |
| WebXRInputProvider | - |
| XRBlocksInputProvider | - |
| XRBlocksInteractions | - |
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 | - |
| ThreeInteractionsOptions | - |
| 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 | - |
| WebXRProviderContext | - |
| XBDirectTouchLike | Structural DirectTouchInput. |
| XBFrameLike | - |
| XBRaySourceLike | Structural RaySourceInput (xrblocks src/interaction/InteractionTypes.ts). |
| XRBlocksContext | The slice of the XR Blocks singletons the provider binds to. |
| XRBlocksInteractionsOptions | The slice of the XR Blocks singletons the provider binds to. |
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 `[- |
| connectXRBlocksInteractions | - |
| 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). |
| createThreeInteractions | - |
| 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. |