> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/webxr-sdk/core-usage.md).

# Core Usage

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

```typescript
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.

```typescript
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.

```typescript
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.

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

Or trigger the session manually from your own button:

```typescript
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:

```typescript
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:

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

### Cleanup

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

### Checking Support

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.multiset.ai/webxr-sdk/core-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.