xra1

XRAI Runtimes — positioning + comparison

Short answer to “are we using Needle / PlayCanvas / plain Three.js / Icosa / a blend?”:

We’re shipping parallel MIT-licensed adapters, one per major runtime. No blend. No single-runtime lock. Users pick the one that fits their stack. All adapters pass the same conformance suite (runtimes/_conformance/) so XRAI docs are portable across them.

Locking discipline: a runtime is only “locked” as canonical-for-scenario-X after the 7-gate verification in RUNTIMES_EVALUATION.md passes. Today, only Unity is locked (for iOS — CVPR-paper evidence). Three.js adapter is locked only for v1.0 public-spec parse/render. Everything else is NOT LOCKED. Per user directive 2026-04-22: “these are important decisions to triple verify & lock in once we see all is working & scalable & meets objectives.”

---

Shipping matrix (today + near-term)

Runtime	Role	Status	When you pick it
Plain Three.js	Reference runtime — smallest, MIT-only, no vendor deps	✅ shipping — adapter at runtimes/threejs/, 4/4 v1.0 fixtures green	Default for web demos, docs, LLM dogfood. Embedded in any Vite/Next site. Zero install beyond three.
Unity + UnityGLTF + Paint	Canonical engineering runtime — Portals reference impl, shipping on iOS + targeting visionOS via UAAL	✅ shipping (unity/Assets/Scripts/Bridge/SceneComposer.cs) — this is what CVPR paper’s 60 FPS numbers come from	Real AR/VR deployment on mobile + visionOS. Full VFX Graph + Gaussian splat + audio-reactive.
PlayCanvas	Heavier web runtime — PBR, ECS, editor-first workflow	⚠ stub README at runtimes/playcanvas/	Teams already on PlayCanvas + needing a published editor tool + server-backed scenes.
Needle Engine	Unity-authored → web export, good WebXR path (browser XR once Apple unlocks Safari)	⚠ stub at runtimes/webxr/ + see specs/015-visionos-needle-avp/	Web viewers for visionOS Safari WebXR + iOS Go App Clip. NOT for UAAL-embedded runtimes (Needle can’t run embedded).
Unreal	AAA rendering + XR	⚠ stub at runtimes/unreal/	High-fidelity desktop/console/VR; teams already on Unreal.
visionOS RealityKit	Apple-native, full swiftlang	⚠ stub at runtimes/visionos/	Native visionOS apps beyond Safari WebXR. HEDGE-VISIONOS-01 activation trigger.

What Icosa IS and IS NOT

Icosa is NOT an XRAI runtime. It’s:

• a Gallery (publish + discover 3D content — icosa.gallery)
• an API (com.icosa.icosa-api-client-unity, vendored at .xrai/MetavidoVFX-main/Packages/ — wraps import + .tilt ↔ glTF conversion)
• a brush library (AllBrushes.asset with 72 Open Brush descriptors — the source we curate Paint-AR brushes from, per specs/009-paint-ar-openbrush/MIGRATION_PLAN_V2_2026-04-22.md)

Portals publishes TO Icosa Gallery and imports FROM Icosa API via XRAI references (object.glb / future object.tilt entity types). Icosa’s own viewer stays on their site — we don’t embed it, they don’t embed our adapter.

Integration path lives in specs/009-paint-ar-openbrush/MIGRATION_PLAN_V2_2026-04-22.md § 3 "the 4-layer Icosa divide."

Portals’ own web surfaces vs xrai-website’s reference adapters

These are different surfaces, both using Three.js under the hood:

Surface	Path	Purpose	Branding
viewer.portals.app	viewer/ in Portals monorepo	Login-gated Portals Viewer + Editor per spec 014	Portals-branded
RGBD hologram web viewer	web/rgbd-viewer/	LiveKit + Three.js point-cloud for live hologram streaming	Portals-branded
xrai-website runtimes/threejs/	this directory	Public MIT-licensed reference adapter, open for external adoption	XRAI-neutral

The Portals-branded viewers can import the xrai-website adapter verbatim — it’s a superset-compatible MIT loader. Spec 014 has the full positioning.

Why parallel adapters beats “pick one”

• Format neutrality. If XRAI becomes the substrate, it can’t be tied to a single rendering stack. Users who already have a Unity shop, a PlayCanvas editor, an Unreal pipeline, or a visionOS native app all deserve a loader.
• Conformance gate. scripts/xrai_conformance_run.sh runs all v1.0 fixtures through every adapter’s CLI. A divergence in one runtime is caught mechanically. This is how glTF stays portable across 50+ renderers.
• Ecosystem credibility. “XRAI runs on N engines” is a stronger pitch than “XRAI runs on our engine.” The governance-readiness Criterion 2 (≥3 runtimes passing) is the public form of this same bar.

Strategy per question

• “Pick one?” No — parallel MIT adapters.
• “Blend?” No — each runtime keeps its own adapter; users pick per-project.
• “Try each + compare?” Yes for runtime adopters (see conformance results). We document the shipped set here; third parties can add more.
• “Icosa?” Icosa is consumer-side infrastructure (Gallery + import API), not a Portals web runtime target.

Adding a new runtime

1. Create runtimes/<name>/ with a package.json (if JS/TS) + src/cli.js implementing the contract: read XRAI JSON on stdin or file arg, exit 0 on parse success.
2. Write runtimes/<name>/README.md with mapping from XRAI entities/relations to your engine’s primitives.
3. Run scripts/xrai_conformance_run.sh --runtime <name> — it auto-discovers and drops a .ok or .fail marker in _conformance/results/.
4. PR. RFCs (0002, 0003) list the v1.1 additions to expect.

Linked from: README.md Implementation surface, FAQ.md, scripts/governance-readiness.sh.

This site is open source. Improve this page.