@realitycollective/service-framework-three

three.js bindings for the Reality Collective TypeScript Service Framework - a render-loop bridge that connects renderer.setAnimationLoop() to the framework's renderTick scheduler channel, and a WebXR runtime adapter that gives a three.js or desktop app the same RuntimeAdapter surface the IWSDK binding has.

npm install @realitycollective/service-framework @realitycollective/service-framework-three

Services written against BaseService<TConfig> run unchanged on three.js, Babylon.js or IWSDK - only the bridge differs. three is not a dependency of this package: every host type is structural, so the bindings build and unit-test with no renderer, no WebXR and no headset.

Render loop

import { ManualScheduler, ServiceManager, createServiceProfile } from "@realitycollective/service-framework";
import { ThreeRenderLoopBridge } from "@realitycollective/service-framework-three";
import { WebGLRenderer } from "three";

const scheduler = new ManualScheduler();
const manager = new ServiceManager({ scheduler });

manager.initializeProfile(createServiceProfile("my-app", [/* your service registrations */]));
manager.start();

const renderer = new WebGLRenderer({ canvas });
const bridge = new ThreeRenderLoopBridge({ scheduler, host: renderer });
bridge.start();
// Every three.js frame now emits renderTick to all registered services.

host is anything with setAnimationLoop (the AnimationLoopHostLike interface), so a WebGLRenderer, WebGPURenderer or a test double all work.

WebXR runtime adapter

RuntimeAdapter is the seam a service depends on to reach its host: per-frame updates, XR capability flags, and session lifecycle. WebXRRuntimeAdapter implements it over the entry points a browser already provides - navigator.xr to negotiate a session, renderer.xr for the session the renderer presents, and setAnimationLoop for frames. It orchestrates those; it renders nothing, plays nothing and owns no scene state.

import { ManualScheduler, ServiceManager } from "@realitycollective/service-framework";
import { WebXRRuntimeAdapter } from "@realitycollective/service-framework-three";
import { WebGLRenderer } from "three";

const manager = new ServiceManager({ scheduler: new ManualScheduler() });
const renderer = new WebGLRenderer({ canvas });
renderer.xr.enabled = true;

const adapter = new WebXRRuntimeAdapter({
  xr: renderer.xr,
  host: renderer,
  scheduler: manager.scheduler,
  sessionInit: () => ({ optionalFeatures: ["hand-tracking"] })
});

adapter.start();

document.querySelector("#enter-vr")?.addEventListener("click", async () => {
  const result = await adapter.session.request("immersive-vr");

  if (!result.ok) {
    // "unsupported" | "denied" | "timeout" | "error" - a normal runtime
    // outcome, so it comes back as a result rather than a thrown error.
    showEnterVrError(result.reason);
  }
});

Pass the adapter to your services (through their configuration, or a token you register it under) and they read adapter.onFrame, adapter.getCapabilities and adapter.session without knowing three.js exists.

Owning the loop

Given a host, the adapter owns the animation loop: start() binds it, stop() releases it, and each callback becomes one FrameInfo - timestamp in milliseconds, delta in seconds. Given a scheduler as well, the same callback also emits renderTick with source: "three" and deltaTime in milliseconds, exactly as ThreeRenderLoopBridge does, so an app needs one loop owner rather than two. Use the adapter or the bridge, not both.

three.js routes setAnimationLoop through the session's own requestAnimationFrame while presenting, so one call covers both the 2D page and the headset.

Omit host to keep the loop yourself and call adapter.emitFrame(timestamp, delta) per frame.

Sessions

adapter.session is the optional session facet from RuntimeAdapter. request never rejects - a headset that is absent, refused or broken is a normal runtime condition, so every outcome is a result:

Outcome	When
{ ok: true }	the session started, or one was already active
unsupported	there is no navigator.xr, or isSessionSupported(mode) resolved false
denied	the request failed with NotAllowedError or SecurityError - the user, the prompt or the permissions policy refused
timeout	nothing arrived within timeoutMs (default 10000)
error	anything else, with the original error attached

getState() walks "none" -> "requesting" -> "active" -> "ending" -> "none". end() calls session.end() and resolves once the session is gone. onVisibilityChange maps the session's visibilitychange onto "visible", "visible-blurred" and "hidden", and reports "non-immersive" whenever there is no session. A value the adapter does not recognise is reported as "hidden", because treating an unknown state as visible would keep game logic running when it should not.

sessionInit supplies the XRSessionInit per mode - required and optional features - and is called once per request. The default sends none.

One request can add features of its own through SessionRequestOptions, which matters when an app swaps mode mid-session and the host's defaults were chosen for the mode it is leaving:

await adapter.session.request("immersive-ar", {
  requiredFeatures: ["hit-test"],
  optionalFeatures: ["plane-detection"],
});

They are merged over what sessionInit returned rather than replacing it: host entries come first, the request's are appended, and a feature named twice appears once. A request that names none passes the hook's result through untouched. The merge is the core's mergeSessionInit, shared with the Babylon binding so the two cannot drift.

Capabilities

The adapter derives immersive, handTracking, planeDetection, passthrough and environmentBlendMode from the live session with the core's shared deriveCapabilities, which is the same derivation the IWSDK adapter uses. It re-derives when the renderer raises sessionstart or sessionend and when the session raises inputsourceschange, and notifies subscribers only when a flag actually changes. refreshCapabilities() re-reads the renderer on demand, for a host that changes what it presents without raising anything.

setCapabilities({ ... }) is a manual override layer on top: an override wins for as long as it is set, survives every later derivation, and is dropped by clearCapabilityOverrides() or dispose().

The same adapter on the desktop

A desktop build with no headset needs no special case. request returns { ok: false, reason: "unsupported" } where the browser has no navigator.xr or does not support the mode, capabilities stay at the all-false defaults, and frames keep arriving from the same loop. Services gate on getCapabilities() and run either way.

API surface

Symbol	Kind	Purpose
ThreeRenderLoopBridge	class	renderer.setAnimationLoop() to renderTick; start, stop, dispose.
ThreeRenderLoopBridgeOptions	interface	{ scheduler, host }.
AnimationLoopHostLike	interface	Anything with setAnimationLoop.
FIRST_FRAME_DELTA_MS	const	16 - the delta reported for the first frame.
WebXRRuntimeAdapter	class	RuntimeAdapter over WebXR; start, stop, emitFrame, getSession, refreshCapabilities, setCapabilities, clearCapabilityOverrides, session, dispose.
WebXRRuntimeAdapterOptions	interface	{ xr, xrSystem?, host?, scheduler?, sessionInit? }.
WebXRManagerLike	interface	The slice of renderer.xr the adapter drives.
WebXRSystemLike	interface	The slice of navigator.xr it negotiates through.
WebXRSessionLike	interface	The slice of XRSession it reads.
WebXRManagerEventType / WebXRSessionEventType / WebXREventListener	types	The host events it subscribes to.

Live examples

• Weather client walkthrough: service-framework-weather.pages.dev
• Client runtime reference: service-framework-client-app.pages.dev

Documentation

See the repository README and this package's Examples/ folder.

License

MIT - see LICENSE.

Classes

Class	Description
ThreeRenderLoopBridge	Public entry point of the three.js binding: the render-loop bridge, and the WebXR runtime adapter that gives a three.js or desktop app the same RuntimeAdapter surface the IWSDK binding has.
WebXRRuntimeAdapter	-

Interfaces

Interface	Description
AnimationLoopHostLike	The slice of a three.js renderer the bridge and the adapter drive.
ThreeRenderLoopBridgeOptions	-
WebXRManagerLike	The slice of a three.js renderer.xr (WebXRManager) the adapter drives.
WebXRRuntimeAdapterOptions	-
WebXRSessionLike	The slice of an XRSession the adapter reads. It extends the core's CapabilitySessionLike, so a live session goes straight to deriveCapabilities with no mapping.
WebXRSystemLike	The slice of navigator.xr the session facet negotiates through.

Type Aliases

Type Alias	Description
WebXREventListener	Host event callback. The adapter reads the host, not the event object.
WebXRManagerEventType	The events three.js's WebXRManager raises that this adapter listens for.
WebXRSessionEventType	The events an XRSession raises that this adapter listens for.

Variables

Variable	Description
FIRST_FRAME_DELTA_MS	Delta reported for the first frame, where there is no previous timestamp.