API Reference

XR Interface (v0.0.1) - Complete documentation for spatial DOM manipulation. Most 3D manipulation methods are asynchronous and return a Promise.

1. Initialization & Setup

XRi.initWebXR(enable, customUrl)

Enables or disables the automatic WebXR fallback for users without the native app.

enable (boolean): Default true.
customUrl (string): Target URL for the WebXR viewer. Default: "https://xri.onl/web/".

XRi.initWebXR(true, "https://xri.onl/web/");

XRi.initMultiplayer(manualSession, url)

Initializes a WebSocket connection to synchronize the AR environment across multiple headsets/clients.

manualSession (string): Room ID. If null, looks for ?session= in the URL.
url (string): WebSocket server URL. Default: "wss://xri.onl/multiplayer".

XRi.initMultiplayer("room_123");

XRi.noCache()

Forces a page reload with a new timestamp parameter (?v=timestamp) to bypass browser cache. Throttled to 5 seconds.

2. Spawning & Global Management

XRi.spawn(id, url, scale, position, rotation, usePreciseCollider, isGlobal)

Spawns a 3D model into the physical space. Returns an instance of XRiObject.

id (string): Unique identifier for the object.
url (string): URL/Path to the 3D model (e.g., .glb).
scale (number): Initial scale. Default: 0.1.
position (object): {x, y, z} coordinates. Default: {x:0.3, y:1, z:0.5}.
rotation (object): {x, y, z} rotation in degrees. Default: {x:0, y:0, z:0}.
usePreciseCollider (boolean): Generates an exact mesh collider if true. Default: false.
isGlobal (boolean): Broadcasts the spawn to multiplayer clients. Default: true.

const duck = await XRi.spawn("duck_1", "assets/duck.glb", 0.8);

XRi.getClassById(id, isGlobal)

Returns an existing XRiObject instance linked to an ID already spawned in the scene.

const duck = XRi.getClassById("duck_1");

XRi.getAllObjects()

Fetches a list of all currently spawned objects from the Unity engine. Returns a Promise resolving to an array.

const objects = await XRi.getAllObjects();

XRi.clearAll(isGlobal)

Destroys all objects in the scene immediately.

XRi.clearAll();

XRi.generateId()

Returns a random unique string identifier (e.g., "id_a1b2c3d").

3. Object Manipulation (XRiObject)

These methods are called directly on the instance returned by XRi.spawn() or XRi.getClassById(). Most methods accept a duration parameter (in seconds) for smooth transitions.

.move(direction, duration)

Moves the object relatively to its current position.

direction (object): {x, y, z} offset.

await duck.move({x: 0, y: 0.5, z: 0}, 1.0); // Moves up 0.5m in 1s

.setPosition(position, duration)

Moves the object to an absolute position in the physical space.

await duck.setPosition({x: 1, y: 0, z: 1}, 2.0);

.rotate(rotation, duration)

Rotates the object. Accepts either a number (Y-axis rotation) or an object {x, y, z}.

await duck.rotate(90, 1.0); // 90 degrees on Y axis
await duck.rotate({x: 45, y: 90, z: 0}, 1.0);

.resetRotation(duration)

Smoothly resets the object's rotation back to {0, 0, 0}.

.zoom(multiplier, duration)

Scales the object relatively to its current size. The value acts as a multiplier.

await duck.zoom(1.5, 1.0); // Increases the current size by 50% (1.5x) over 1 second

.setScale(absoluteScale, duration)

Sets the object to an absolute scale (in meters), regardless of its original or current size.

await duck.setScale(1.5, 1.0); // Forces the object to become exactly 1.5 meters large over 1 second

.getPosition()

Requests the current absolute coordinates of the object. Returns a Promise resolving to {x, y, z}.

const pos = await duck.getPosition();

4. Physics & Behavior

.setGrabbable(isGrabbable)

Enables or disables hand-tracking interaction, allowing the user to grab and move the object physically.

await duck.setGrabbable(true);

.setGravity(useGravity)

Applies real-world physics and gravity to the object, causing it to fall and collide with the physical floor/tables.

await duck.setGravity(true);

.lookAt(enable)

Enables billboarding. The object will constantly rotate to face the user's headset.

await duck.lookAt(true);

.setVisible(isVisible)

Hides or shows the 3D model without destroying it.

await duck.setVisible(false);

5. Animation & Hierarchy

.startAnimation(animationName)

Triggers an embedded animation inside the model file.

await duck.startAnimation("Walk");

.stopAnimation()

Stops the currently playing animation.

.parent(parentId)

Parents this object to another spawned object. If the parent moves, the child moves with it.

await duck.parent("table_1");

.destroy()

Permanently removes the object from the physical space and frees its memory.

await duck.destroy();

6. Global Callbacks

You can define these functions globally in your window object to listen to Unity engine events.

window.handleSelection(id)

Triggered when the user physically grabs an object with their hands.

window.handleSelection = function(id) {
    console.log("User grabbed: " + id);
};

window.handleRelease(id)

Triggered when the user releases a previously grabbed object.

window.log(message, colorCode)

Overrides the internal XRi debug logger. Useful for printing custom UI logs inside the headset.