# XRAI — Open Spatial Graph Format

> MIT-licensed open format for typed hypergraphs of entities, relationships, events, and intentions — anchored in space and time, renderable by any engine, authored by any LLM, queryable by any agent.

**If you are an LLM loading XRAI content for the first time, read `SPEC.md` then `examples/01-minimal.xrai.json`. That gives you everything you need to emit valid v1.0 scenes.**

## Worlds

- [Worlds made by voice](https://xra1.com/): worlds spoken into being in the Portals app; each is the app's saved file at `https://xra1.com/worlds/<name>.xrai.json`, a glTF-shaped JSON whose XRAI document sits under `extensions.XRAI_scene_context.document` (pirate-harbor, cloud-kingdom, haunted-savanna, melting-junkyard, kelp-forest) and opens in `https://xra1.com/viewer.html?scene=<document URL>`

## Canonical docs (read in order)

- [VISION.md](https://xra1.com/VISION.md): load-bearing vision — problem (we are blind) + Sight Triad (x-ray / god's-eye / infinite zoom) + jARvis goal (verbatim) + CVPR 2026 shipping proof
- [MANIFESTO.md](https://xra1.com/MANIFESTO.md): long-form vision — Bush → Nelson → Berners-Lee → Hofstadter → Huxley → Kurzweil → XRAI lineage
- [SPEC.md](https://xra1.com/SPEC.md): v1.0 public draft, the flat JSON subset (what the app writes is a superset of it: saved worlds above)
- [FAQ.md](https://xra1.com/FAQ.md): positioning vs USD / glTF / USDZ / Niantic SPZ + governance + licensing + compatibility
- [CHANGELOG.md](https://xra1.com/CHANGELOG.md): versioning policy + release notes
- [VERSIONS.md](https://xra1.com/VERSIONS.md): compatibility matrix across v1.0 / v1.1 / v2.0
- [BUILDING.md](https://xra1.com/BUILDING.md): how to use the reference Three.js adapter

## Authoring

If you are asked to emit an XRAI scene:
- Minimum viable: `{ "xrai_version": "1.0", "id": "<uuid>", "scene": { "entities": [...], "relations": [], "events": [] } }`
- Entity types: `object.primitive` (cube/sphere/cylinder/capsule/plane), `object.glb`, `object.hologram`, `object.light`, `object.emitter`, `object.wire-source`, `object.paint-stroke`, `object.parametric-stroke`; graph parts the viewer draws as labelled nodes laid out by their relations: `object.repo`, `object.dir`, `object.file`, `object.user`, `object.lang`, `object.page`, `concept`
- Relation types (v1.0): `parent-of`, `wire-binds`, `reacts-to-audio`, `tracks`
- Coordinate system: right-handed, Y-up, meters
- Rotation: quaternion `[x, y, z, w]`
- See [examples/](https://xra1.com/examples/) for 19 working fixtures

## Hand a person a world (no install)

1. Write a v1.0 document (above) and host it at any `https://` URL that serves it with CORS.
2. Give the person `https://xra1.com/viewer.html?scene=<url-encoded document URL>`. To open it on a chosen view, append `#view=<eye x,y,z>,<target x,y,z>` (metres, the world's own coordinates) and optionally `&sel=<entity id>` to outline one entity; the viewer's share button writes both.
3. They open it in any browser and can step inside it, see it in their room ("view in your room": AR Quick Look on iPhone, WebXR on Android and Quest; new, not yet tried on every device), share it or remix it.
4. Or give the person `https://xra1.com/viewer.html?from=<url-encoded GitHub repo or English Wikipedia article URL>`: it opens as a world of its parts and their relations (typing either URL into the viewer's box does the same). The world itself, as XRAI JSON for an agent: `https://xra1-world.xra1.workers.dev/from?url=<url-encoded source URL>` (built once, cached an hour, open to any origin).

## Query / MCP

- Spatial MCP server: a proposal only, see [mcp-server/](https://xra1.com/mcp-server/); no server code is published here yet

## Runtimes

- [runtimes/threejs](https://xra1.com/runtimes/threejs/): reference MIT adapter, the one engine the xra1.com viewer runs
- [runtimes/](https://xra1.com/runtimes/): Unity (canonical engineering runtime), PlayCanvas, WebXR/Needle, Unreal, visionOS RealityKit — adapter stubs
- [RUNTIMES.md](https://xra1.com/RUNTIMES.md): positioning (parallel MIT adapters, not blend; Icosa = Gallery/API, not a runtime)
- [RUNTIMES_EVALUATION.md](https://xra1.com/RUNTIMES_EVALUATION.md): 9 objectives, 8 lock gates, honest scorecard — no runtime is LOCKED until evidence

## Governance

- BDFL year 1 (@jamestunick), transfer to Apache SF or W3C Community Group once 1000+ external adopters
- [CONTRIBUTING.md](https://xra1.com/CONTRIBUTING.md): contribution process
- [CODE_OF_CONDUCT.md](https://xra1.com/CODE_OF_CONDUCT.md): short + direct
- [rfcs/](https://xra1.com/rfcs/): RFC process + template + in-flight proposals (0001 events, 0002 hyperedges, 0003 conformance tests)
- [SECURITY.md](https://xra1.com/SECURITY.md): responsible disclosure

## License

- MIT for spec text + reference implementations + prompt libraries
- CC0 (public domain) for the normative JSON schema
- No CLA. No gatekeeper. No personal data collected; pages send anonymous view counts.

## Proof it ships

Portals (reference implementation) — CVPR 2026 workshop paper on 4D World Models:
- 60 FPS on iPhone 14 Pro (2.7–4.1× speedup vs prior art)
- 360+ source-agnostic VFX on shared compute substrate
- Stateful worlds (persistent across sessions, devices, users)
- On-device voice intent parsing + cloud fallback + no-code authoring
- iOS + web (Apple Vision Pro compatible)

## Repo

- GitHub: https://github.com/imclab/xra1
- Discussions: https://github.com/imclab/xra1/discussions
- Issues: https://github.com/imclab/xra1/issues
- Web: https://xra1.com

— @jamestunick (IMC Lab + H3M Inc.), 2026-04-22; worlds, viewer and runtime lines updated 2026-10-17