# VibeXR

> VibeXR is a single-file WebXR interaction framework: one HTML file, three.js r186 through an import map, no build step. Hands, controllers, gaze / transient pointers and the mouse all share four verbs (point, pinch, poke, grab); hover, drag, two-hand rotate / scale, UI buttons and sliders, the hand menu, passthrough and keyboard + mouse navigation (desktop and in XR) are built in, with every default recorded together with the reason behind it. You build an experience by adding a "world" - a plain object with `init(ctx)` - and deliver one HTML file that runs in the headset browser after tapping "Enter".

## Agent skill

- [VibeXR skill (SKILL.md)](https://vibexr.io/skill/vibexr/SKILL.md): when to use VibeXR, the never-edit-the-framework rule, the workflow, the 12 most important rules and the desktop self-test loop

Important: check `ctx.app.display` (OST optical see-through glasses vs VST passthrough headsets) before laying out; OST has a small field of view and cannot draw black. See the skill's "OST or VST?" section.

## Docs

- [API reference](https://vibexr.io/docs/api.md): world contract and lifecycle (incl. `claimKeys`, `background`), every `ctx` member, Interactable options and events, UI kit, placement, input model incl. keyboard and mouse, `setBackdrop`, config knobs, Hello world
- [Rules](https://vibexr.io/docs/rules.md): 66 defaults, each with its value, why, and what went wrong before (by changelog version)
- [Tutorial](https://vibexr.io/docs/tutorial.md): step-by-step, no XR knowledge needed: install the skill, ask Claude Code for a world, open it locally, put it on a headset, share it through Studio (Chinese: https://vibexr.io/docs/tutorial.zh.md)
- [Examples](https://vibexr.io/docs/examples.md): Hello world, a walkthrough of the built-in Playground world, and recipes (two-hand scaling with limits, poke panel, far-pinch selection, AR vs VR, a stage that faces you, keys and a sky of its own, house UI: hand-menu controls, Enter XR, credits)

## Multiplayer modules

- [net.js](https://vibexr.io/net.js) and [hands.js](https://vibexr.io/hands.js): rooms (MQTT signaling + WebRTC), voice on by default, and other people's real outlined hands; how to use them is in the skill's "Multiplayer" section.

## Publish

- [VibeXR Studio](https://studio.vibexr.io/): upload one HTML world (sign in with GitHub); automatic review (safety scan, test render with a simulated headset) and a human approval, then it gets its own link. Beta.

## Framework

- [vibexr.html](https://vibexr.io/framework/vibexr.html): the framework itself (v0.9.5), a single HTML file with the changelog at the top, plus the display add-on; add your world in a module script after it
- [vibexr-display.js](https://vibexr.io/framework/vibexr-display.js): the display add-on on its own (OST / VST / VR detection, measured FOV, `fitDistance`, `?ost=WxH` simulation)