Core Usage

Use XRSessionManager with any WebGL2 renderer without Three.js

If you are using a custom renderer, Babylon.js, or any other WebGL2 library, import from @multisetai/vps/core. This entry point has zero peer dependencies.

Setup

import { MultisetClient, XRSessionManager } from '@multisetai/vps/core';

const client = new MultisetClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  mapType: 'map',
  code: 'MAP_XXXXXXXXXX',
});

await client.authorize();

Create the Session Manager

Pass a WebGL2RenderingContext from your canvas and a session options object.

const canvas = document.getElementById('canvas') as HTMLCanvasElement;
const gl = canvas.getContext('webgl2')!;

const session = new XRSessionManager(gl, {
  client,
  autoLocalize: true,

  onSessionStart: () => {
    console.log('AR session started');
  },
  onSessionEnd: () => {
    console.log('AR session ended');
  },
  onLocalizationResult: (result) => {
    const { position, rotation, confidence } = result.localizeData;
    console.log('Pose found:', position, rotation, 'confidence:', confidence);
  },
  onLocalizationFailure: (reason) => {
    console.warn('Localization failed:', reason);
  },
  onError: (error) => {
    console.error('Session error:', error);
  },
});

Handle XR Frames

Register a frame handler to drive your own render loop. The SDK owns the WebXR session; your handler receives everything you need per frame.

session.setXRFrameHandler((event) => {
  const { frame, view, viewport, baseLayer, pose, deltaSeconds } = event;

  // Bind the XR framebuffer
  gl.bindFramebuffer(gl.FRAMEBUFFER, baseLayer.framebuffer);
  gl.viewport(viewport.x, viewport.y, viewport.width, viewport.height);
  gl.clearColor(0, 0, 0, 0); // alpha = 0 for camera passthrough
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

  // Camera matrices
  const projectionMatrix = view.projectionMatrix;           // Float32Array (4x4)
  const viewMatrix = pose.transform.inverse.matrix;         // Float32Array (4x4)

  // Your draw calls here
  myRenderer.render(projectionMatrix, viewMatrix);
});

Mount the AR Button

createButton() returns a pre-styled <button> that handles start and stop. It must be activated by a user gesture (click/tap) to satisfy browser security requirements.

const button = session.createButton();
document.body.appendChild(button);

Or trigger the session manually from your own button:

myButton.addEventListener('click', async () => {
  if (session.isActive()) {
    session.stopSession();
  } else {
    await session.startSession(); // must be inside a click handler
  }
});

Handle Localization Results

If you want to react to localization from outside the frame handler, use the session callbacks. To also access the result handler used by adapters, register an adapter result handler:

session.setAdapterResultHandler((result, trackerSpace) => {
  // result: ILocalizeAndMapDetails
  // trackerSpace: XRReferenceSpace — the map-relative reference space
  const { position, rotation } = result.localizeData;
  // Apply pose to your scene graph here
});

Manual Localization

With autoLocalize: false, trigger localization on demand:

document.getElementById('localize-btn').addEventListener('click', async () => {
  const result = await session.localizeFrame();
  if (result) {
    console.log('Position:', result.localizeData.position);
  }
});

Cleanup

session.dispose(); // ends session, removes all listeners, releases GL resources

Checking Support

const supported = await XRSessionManager.isSupported();
if (!supported) {
  document.getElementById('ar-btn').style.display = 'none';
}