@holoscript/runtime

HoloScript browser runtime - React Three Fiber integration, event bus, storage, and device APIs.

Installation

npm install @holoscript/runtime

Overview

The runtime is the execution engine that brings HoloScript code to life in the browser. It handles scene rendering, physics, input, trait execution, and provides utility APIs for events, storage, timing, math, and navigation.

Entry Points

| Import | Description | | -------------------------------- | ------------------------------- | | @holoscript/runtime | All APIs | | @holoscript/runtime/events | Event bus | | @holoscript/runtime/storage | Storage adapters | | @holoscript/runtime/device | Device detection | | @holoscript/runtime/timing | Timing utilities | | @holoscript/runtime/math | Math helpers | | @holoscript/runtime/navigation | Client-side routing | | @holoscript/runtime/browser | Scene loader + Three.js runtime | | @holoscript/runtime/global | IIFE bundle for <script> tags |

Usage

Unified Runtime Object

import { runtime, initRuntime } from '@holoscript/runtime';

// Initialize (registers on globalThis.HoloScriptRuntime)
initRuntime();

// Event bus
runtime.on('player:move', (data) => console.log(data));
runtime.emit('player:move', { x: 0, y: 1, z: -2 });

// Storage
await runtime.storage.set('score', 100);
const score = await runtime.storage.get('score');

// Device
if (runtime.device.isVRCapable) {
  /* enter VR */
}

// Timing
runtime.after(1000, () => console.log('delayed'));
runtime.tween(0, 1, 500, (v) => (mesh.opacity = v), runtime.easing.easeOut);

// Math
const pos = runtime.vec3.lerp(start, end, 0.5);

// Navigation
runtime.navigate('/lobby');

Browser Runtime (Three.js)

import { createRuntime } from '@holoscript/runtime/browser';

const rt = createRuntime({
  container: document.getElementById('app'),
  antialias: true,
});

await rt.loadScene('scene.holo');

Event Bus

import { on, once, emit, off } from '@holoscript/runtime/events';

const unsub = on('collision', (data) => {
  /* handle */
});
emit('collision', { objectA: 'ball', objectB: 'wall' });
unsub(); // unsubscribe

Storage

import { get, set, remove, createIndexedDBStorage } from '@holoscript/runtime/storage';

// Default adapter (localStorage with memory fallback)
await set('key', { nested: 'value' });
const data = await get('key');

// IndexedDB for larger data
const db = createIndexedDBStorage('myApp', 'scenes');
await db.set('scene1', largeSceneData);

Device Detection

import { device, isMobile, isVRCapable } from '@holoscript/runtime/device';

if (await device.supportsVR()) {
  /* enable VR button */
}
if (device.prefersReducedMotion) {
  /* disable animations */
}
console.log(device.getMaxTextureSize()); // e.g. 4096

Timing

import {
  after,
  every,
  debounce,
  throttle,
  wait,
  createLoop,
  tween,
  easing,
} from '@holoscript/runtime/timing';

const cancel = every(16, () => update());
const loop = createLoop((delta) => animate(delta));
await wait(1000);
tween(0, 100, 2000, (v) => (el.style.left = v + 'px'), easing.easeOutElastic);

Math

import { lerp, clamp, vec3, distance3D, noise1D, fbm } from '@holoscript/runtime/math';

const v = vec3.normalize(vec3.sub(target, origin));
const d = distance3D(0, 0, 0, 1, 1, 1);
const n = fbm(x * 0.1, 4, 2.0, 0.5); // fractal noise

Trait System

The runtime includes 50+ trait implementations organized by category:

Interaction (18 traits)

GrabbableTrait, ThrowableTrait, PointableTrait, HoverableTrait, ClickableTrait, DraggableTrait, ScalableTrait, CollidableTrait, PhysicsTrait, GravityTrait, TriggerTrait, GlowingTrait, TransparentTrait, SpinningTrait, FloatingTrait, PulseTrait, OutlineTrait, AnimatedTrait

Physics (10 traits)

ClothTrait, SoftBodyTrait, FluidTrait, BuoyancyTrait, RopeTrait, WindTrait, JointTrait, RigidbodyTrait, DestructionTrait, LookAtTrait

AI/Behavior (5 traits)

BehaviorTreeTrait, EmotionTrait, GoalOrientedTrait, PerceptionTrait, MemoryTrait

Extended (11 traits)

RotatableTrait, StackableTrait, SnappableTrait, BreakableTrait, CharacterTrait, PatrolTrait, NetworkedTrait, AnchorTrait, SpatialAudioTrait, ReverbZoneTrait, VoiceProximityTrait

Advanced (10 traits)

TeleportTrait, HandTrackingTrait, HapticTrait, UIPanelTrait, ParticleSystemTrait, WeatherTrait, DayNightTrait, LODTrait, PortalTrait, MirrorTrait

Physics Engine

Built on Cannon.js (cannon-es):

import { PhysicsWorld } from '@holoscript/runtime';

const physics = new PhysicsWorld({ gravity: [0, -9.81, 0] });
physics.addBody('ball', mesh, 'dynamic', 1.0);
physics.onCollision('ball', (event) => console.log('hit!', event));
physics.applyImpulse('ball', [0, 5, 0]);

Peer Dependencies

• react ^18.0.0 (optional)
• @react-three/fiber ^8.0.0 (optional)
• three ^0.160.0 (optional)

x402 Facilitator Verification (server-side)

When you pair runtime content with paywalled routes, use the marketplace API verifier to confirm facilitator-backed x402 receipts over HTTP.

Environment (example):

• X402_VERIFIER_ENABLED=true
• X402_FACILITATOR_URL=https://cdp.coinbase.com/x402
• X402_FACILITATOR_API_KEY=... (optional)
• X402_VERIFIER_TIMEOUT_MS=5000

Minimal usage:

import { createX402HttpVerifierFromEnv } from '@holoscript/marketplace-api';

const verifier = createX402HttpVerifierFromEnv();
const result = await verifier.verifyPayment({
  paymentId: 'pay_abc123',
  transactionHash: '0x...',
  network: 'base',
  asset: 'USDC',
  amount: 0.05,
  contentId: '/api/vrr/phoenix-brew-twin',
});

if (!result.verified) {
  throw new Error(`x402 verification failed: ${result.reason}`);
}

Package boundary & release posture

Audience. @holoscript/runtime is the browser runtime for external app developers, operators, and founder-run teams shipping spatial/VR/AR HoloScript applications — it targets public, consumer-facing builds, not an internal-only harness.

Caller-owned configuration. The runtime takes its container, physics gravity, and storage backend from what the caller passes into createRuntime/initRuntime; the x402 facilitator verifier above is entirely caller-configured through your own environment variables (X402_VERIFIER_ENABLED, X402_FACILITATOR_URL, X402_FACILITATOR_API_KEY). Nothing here is the package default facilitator — you point it at the facilitator and storage backend you operate.

Package boundary. This package does not ship founder-local paths, private workspace fixtures, or embedded credentials; the trait system and physics engine (cannon-es) run entirely client-side against data the caller supplies.

Release posture. Known limitations: the peer-dependency ranges listed for React/Three/@react-three/fiber are more permissive than what's actively validated in CI, and the AI/behavior trait subset is still v0-preview quality — validate them for your use case before depending on their behavior in production. If an upgrade regresses your app, rollback to the previous published version.

License

MIT