Build your first
presence application.

01 / INSTALL

Start from a verified local package.

The private alpha requires Node.js 20 or later and an ESM application. It has no external runtime dependencies and is installed from an approved source checkout.

npm install /path/to/realityrelay-platform

02 / CORE MODEL

Scene → Space → Session.

The adapter owns endpoint commands. The Runtime owns compatibility and lifecycle. The Scene never contains vendor-specific hardware instructions.

03 / SESSION

Run the complete lifecycle.

import {
  RuntimeEngine,
  InMemoryEndpointAdapter
} from "@reality-relay/sdk";

const runtime = new RuntimeEngine();

runtime.on("*", ({ type, detail, timestamp }) => {
  console.log(timestamp, type, detail);
});

runtime.registerEndpoint(endpoint, new InMemoryEndpointAdapter());
runtime.registerScene(scene);

const session = await runtime.startSession({
  endpointId: endpoint.id,
  sceneId: scene.id
});

await runtime.pause(session.id);
await runtime.play(session.id);
await runtime.stop(session.id);

One active Session owns a Space at a time. The included in-memory adapter records the complete command sequence but never controls physical hardware.

04 / COMPATIBILITY

Explain a mismatch before connecting.

const report = evaluateSceneCompatibility(endpoint, scene);

if (!report.compatible) {
  console.error(report.missingCapabilities);
}

The report includes required, available and missing capabilities, plus endpoint mode and native resolution. Structural contract errors still throw; a factual capability mismatch does not need exception parsing.

05 / ENDPOINT ADAPTER

Connect one real Space without contaminating the platform.

class PortraitHldAdapter {
  async connect(profile) { /* open endpoint */ }
  async configure(calibration) { /* apply versioned profile */ }
  async prepare(scene) { /* load compatible content */ }
  async play() { /* begin presentation */ }
  async pause() { /* hold deterministic state */ }
  async stop() { /* stop safely */ }
  async disconnect() { /* release resources */ }
  async health() { return { ready: true, state: "ready" }; }
}

• Declare only capabilities the endpoint actually supports.
• Make stop and disconnect safe during recovery.
• Report hardware faults instead of masking them.
• Never mark content physically approved without evidence.

06 / PRESENCE CHECK

Validate belonging, not just pixels.

A Presence Profile defines safe area, contact line, shadow band, camera rules and display lighting for one calibrated Space.

const profile = validatePresenceProfile(input);
const result = evaluatePresenceAnalysis(profile, analysis);

// "blocked" | "review" | "passed"
console.log(result.status, result.blockers, result.warnings);

Any blocker wins. Floating feet, detached shadows or a subject outside the safe area cannot be hidden by an average score.

07 / AI VIDEO

Compile a display-native plan.

const plan = service.createPlan({
  providerId: "deterministic-video-simulator",
  presenceProfile,
  brief: {
    subject: "a life-size remote expert",
    action: "welcome, then return to neutral",
    durationSeconds: 8,
    loop: true,
    referenceImage: { uri: "asset://approved-frame.png" }
  }
});

The plan fixes the 1080 × 1920 master, prompt constraints, repair path, evidence requirements and publication ceiling. The included provider is a simulator and produces no media.

08 / TROUBLESHOOTING

Diagnose with structured evidence.

INCOMPATIBLE_ENDPOINT

Inspect missingCapabilities; do not invent endpoint support.

ENDPOINT_BUSY

Stop the active Session or choose another Space.

INVALID_GROUNDING

Provide normalized contact and shadow values for a grounded Scene.

UNSUPPORTED_OPERATION

The adapter lacks the optional live parameter method.

Simulated generation

The deterministic provider is working as designed; it never produces publishable media.

When reporting an issue, include SDK and Node versions, endpoint mode and capabilities, Scene ID/version, Runtime error code/details and ordered Runtime events. Never include credentials or private customer media.