# XRi.js - Spatial DOM & WebXR SDK (Full Reference)
> XRi.js is a zero-config spatial computing and WebXR JavaScript library. It provides a 5-level progressive enhancement for AR/3D web integration, a built-in Unity (Vuplex) bridge, and native P2P multiplayer via WebSockets with remote execution capabilities.

## 1. Core Architecture
The SDK exposes a global `window.XRi` instance (based on `XRiBridge`) and returns `XRiObject` instances for specific 3D model manipulation. All asynchronous manipulation methods return Promises.

* **Mandatory Import:** `<script src="https://xri.onl/XRi.js"></script>`
* **Asset Rule:** All 3D models (.glb, .usdz) MUST use absolute `https://` URLs.
* **Target Platforms:** PC (Model-viewer), iOS (Quick Look), Android Mobile (WebXR), Headsets (Full WebXR), Native XRi App (Full Physics Unity Bridge).

## 2. Global Initialization & Multiplayer
- `XRi.initWebXR(enable = true, customUrl = "https://xri.onl/web/")`: Initializes the environment. If the native wrapper (Vuplex) is missing, it automatically triggers the URL-based fallback to the WebXR viewer.
- `XRi.initMultiplayer(manualSession = null, url = 'wss://xri.onl/multiplayer', mode = 'append')`: Connects to the WebSocket room (reads `?session=...` from URL by default). Enables state synchronization and Remote Execution (`eval` of server events).

## 3. Global API (XRi Bridge)
These methods control the scene and spawn objects. By default, `isGlobal = true` broadcasts the command to all connected users in the multiplayer session.
- `XRi.spawn(id, url, scale = 0.1, position = {x:0.3, y:1, z:0.5}, rotation = {x:0,y:0,z:0}, usePreciseCollider = false, isGlobal = true)`: Spawns a 3D object and triggers fallbacks if needed. Returns a Promise resolving to an `XRiObject`.
- `XRi.getClassById(id, isGlobal = true)`: Returns an `XRiObject` instance to manipulate an existing entity.
- `XRi.clearAll(isGlobal = true)`: Resets the entire scene.
- `XRi.getAllObjects()`: Returns an array of all objects currently in the scene.
- `XRi.generateId()`: Returns a random string ID (e.g., "id_abc1234").

## 4. Instance API (XRiObject)
Manipulate specific spawned objects. Almost all methods accept a `duration` (in seconds) for smooth transitions.
- `.move(direction, duration = 1.0)`: Moves the object relative to its position.
- `.rotate(rotation, duration = 1.0)`: Rotates the object (accepts a number for Y-axis or `{x, y, z}`).
- `.setPosition(position, duration = 0)`: Moves the object to absolute world coordinates.
- `.resetRotation(duration = 1.0)`: Resets to {0,0,0} rotation.
- `.setScale(targetScale, duration = 1.0)`: Scales the object smoothly.
- `.zoom(targetScale, duration = 1.0)`: Relative scaling/zooming.
- `.lookAt(enable = true)`: Forces the object to face the user's camera.
- `.setGravity(useGravity = true)`: Enables/disables physical gravity.
- `.setGrabbable(isGrabbable = true)`: Allows the user to grab the object with hand-tracking/controllers.
- `.setVisible(isVisible = true)`: Toggles visibility.
- `.parent(parentId)`: Links the current object as a child of `parentId`.
- `.startAnimation(animationName = "")`: Plays an embedded glTF animation.
- `.stopAnimation()`: Stops the current animation.
- `.getPosition()`: Returns the absolute `{x, y, z}` coordinates.
- `.destroy()`: Removes the object from the scene.

## 5. Interaction Callbacks (Global Scope)
Define these functions on the `window` object to handle physical interactions triggered by the Unity Bridge:
- `window.handleSelection(id)`: Triggered via "GRAB_START" when a user grabs an object.
- `window.handleRelease(id)`: Triggered via "GRAB_END" when a user releases an object.
- `window.handleAllObjects(objectsArray)`: Callback for the GET_ALL_OBJ request.

## 6. Official Ecosystem Links
- App Hub & Sandbox: https://app.xri.onl
- Dev Hub & Tools: https://dev.xri.onl
- Tools: QR Builder (/qr.html), P2P Chat (/P2P.html), Remote Execution (/remote_execution.html), Action Builder (/action-builder.html), 3D Texture Editor (/editor.html).

## 7. Code Example: Spawn & Physics
```javascript
// Example: Spawning an object with gravity and grabbing enabled
await XRi.initWebXR(true);
const myObj = await XRi.spawn("cube1", "[https://example.com/cube.glb](https://example.com/cube.glb)", 1.0, {x:0, y:2, z:-1});

await myObj.setGravity(true);
await myObj.setGrabbable(true);

window.handleSelection = (id) => {
    console.log(`${id} has been grabbed!`);
};

//HTML FULL
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script src="https://xri.onl/XRi.js"></script>
    
    <style>
        /* ... existing styles ... */
        * { box-sizing: border-box; margin: 0; padding: 0; }
        body { font-family: 'Inter', sans-serif; background-color: #fcfcfc; color: #1a1a1a; line-height: 1.6; }
        nav { background: #ffffff; padding: 1rem 5%; display: flex; justify-content: space-between; align-items: center; border-bottom: 1px solid #eee; position: sticky; top: 0; z-index: 100; }
        .logo { font-weight: 800; font-size: 1.4rem; color: #d4a373; letter-spacing: 1px; }
        .cart-status { background: #f1f1f1; padding: 8px 15px; border-radius: 50px; font-size: 0.9rem; font-weight: 600; }
        #count { color: #d4a373; }
        .hero { padding: 50px 20px; text-align: center; background: #f8f5f2; }
        .container { max-width: 1100px; margin: 0 auto; padding: 40px 20px; }
        .product-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 25px; }
        .card { background: #ffffff; border: 1px solid #eaeaea; border-radius: 20px; padding: 20px; transition: all 0.3s ease; text-align: left; box-shadow: 0 4px 15px rgba(0,0,0,0.02); }
        .img-box { height: 220px; background: #fdfdfd; border-radius: 15px; display: flex; align-items: center; justify-content: center; margin-bottom: 15px; overflow: hidden; }
        .img-box img { width: 90%; height: 90%; object-fit: contain; transition: transform 0.5s ease; }
        .card h3 { font-size: 1.3rem; margin-bottom: 5px; color: #1a1a1a; text-transform: uppercase; }
        .description { font-size: 0.9rem; color: #777; margin-bottom: 15px; }
        .price { font-size: 1.5rem; margin: 10px 0; font-weight: 700; color: #d4a373; }
        .btn-group { display: flex; flex-direction: column; gap: 10px; }
        .btn-cart { background: #1a1a1a; color: #fff; border: none; padding: 12px; border-radius: 10px; font-weight: 600; font-size: 0.9rem; cursor: pointer; transition: background 0.2s; }
        .btn-xr { background: #fff; color: #d4a373; border: 1.5px solid #d4a373; padding: 10px; border-radius: 10px; font-weight: 600; font-size: 0.85rem; cursor: pointer; transition: 0.3s; }

        /* NEW CUSTOM GRAPHIC MODAL */
        #ingredient-modal {
            position: fixed;
            bottom: -100%;
            left: 0;
            width: 100%;
            background: white;
            z-index: 2000;
            padding: 30px;
            border-radius: 30px 30px 0 0;
            box-shadow: 0 -10px 30px rgba(0,0,0,0.2);
            transition: bottom 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
            text-align: center;
        }
        #ingredient-modal.active { bottom: 0; }
        #ingredient-modal h2 { color: #d4a373; margin-bottom: 10px; text-transform: uppercase; }
        #ingredient-modal p { color: #555; margin-bottom: 20px; font-style: italic; }
        .modal-btns { display: flex; gap: 15px; justify-content: center; }
        .btn-order { background: #d4a373; color: white; border: none; padding: 15px 30px; border-radius: 12px; font-weight: 700; cursor: pointer; flex: 1; }
        .btn-close { background: #eee; border: none; padding: 15px; border-radius: 12px; cursor: pointer; }
        
        /* DARK OVERLAY */
        #modal-overlay {
            position: fixed; top: 0; left: 0; width: 100%; height: 100%;
            background: rgba(0,0,0,0.4); z-index: 1999; display: none;
        }
    </style>
</head>
<body>

    <nav>
        <div class="logo">BISTRO XR</div>
        <div class="cart-status">ORDER: [<span id="count">0</span>]</div>
    </nav>

    <div class="hero">
        <h1>Gourmet Experience</h1>
        <p>Tap a dish in AR to view ingredients and order.</p>
    </div>

    <div class="container">
        <div class="product-grid">
            <div class="card">
                <div class="img-box"><img src="https://simonevetere.github.io/XRi-menu-example/assets/img/burger.png"></div>
                <h3>Starter One</h3>
                <p class="description">Premium Angus beef and melted cheddar.</p>
                <div class="price">€ 18.00</div>
                <div class="btn-group">
                    <button class="btn-cart" onclick="updateCart()">ADD TO ORDER</button>
                    <button class="btn-xr" onclick="launchXR('https://raw.githubusercontent.com/simonevetere/XRi-menu-example/main/assets/3d/burger.glb')">VIEW IN AR / 3D</button>
                </div>
            </div>
            <div class="card">
                <div class="img-box"><img src="https://simonevetere.github.io/XRi-menu-example/assets/img/pasta.png"></div>
                <h3>Main Dish</h3>
                <p class="description">Homemade pasta with fresh cherry tomatoes.</p>
                <div class="price">€ 24.50</div>
                <div class="btn-group">
                    <button class="btn-cart" onclick="updateCart()">ADD TO ORDER</button>
                    <button class="btn-xr" onclick="launchXR('https://raw.githubusercontent.com/simonevetere/XRi-menu-example/main/assets/3d/pasta.glb')">VIEW IN AR / 3D</button>
                </div>
            </div>
            <div class="card">
                <div class="img-box"><img src="https://simonevetere.github.io/XRi-menu-example/assets/img/dessert.png"></div>
                <h3>Chef's Dessert</h3>
                <p class="description">Dark chocolate mousse with pistachio.</p>
                <div class="price">€ 12.00</div>
                <div class="btn-group">
                    <button class="btn-cart" onclick="updateCart()">ADD TO ORDER</button>
                    <button class="btn-xr" onclick="launchXR('https://raw.githubusercontent.com/simonevetere/XRi-menu-example/main/assets/3d/dessert.glb')">VIEW IN AR / 3D</button>
                </div>
            </div>
        </div>
    </div>

    <div id="modal-overlay" onclick="closeModal()"></div>
    <div id="ingredient-modal">
        <h2 id="modal-title">Ingredients</h2>
        <p id="modal-text"></p>
        <div class="modal-btns">
            <button class="btn-order" id="modal-order-btn">ORDER NOW</button>
            <button class="btn-close" onclick="closeModal()">✕</button>
        </div>
    </div>

    <script>
    const spawnedItemsData = new Map();
    let lastSelectedId = null;
    let plateisspwn = false;
    const ingredientsMenu = {
        'burger': "Brioche bun, 200g Angus beef, Cheddar, Crispy bacon, Secret sauce.",
        'pasta': "Handmade spaghetti, Piennolo tomatoes, Fresh basil, Creamy Burrata.",
        'dessert': "70% Dark chocolate mousse, Toasted pistachios, Raspberry core."
    };

    async function launchXR(modelPath) {

        if(XRi.isReady && !plateisspwn){
            let plate_model = "https://raw.githubusercontent.com/simonevetere/XRi-menu-example/main/assets/3d/plate.glb"
            const plate = XRi.spawn("plate", plate_model, 0.5, { x: 0, y: 0.8, z: 0.5 }, { x: 0, y: 180, z: 0 }, true);
            plateisspwn = true;
        }

        let dishType = 'default';
        let dishSize = 0.1;
        
        if (modelPath.includes('burger')) { dishType = 'burger'; dishSize = 0.15; } 
        else if (modelPath.includes('pasta')) { dishType = 'pasta'; dishSize = 0.25; } 
        else if (modelPath.includes('dessert')) { dishType = 'dessert'; dishSize = 0.12; }

        if (typeof XRi !== 'undefined') {
            const uniqueId = "dish_" + Date.now() + "_" + Math.floor(Math.random() * 1000);
            spawnedItemsData.set(uniqueId, dishType);

            const object = await XRi.spawn(uniqueId, modelPath, dishSize, { x: 0, y: 0.8, z: 0.5 });
            
            XRi.parent(uniqueId,"plate");
            
            object.move({x: 0, y: 0.05, z: 0}, 1.0);
            
            object.setGravity(true);
        }
    };

    // INTERCEPT 3D OBJECT CLICK
    window.handleSelection = function(id) {
        const dishType = spawnedItemsData.get(id);
        if (dishType) {
            lastSelectedId = id;
            showModal(dishType);
        }
    };

    function showModal(type) {
        document.getElementById('modal-title').innerText = type.toUpperCase();
        document.getElementById('modal-text').innerText = ingredientsMenu[type];
        document.getElementById('modal-overlay').style.display = 'block';
        document.getElementById('ingredient-modal').classList.add('active');
        
        // Setup order button within modal
        document.getElementById('modal-order-btn').onclick = function() {
            updateCart();
            // 3D Visual feedback: Object "jumps"
            XRi.getClassById(lastSelectedId).move({x:0, y:0.1, z:0}, 0.2).then(() => {
                XRi.getClassById(lastSelectedId).move({x:0, y:-0.1, z:0}, 0.2);
            });
            closeModal();
        };
    }

    function closeModal() {
        document.getElementById('modal-overlay').style.display = 'none';
        document.getElementById('ingredient-modal').classList.remove('active');
    }

    function updateCart() {
        let countEl = document.getElementById('count');
        countEl.innerText = parseInt(countEl.innerText) + 1;
    };

    if (typeof XRi !== 'undefined') {
        XRi.initMultiplayer();
        XRi.initWebXR();
        XRi.clearAll();
    }
    </script>
</body>
</html>

//LIbrerie di test
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>XRi Burger Test</title>

    <script>
        // Global error handling for remote debugging
        window.onerror = function(message, source, lineno) {
            const errBox = document.createElement('div');
            errBox.style = "background:red; color:white; padding:20px; font-size:18px; position:fixed; top:0; left:0; right:0; z-index:9999;";
            errBox.innerHTML = `CRASH: ${message} (Line ${lineno})`;
            document.body.appendChild(errBox);
            return false;
        };
        window.onunhandledrejection = function(event) {
            const errBox = document.createElement('div');
            errBox.style = "background:orange; color:black; padding:20px; font-size:18px; position:fixed; top:60px; left:0; right:0; z-index:9999;";
            errBox.innerHTML = `ASYNC ERR: ${event.reason}`;
            document.body.appendChild(errBox);
        };
    </script>

    <script src="https://xri.onl/XRi.js"></script>
    
    <style>
        body { 
            font-family: 'Segoe UI', Arial, sans-serif; 
            background-color: #0f0f0f; 
            color: #ffffff; 
            padding: 20px; 
            margin: 0;
        }
        h1 { margin-top: 0; color: #bb86fc; font-size: 22px; border-bottom: 1px solid #333; padding-bottom: 10px; }
        .section-title { font-size: 12px; color: #666; margin: 15px 0 5px 0; text-transform: uppercase; letter-spacing: 1px; }
        .controls { 
            display: grid; 
            grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); 
            gap: 10px; 
            margin-bottom: 20px; 
        }
        button { 
            padding: 12px; 
            background: #2c2c2c; 
            color: #bb86fc; 
            border: 1px solid #444; 
            border-radius: 6px; 
            font-size: 14px; 
            font-weight: bold; 
            cursor: pointer; 
            transition: all 0.2s;
        }
        button:hover { background: #383838; border-color: #bb86fc; }
        button:active { transform: scale(0.95); background: #bb86fc !important; color: #000; }
        
        .btn-spawn { background: #bb86fc; color: #000; }
        .btn-info { color: #00d1ff; border-color: #00d1ff; }
        .btn-danger { color: #ff5555; border-color: #ff5555; }
        
        #debug-console { 
            background: #000; 
            color: #0f0; 
            padding: 15px; 
            border-radius: 8px; 
            height: 250px; 
            overflow-y: auto; 
            font-family: 'Consolas', monospace; 
            font-size: 13px;
            border: 1px solid #333;
            box-shadow: inset 0 0 10px rgba(0,255,0,0.05);
        }
    </style>
</head>
<body>

    <h1>XRi Burger Lab v2.1</h1>
    
    <div class="section-title">Core Actions</div>
    <div class="controls">
        <button class="btn-spawn" onclick="testSpawn()">SPAWN BURGER</button>
        <button onclick="testMove()">MOVE UP</button>
        <button onclick="testRotate()">ROTATE 90°</button>
        <button onclick="testScale()">SCALE UP</button>
        <button onclick="testGravity()">TOGGLE GRAVITY</button>
        <button onclick="testLookAt()">LOOK AT CAM</button>
    </div>

    <div class="section-title">Data & Debug</div>
    <div class="controls">
        <button class="btn-info" onclick="testPos()">GET POSITION</button>
        <button class="btn-info" onclick="testGetAll()">LIST ALL OBJ</button>
        <button onclick="testAnim()">START ANIM</button>
        <button class="btn-danger" onclick="testClear()">DESTROY ALL</button>
    </div>

    <div id="debug-console"></div>

    <script>
        const BURGER_URL = "https://raw.githubusercontent.com/simonevetere/XRi-menu-example/main/assets/3d/burger.glb";
        let myBurger = null;
        let isGravityOn = false;
        let isLookAtOn = false;

        function log(msg, color = "#0f0") {
            const consoleDiv = document.getElementById("debug-console");
            const time = new Date().toLocaleTimeString();
            consoleDiv.innerHTML += `<div style="color: ${color}">[${time}] ${msg}</div>`;
            consoleDiv.scrollTop = consoleDiv.scrollHeight;
        }
        window.log = log; 

        if (typeof window.XRi === 'undefined') {
            log("ERROR: XRi.js not found!", "#ff0000");
        } else {
            log("XRi Engine Ready.", "#bb86fc");
        }

        async function testSpawn() {
            log("Spawning burger...", "#ffff00");
            try {
                // Spawn returns an XRiObject instance
                myBurger = await XRi.spawn("burger_01", BURGER_URL, 0.2, {x: 0, y: 1, z: 0.5});
                log("Burger successfully spawned.");

                setTimeout(async () => {
                    await myBurger.setGrabbable(true);
                    log("Grab enabled.");
                }, 1000);

            } catch (error) {
                log("Spawn Error: " + error.message, "#ff5555");
            }
        }

        async function testMove() {
            if (!myBurger) return log("Spawn a burger first!", "#ff5555");
            await myBurger.move({x: 0, y: 0.2, z: 0}, 0.5);
            log("Relative movement completed.");
        }

        async function testRotate() {
            if (!myBurger) return log("No burger!", "#ff5555");
            await myBurger.rotate({x: 0, y: 90, z: 0}, 1.0);
            log("90° Y rotation completed.");
        }

        async function testScale() {
            if (!myBurger) return log("No burger!", "#ff5555");
            await myBurger.setScale(0.4, 1.0);
            log("Scale set to 0.4");
        }

        async function testGravity() {
            if (!myBurger) return log("No burger!", "#ff5555");
            isGravityOn = !isGravityOn;
            await myBurger.setGravity(isGravityOn);
            log("Gravity: " + (isGravityOn ? "ON" : "OFF"), "#bb86fc");
        }

        async function testLookAt() {
            if (!myBurger) return log("No burger!", "#ff5555");
            isLookAtOn = !isLookAtOn;
            await myBurger.lookAt(isLookAtOn);
            log("LookAt (Billboard): " + (isLookAtOn ? "ON" : "OFF"), "#bb86fc");
        }

        async function testAnim() {
            if (!myBurger) return log("No burger!", "#ff5555");
            await myBurger.startAnimation(""); // Leave empty for the first available animation
            log("Attempting to start animation...");
        }

        async function testPos() {
            if (!myBurger) return log("No burger!", "#ff5555");
            log("Requesting position...", "#00d1ff");
            let pos = await myBurger.getPosition();
            if (pos) log(`POS -> X:${pos.x.toFixed(2)}, Y:${pos.y.toFixed(2)}, Z:${pos.z.toFixed(2)}`, "#00d1ff");
        }

        async function testGetAll() {
            log("Scanning scene objects...", "#00d1ff");
            let list = await XRi.getAllObjects();
            if(list && list.length > 0) {
                log("Found: " + list.length + " objects.");
                console.table(list);
            } else {
                log("Empty scene.", "#ffff00");
            }
        }

        async function testClear() {
            await XRi.clearAll();
            myBurger = null;
            log("Scene cleared.", "#ff5555");
        }

        // Grab events handled by Unity
        window.handleSelection = function(id) { log(`GRABBED: ${id}`, "#ffff00"); };
        window.handleRelease = function(id) { 
            log(`RELEASED: ${id}`, "#bb86fc"); 
            if (myBurger && id === myBurger.id) testPos(); 
        };
    </script>
</body>
</html>
```