@realitycollective/service-framework

The core runtime of the Reality Collective Service Framework for TypeScript - dependency injection, service lifecycle, events, schedulers and configuration, for browser and app runtimes.

npm install @realitycollective/service-framework

A TypeScript-first implementation of the same architecture as the Reality Collective Unity Service Framework: services are registered into a profile, resolved by token, and driven by a scheduler that the host environment owns.

What it provides

| Area | Detail | | --- | --- | | Service manager | Registration, dependency-ordered start/stop, resolution by token, wait-for-service | | Base services | BaseService and BaseServiceModule - lifecycle hooks with typed configuration | | Tokens | createServiceToken<T>() - type-safe resolution with no string keys at the call site | | Scheduler | Named channels such as renderTick that services subscribe to. Your app decides what drives them: a timer, a render loop, or manual ticks | | Events | An in-framework event service for service-to-service messaging | | Configuration | Profile-based configuration with environment awareness | | Runtime adapter | RuntimeAdapter - the host seam a service depends on: a per-frame fan-out, XR capability flags, and an optional session facet (request, end, state and visibility). Host bindings implement it | | Session features | SessionRequestOptions.requiredFeatures and optionalFeatures - WebXR feature strings for one request, merged over the host's own defaults by mergeSessionInit(init, options). An app that swaps mode mid-session needs them, because the host's defaults were chosen for the mode it is leaving | | Capability derivation | deriveCapabilities(session) - reads immersive, handTracking, planeDetection, passthrough and environmentBlendMode off a live XR session. Shared by every host binding, so the same session reports the same flags under IWSDK and three.js. Its input, CapabilitySessionLike, is structural: no WebXR types, no DOM | | State-owning services | SnapshotService<TConfig, TSnapshot> - one immutable snapshot plus pub/sub; subscribers get the current value immediately, then every publish | | Headless testing | MockRuntimeAdapter - drives frames, capabilities and session lifecycle with no engine, no WebXR and no headset | | Adapter conformance | runtimeAdapterContractCases() - the checks every RuntimeAdapter must pass, shipped as data rather than as a test file, so an adapter written outside this repository can prove it conforms |

EnvironmentDescriptor here means the platform environment - the host's name and its capability strings, such as "dom" or "render-loop" - and is not the same thing as EnvironmentSpec in @realitycollective/webxr-environment, which describes the visual environment of sky, fog and lighting. An app can hold both at once, so the two names are worth keeping apart.

Usage

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

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

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

The host decides what drives the scheduler - a timer, a render loop, or an XR frame source.

Host bindings

The core is host-agnostic. Add exactly one binding for your runtime:

| Package | Host | | --- | --- | | service-framework-react | React provider and hooks | | service-framework-three | three.js render loop, plus a WebXR runtime adapter for any page that owns its renderer | | service-framework-babylon | Babylon.js render loop | | service-framework-iwsdk | Meta IWSDK (WebXR) frame source | | service-framework-client | React + three.js, already wired together |

Writing your own binding

An adapter for a host nobody has covered yet has to behave exactly as the bindings above do, or a service that passes its unit tests stops behaving the same way on a headset. runtimeAdapterContractCases() is the set of checks that says so, shipped as data rather than as a test file so it can run in your repository under your own runner. Each case returns silently on success and throws a plain Error describing the failure otherwise:

import { runtimeAdapterContractCases } from "@realitycollective/service-framework";

for (const contractCase of runtimeAdapterContractCases()) {
  it(contractCase.name, () => contractCase.run(makeSubject()));
}

makeSubject() returns a RuntimeAdapterSubject: your adapter, plus a RuntimeAdapterDriver that pushes a frame, sets capability flags and - if your host owns sessions - starts and ends one. Build a fresh subject per case, because the session cases drive a session through its whole lifecycle. Some cases are asynchronous, so the runner has to await what run returns. An adapter with no session facet passes the session cases without running them, since session is optional.

Live examples

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

Documentation

Architecture, service authoring and consumption patterns are documented in the repository, including a Unity-to-web migration guide. A runnable example ships in this package's Examples/ folder.

License

MIT - see LICENSE.