MultiSet VPS WebXR

TypeScript SDK for integrating MultiSet's Visual Positioning System (VPS) into WebXR applications. Provides 6-DOF localization by matching camera frames against cloud-hosted maps, and object tracking by matching camera frames against registered 3D objects.

Contents

• Architecture
• Installation
• Requirements
• CORS Configuration
• Quick Start
  • VPS — Three.js
  • VPS — Vanilla / WebGL2
  • Object Tracking — Three.js
  • Needle Engine
    • Unity Inspector Workflow
    • MapSpace — anchoring a whole subtree
    • MapAnchor — zero-code object placement
• Navigation — AR wayfinding (full guide)
• Canvas Visibility During AR
• API Reference
  • MultisetClient
  • XRSessionManager
  • ThreeAdapter
  • NeedleAdapter
  • IVpsAdapter — the contract both adapters share
  • MapSpace
  • MapAnchor
  • Navigation
  • NavMeshPathfinder
  • buildPathRibbon
  • MultisetVPS
• Placing Content at Map Coordinates
• Styling the AR Button
• Custom Start / Stop Button
• Type Definitions
• Troubleshooting
  • AR button doesn't appear
  • MapAnchor not appearing after localization
  • MapSpace content missing or misplaced
  • Component start() never called

Architecture

The SDK is split into independent entry points so you only install what you need:

| Entry point | Contents | Peer deps | |---|---|---| | @multisetai/vps/core | MultisetClient + XRSessionManager | None | | @multisetai/vps/three | ThreeAdapter | three >=0.169.0 | | @multisetai/vps/needle | NeedleAdapter | @needle-tools/engine (brings its own three) |

XRSessionManager owns the full vanilla WebXR session lifecycle — frame loop, camera capture, localization, tracking-loss recovery — with zero Three.js dependency. ThreeAdapter and NeedleAdapter wire it to a renderer and scene.

Installation

# Core only (no Three.js)
npm install @multisetai/vps

# With Three.js adapter
npm install @multisetai/vps three

# With Needle Engine — no separate `three` install needed.
# Needle Engine ships its own three.js fork as a dependency.
npm install @multisetai/vps

Requirements

• HTTPS — WebXR requires a secure context (https:// or http://localhost).
• Android + ARCore — Chrome or Edge on an ARCore-capable Android device (Android 8+, Chrome 81+).
• Three.js ≥ 0.169.0 — only required when using @multisetai/vps/three. Compatible through the latest release (r184+).
• Needle Engine ≥ 5.0.0 — only required when using @multisetai/vps/needle. Needle ships its own three fork — do not install three separately.

iOS is not supported. This SDK requires the camera-access WebXR feature. Safari on iOS does not implement it.

CORS Configuration

The SDK makes direct browser-to-API requests, so your domain must be whitelisted in the MultiSet dashboard.

1. Open the MultiSet Dashboard
2. Go to Credentials → Settings → Domains
3. Click Add + and enter your origin (e.g. https://localhost:5173 for dev, https://your-app.com for prod)

Without this, the browser will block every API request with a CORS error.

Quick Start

VPS Localization — Three.js

import * as THREE from 'three';
import { MultisetClient, XRSessionManager } from '@multisetai/vps/core';
import { ThreeAdapter } from '@multisetai/vps/three';

// Check support before showing any AR UI
const supported = await ThreeAdapter.isSupported();
if (!supported) {
  console.warn('WebXR immersive-ar is not supported on this device.');
}

const client = new MultisetClient({
  clientId: 'CLIENT_ID',
  clientSecret: 'CLIENT_SECRET',
  code: 'MAP_OR_MAPSET_CODE',
  mapType: 'map',
});

await client.authorize();

const renderer = new THREE.WebGLRenderer({ antialias: true });
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.01, 1000);

const session = new XRSessionManager(renderer.getContext() as WebGL2RenderingContext, {
  client,
  overlayRoot: document.body,
  autoLocalize: true,
  confidenceCheck: true,
  confidenceThreshold: 0.5,
  onSessionStart: () => {
    // Hide the canvas during AR — the XR compositor owns the display.
    renderer.domElement.style.display = 'none';
  },
  onSessionEnd: () => {
    renderer.domElement.style.display = 'block';
  },
  onLocalizationResult: (result) => console.log('Localized:', result.localizeData.position),
  onLocalizationFailure: (reason) => console.warn('Failed:', reason),
  onError: (err) => console.error(err),
});

const adapter = new ThreeAdapter({ session, renderer, scene, camera, showMesh: true });
adapter.initialize(); // mounts the built-in START AR / STOP AR button

// Add your 3D content
scene.add(new THREE.Mesh(
  new THREE.BoxGeometry(0.1, 0.1, 0.1),
  new THREE.MeshBasicMaterial({ color: 0xff0077 })
));

VPS Localization — Without Three.js (WebGL2 / Vanilla)

In this mode the SDK manages the session lifecycle, camera capture, and localization. You are responsible for all rendering: each XR frame, draw your scene into event.baseLayer.framebuffer using the provided gl context. This approach works with any WebGL2-based renderer — Babylon.js, raw WebGL, or your own engine.

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

const supported = await XRSessionManager.isSupported();
if (!supported) {
  console.warn('WebXR immersive-ar is not supported on this device.');
}

const client = new MultisetClient({ clientId: '...', clientSecret: '...', code: '...', mapType: 'map' });
await client.authorize();

// A WebGL2 context is required — WebXR renders into a GL framebuffer, not a 2D canvas.
const gl = document.querySelector('canvas')!.getContext('webgl2')!;

const session = new XRSessionManager(gl, {
  client,
  overlayRoot: document.body,
  autoLocalize: true,
  onLocalizationResult: (result) => console.log('Localized:', result.localizeData.position),
  onError: (err) => console.error(err),
});

// Wire your render loop — called every XR frame with the current pose and framebuffer.
session.setXRFrameHandler((event) => {
  // Bind event.baseLayer.framebuffer and render your scene using event.view for camera matrices.
});

document.body.appendChild(session.createButton());

Object Tracking — Three.js

Object tracking detects and poses registered 3D objects by matching a captured camera frame against the MultiSet cloud.

import * as THREE from 'three';
import { MultisetClient, XRSessionManager } from '@multisetai/vps/core';
import { ThreeAdapter } from '@multisetai/vps/three';

const client = new MultisetClient({
  clientId: 'CLIENT_ID',
  clientSecret: 'CLIENT_SECRET',
  mapType: 'object-tracking',
  code: ['YOUR_OBJECT_CODE'],
});

await client.authorize();

const renderer = new THREE.WebGLRenderer({ antialias: true });
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.01, 1000);

const session = new XRSessionManager(renderer.getContext() as WebGL2RenderingContext, {
  client,
  overlayRoot: document.body,
  autoTracking: true,          // detect once on session start
  confidenceCheck: true,
  confidenceThreshold: 0.5,
  onSessionStart: () => { renderer.domElement.style.display = 'none'; },
  onSessionEnd:   () => { renderer.domElement.style.display = 'block'; },
  onObjectTrackingSuccess: (result) => {
    console.log('Detected', result.objectCodes, 'at', result.position);
  },
  onObjectTrackingFailure: (reason) => console.warn('Tracking failed:', reason),
  onError: (err) => console.error(err),
});

const adapter = new ThreeAdapter({
  session,
  renderer,
  scene,
  camera,
  showObjectMeshes: true,       // load and display the 3D outline mesh
  onObjectMeshLoaded: (code) => console.log('Mesh loaded for', code),
});
adapter.initialize();

// Trigger tracking manually from a button
trackButton.addEventListener('click', () => {
  void adapter.trackObjects();
});

Needle Engine

NeedleAdapter is a Needle Engine Behaviour component. Add it to a GameObject via addNewComponent() from your own component's start(). The built-in START AR / STOP AR button mounts automatically — no initialize() call needed.

Important: Do not add a Needle WebXR component to the same scene. NeedleAdapter must own the WebXR session directly because it bypasses Three.js's built-in XR manager (renderer.xr). This is required to work around a Chrome/WebXR regression where enabling camera-access corrupts Three.js's internal texture state. Adding a Needle WebXR component would start a second session and conflict with this setup. Delete the WebXR component from the scene hierarchy before adding MultisetVPS.

Unity Inspector workflow

MultisetVPS, MapSpace, and MapAnchor are ready-made components. Copy a few template files into your project, fill in credentials in the Inspector — no code required.

Why template files? Needle Engine's Unity codegen scans only your local src/scripts/ folder to generate C# stubs — it skips node_modules. Copying the templates into your project gives Unity the component definitions it needs, while all SDK utilities (NeedleAdapter, MultisetClient, etc.) are still imported from the package.

A consequence worth remembering: these components are not package exports. In code, import them relatively (./MapSpace.js), never from @multisetai/vps/needle. They are also yours to edit — Needle will not overwrite them.

1. Install in your Needle web project:

   npm install @multisetai/vps

2. Copy the TypeScript templates into your Needle project's scripts folder (the folder Needle scans for components — web/src/scripts/ by default, but use whatever path your project uses):

   cp node_modules/@multisetai/vps/templates/MultisetVPS.ts <your-web-folder>/src/scripts/
   cp node_modules/@multisetai/vps/templates/MapSpace.ts    <your-web-folder>/src/scripts/
   cp node_modules/@multisetai/vps/templates/MapAnchor.ts   <your-web-folder>/src/scripts/
   cp node_modules/@multisetai/vps/templates/MapType.ts     <your-web-folder>/src/scripts/

   MapType.ts must be present alongside MultisetVPS.ts — Needle's component compiler resolves the enum from this file to generate the Map Type dropdown. Without it the component will not appear in the Inspector.

   Needle Engine automatically picks up everything in your scripts folder and generates the matching C# stubs in Unity.

3. Copy the C# enum into your Unity project's Assets/ folder (one-time setup — this file is never overwritten by Needle). Run this from inside your web folder:

   cp node_modules/@multisetai/vps/templates/MapType.cs ../Assets/

   This gives you a Map Type dropdown in the Inspector (SingleMap / MapSet / ObjectTracking). Without it, Needle generates the field but Unity can't compile the enum reference.

4. In Unity, add a MultisetVPS component to any GameObject and fill in clientId, clientSecret, and mapCode in the Inspector.

5. Place your content. Two options, and MapSpace is the recommended default:

   • MapSpace — add it to a single empty GameObject at the scene root, then nest everything you want anchored underneath. Each child's normal Unity Transform position is its map coordinate, so you can paste values straight from the developer portal's Map Viewer and lay the scene out visually in the editor. See MapSpace — anchoring a whole subtree.
   • MapAnchor — add it to an individual GameObject and type its coordinate into the Offset field. Best for one-off objects and runtime-spawned content. See MapAnchor — zero-code object placement.

   MultisetVPS discovers all MapSpace and MapAnchor instances automatically at startup — no manual wiring needed.

6. Export to web — the START AR / STOP AR and CAPTURE FRAME buttons appear automatically.

Where map coordinates come from

Open your map in the Map Viewer (or MapSet Viewer) in the developer portal, pick the point you want to anchor to, and copy the coordinates. These are Unity left-handed values, which is exactly what both components expect by default — paste them in unchanged.

For runtime-spawned objects (loaded from an API, instantiated mid-session), call adapter.registerAnchor(anchor) — see MapAnchor — zero-code object placement below.

Code-based setup (without Unity Inspector)

import { Behaviour, serializable, addNewComponent } from '@needle-tools/engine';
import { MultisetClient } from '@multisetai/vps/core';
import { NeedleAdapter } from '@multisetai/vps/needle';
import * as THREE from 'three';

export class MyARComponent extends Behaviour {
  async start() {
    const client = new MultisetClient({
      clientId: 'CLIENT_ID',
      clientSecret: 'CLIENT_SECRET',
      code: 'MAP_CODE',
      mapType: 'map',
    });

    const adapter = new NeedleAdapter({
      client,
      showMesh: true,
      sessionOptions: {
        autoLocalize: true,
        onSessionStart: () => console.log('AR started'),
        onSessionEnd:   () => console.log('AR ended'),
        onLocalizationFailure: (reason) => console.warn('Failed:', reason),
        onError: (err) => console.error(err),
      },
      onLocalizationSuccess: (result, worldFromMap) => {
        // Place content anchored to the scanned map
        const marker = new THREE.Mesh(
          new THREE.SphereGeometry(0.05),
          new THREE.MeshBasicMaterial({ color: 0x00ff88 })
        );
        marker.position.applyMatrix4(worldFromMap);
        this.context.scene.add(marker);
      },
    });

    // addNewComponent triggers awake() — button mounts automatically
    addNewComponent(this.gameObject, adapter);
    await client.authorize();
  }
}

MapSpace — anchoring a whole subtree (Unity)

MapSpace marks one GameObject as the map origin. On every successful localization it is moved so that its origin coincides with the scanned map's origin, and every descendant follows automatically.

This is the recommended way to place content in Unity, because a child's local Transform position is its map coordinate:

SampleScene
├── MultisetVPS          ← credentials
└── Map Space            ← MapSpace, transform at identity
    ├── Office Entry     ← local position = portal coordinate
    ├── Coffee Shack     ← local position = portal coordinate
    └── Lift             ← local position = portal coordinate

Setup

1. Create an empty GameObject at the scene root. Leave its transform at identity — Position (0,0,0), Rotation (0,0,0), Scale (1,1,1).
2. Add the MapSpace component.
3. Nest the objects you want anchored underneath it.
4. Set each child's normal Unity Transform position to its coordinate from the portal's Map Viewer.

| Inspector field | Type | Default | Description | |---|---|---|---| | Hide Until Localized | bool | true | Hide anchored content until the first successful localization. Re-hides when the AR session ends. |

Why this over MapAnchor per object

• The Unity editor layout is the AR layout — arrange POIs visually instead of typing coordinates you cannot verify until you deploy.
• Import the scanned map mesh as a child and place content against real geometry.
• Relative layout is preserved exactly. Everything moves as one rigid body, so POIs can never drift apart.
• One transform write per localization regardless of POI count.
• No per-object handedness flag to get wrong.

Note — Unity authored transforms are converted to Three.js by Needle's exporter, so no handedness setting is involved. This is why MapSpace has no isRightHanded field while MapAnchor does.

Important — hideUntilLocalized makes the root invisible, and Needle treats an invisible GameObject as inactive. That applies to every descendant, so none of their start() methods run until the first localization. Keep always-running logic (session listeners, UI, network polling) on a separate GameObject outside this hierarchy.

Do not nest a MapAnchor inside a MapSpace. MapAnchor writes a world position into a local transform, so inside an already-positioned root the offset is applied twice. MultisetVPS logs a warning if it detects this. Use one or the other for a given object.

Runtime-added children do not go through the Unity exporter, so route their coordinates through MapSpace.toLocal():

import { MapSpace } from './MapSpace.js';
import * as THREE from 'three';

const poi = instantiate(myPoiPrefab);
mapSpace.gameObject.add(poi);
poi.position.copy(MapSpace.toLocal(new THREE.Vector3(1.5, 0, -2.0)));  // Unity LHS in

Alternatively use MapAnchor with registerAnchor() and leave the object unparented — it accepts Unity values directly.

MapAnchor — zero-code object placement (Unity)

MapAnchor is a Needle Engine component that anchors any GameObject to the VPS map origin after a successful localization. Add it to the object you want to place in AR from the Unity Inspector — no code required.

Use it for individual objects, runtime-spawned content, and anything that must not inherit the map's rotation. For laying out several POIs in a scene, prefer MapSpace.

| Inspector field | Type | Description | |---|---|---| | Offset | Vector3 | Position offset from the map origin in metres. Enter Unity Inspector values directly — X is negated automatically unless Is Right Handed is enabled. | | Match Orientation | bool | Align the object's rotation to the map's orientation. | | Rotation Offset | Vector3 (degrees) | Additional rotation applied on top of the map orientation. Only used when Match Orientation is enabled. Enter Unity Inspector values — Y and Z are negated automatically unless Is Right Handed is enabled. | | Hide Until Localized | bool | Hide the object until the first successful localization. Re-hides it when the AR session ends. | | Is Right Handed | bool | Off by default. When off, Offset and Rotation Offset are treated as Unity (left-handed) values and converted automatically. Enable only if you are entering Three.js (right-handed) values directly. |

MultisetVPS (or your own component calling addNewComponent) automatically discovers all MapAnchor instances in the scene at startup and wires them to the adapter. You do not call any method manually.

Important: When hideUntilLocalized is true, Needle sets visible = false on the GameObject in awake(). An invisible GameObject is inactive in Needle — every component on it, not just MapAnchor, will have its start() skipped. Keep MapAnchor on the object you want placed in AR. Put any logic components (session listeners, custom UI) on a separate, always-visible GameObject.

For objects spawned at runtime (e.g. from API data or a prefab instantiated mid-session), register them explicitly so they receive localization events and are placed immediately if localization has already succeeded:

// MapAnchor is a template file you copied into your own project — import it
// relatively. It is NOT exported from the package.
import { MapAnchor } from './MapAnchor.js';

// Spawn a new object at runtime and anchor it to the map
const obj = instantiate(myPrefab);
const anchor = addNewComponent(obj, new MapAnchor());
anchor.hideUntilLocalized = true;
anchor.offset.set(0.5, 0, -1.0);

// Connect it — places immediately if localization already succeeded
this.adapter.registerAnchor(anchor);

Using useDefaultButton: false (custom button):

const adapter = new NeedleAdapter({
  client,
  useDefaultButton: false,
  sessionOptions: { autoLocalize: true },
});

addNewComponent(this.gameObject, adapter);
await client.authorize();

myButton.addEventListener('click', () => {
  if (adapter.isActive()) {
    adapter.stopSession();
  } else {
    void adapter.startSession();
  }
});

Navigation

AR indoor wayfinding on top of localization: pick a destination, follow an arrowed path along the floor, arrive. Ships as a separate entry point, so an app that only localizes pays nothing for it.

npm install @multisetai/vps three-pathfinding

three-pathfinding is an optional peer dependency, loaded on demand — install it only if you use NavMeshPathfinder.

The package has the essentials to build a navigation app; it is not a navigation app. You get the state machine, pathfinding, and buildPathRibbon (corners → ribbon triangles). UI, shaders, materials, labels and icons are design decisions and live in the samples, where you own them.

import { Navigation, NavMeshPathfinder, buildPathRibbon } from '@multisetai/vps/navigation';

const pathfinder = await NavMeshPathfinder.fromObject3D(navMesh, { space: mapSpace.object });
const navigation = await Navigation.create({ adapter, mapSpace, pathfinder, pois });

navigation.on('pathUpdated', ({ corners }) => {
  mesh.geometry = buildPathRibbon(corners);   // your Mesh, your material
});
navigation.setDestination('kitchen');

Works with ThreeAdapter and NeedleAdapter alike — Navigation talks to IVpsAdapter and never imports either. It requires a MapSpace, which defines the coordinate frame every route is computed in; that is what makes relocalization free.

For a complete app — arrow shader, POI labels, destination panel, scene setup — start from the Needle or three.js navigation sample.

→ Full navigation guide — setup, API, tuning, and troubleshooting.

Canvas Visibility During AR

Important — the SDK renders the Three.js scene into the XR framebuffer, not the canvas element. During an active AR session the canvas element is not updated; it retains whatever was last drawn by the preview loop. If the canvas is visible during AR (e.g. as part of the WebXR DOM overlay) it will appear as a frozen image on top of the AR scene.

Always hide the canvas when the session starts and restore it when it ends:

onSessionStart: () => { renderer.domElement.style.display = 'none'; },
onSessionEnd:   () => { renderer.domElement.style.display = 'block'; },

API Reference

MultisetClient

Pure HTTP client for auth, localization, and object tracking. No WebXR or rendering concerns.

new MultisetClient(config: IMultisetClientConfig)

IMultisetClientConfig

VPS mode (mapType: 'map' or mapType: 'map-set')

| Parameter | Type | Description | |---|---|---| | clientId | string | Your MultiSet client ID | | clientSecret | string | Your MultiSet client secret | | mapType | 'map' \| 'map-set' | Whether code is a single map or a map set | | code | string | Map or map-set code | | endpoints? | Partial<IMultisetSdkEndpoints> | Override default API endpoints | | isRightHanded? | boolean | Handedness sent to the API. Default true | | convertToGeoCoordinates? | boolean | Request geographic coordinates in the response | | hintPosition? | string | Local-space position hint "x,y,z" | | hintRadius? | number \| string | Search radius in metres (1–100). Requires hintPosition or passGeoPose | | hintMapCodes? | string[] | Narrow candidates by map code. Only valid when mapType: 'map-set' | | passGeoPose? | boolean | Send a geoHint from the Geolocation API with each request | | use2DFiltering? | boolean | Skip altitude in geo filtering. Only valid when passGeoPose: true |

Object tracking mode (mapType: 'object-tracking')

| Parameter | Type | Description | |---|---|---| | clientId | string | Your MultiSet client ID | | clientSecret | string | Your MultiSet client secret | | mapType | 'object-tracking' | Enables object tracking mode. No map code required. | | code | string[] | Object codes to detect and track | | isRightHanded? | boolean | Handedness sent to the API. Default true | | endpoints? | Partial<IMultisetSdkEndpoints> | Override default API endpoints |

Methods

| Method | Returns | Description | |---|---|---| | authorize() | Promise<string> | Authenticate and cache an access token. Call before any other method. | | localizeWithFrame(frame, intrinsics) | Promise<ILocalizeAndMapDetails \| null> | Submit a captured frame for VPS localization. | | trackObject(frame, intrinsics) | Promise<IObjectTrackingResponse \| null> | Submit a captured frame for object detection. Uses code from the client config. Returns null when no object is detected. | | downloadObjectMesh(objectCode) | Promise<string \| null> | Fetch a signed download URL for the 3D mesh of an object. | | fetchMapDetails(mapCode) | Promise<IGetMapsDetailsResponse \| null> | Fetch map metadata by code (result is cached). | | downloadFile(key) | Promise<string> | Resolve a storage key to a signed download URL. Low-level — downloadObjectMesh and fetchMapDetails use it internally. | | token | string \| null | Getter. The cached access token, or null before authorize(). Useful when debugging auth failures. | | mapType | 'map' \| 'map-set' \| 'object-tracking' | Getter. The configured mode. | | objectCodes | string[] | Getter. The configured object codes. Empty unless mapType: 'object-tracking'. |

XRSessionManager

Owns the WebXR session lifecycle — frame loop, camera capture, localization, object tracking, and tracking-loss recovery. Zero Three.js dependency.

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

new XRSessionManager(gl: WebGL2RenderingContext, options: IXRSessionOptions)

IXRSessionOptions

| Parameter | Type | Description | |---|---|---| | client | MultisetClient | Required. | | overlayRoot? | HTMLElement | Root element for the WebXR DOM overlay. | | autoLocalize? | boolean | Run one localization automatically when the session starts. | | relocalization? | boolean | Re-localize whenever tracking is lost and then recovered. | | confidenceCheck? | boolean | Only accept results with confidence >= confidenceThreshold. Applies to both VPS and object tracking. | | confidenceThreshold? | number | Minimum confidence (0.2–0.8). Default 0.5. | | poseTimeoutMs? | number | Max ms to wait for a valid viewer pose before failing. Default 10000. | | localizationTrackingTimeoutMs? | number | Deprecated — use poseTimeoutMs. Will be removed in v3. | | backgroundLocalization? | boolean | Periodically send localization/tracking requests in the background while the session is active. | | bgLocalizationInterval? | number | Interval in seconds between background attempts. Clamped to 10–180 s. Default 30 for VPS modes, 10 for object tracking. | | autoTracking? | boolean | Call trackObjects() once automatically when the session starts. Requires mapType: 'object-tracking' on the client. | | restartTracking? | boolean | Re-attempt tracking whenever XR tracking is lost and then recovered. | | trackingCaptureDelayMs? | number | Milliseconds to wait before capturing a frame when trackObjects() is called. Useful for camera stabilisation. Default 0. | | referenceSpaceType? | XRReferenceSpaceType | XR reference space type. Default 'local'. Use 'local-floor' for floor-relative tracking if the device supports it. | | framebufferScaleFactor? | number | XR framebuffer scale relative to native resolution. Values < 1 reduce GPU load; values > 1 supersample. | | onSessionStart? | () => void | Called when the AR session starts. | | onSessionEnd? | () => void | Called when the AR session ends. | | onLocalizationInit? | () => void | Called at the start of a VPS localization run. | | onLocalizationResult? | (result: ILocalizeAndMapDetails) => void | Called when VPS localization succeeds (and passes the confidence check, if enabled). | | onLocalizationSuccess? | (result: ILocalizeAndMapDetails) => void | Deprecated — use onLocalizationResult. If using ThreeAdapter, use its onLocalizationSuccess which also provides worldFromMap. Will be removed in v3. | | onLocalizationFailure? | (reason?: string) => void | Called when VPS localization fails or falls below the confidence threshold. | | onFrameCaptured? | (frame: IFrameCaptureEvent) => void | Called when a camera frame is captured for localization. | | onCameraIntrinsics? | (intrinsics: ICameraIntrinsicsEvent) => void | Called with camera intrinsic parameters for the captured frame. | | onPoseResult? | (pose: IPoseResultEvent) => void | Called with the raw pose result from the VPS backend. | | onObjectTrackingInit? | () => void | Called at the start of an object tracking run. | | onObjectTrackingRequested? | (frame: IFrameCaptureEvent, intrinsics: ICameraIntrinsicsEvent) => void | Called just before the tracking request is sent, with the captured frame and intrinsics. | | onObjectTrackingSuccess? | (result: IObjectTrackingResponse) => void | Called when object tracking succeeds and passes the confidence check (if enabled). | | onObjectTrackingFailure? | (reason?: string) => void | Called when object tracking fails or falls below the confidence threshold. | | onError? | (error: unknown) => void | Called when any error occurs. | | onContextLost? | () => void | Called when the WebGL context is lost. The active session is ended automatically. | | onContextRestored? | () => void | Called when the WebGL context is restored. The user may restart the session. |

Static methods

| Method | Returns | Description | |---|---|---| | XRSessionManager.isSupported() | Promise<boolean> | Returns true if the browser supports immersive-ar WebXR sessions. Use this to conditionally show AR UI before creating any objects. |

Methods

| Method | Returns | Description | |---|---|---| | createButton() | HTMLButtonElement | Create the built-in styled AR button. Shows START AR / STOP AR and toggles the session on click. | | startSession() | Promise<void> | Start an AR session programmatically. Must be called from within a user gesture handler (click/tap). | | stopSession() | void | Stop the active AR session. No-op if no session is running. | | localizeFrame() | Promise<ILocalizeAndMapDetails \| null> | Capture and localize one frame against the configured map. Requires an active session. | | trackObjects() | Promise<IObjectTrackingResponse \| null> | Capture one frame and run object detection. Requires an active session and mapType: 'object-tracking' on the client. | | isActive() | boolean | Whether an XR session is currently running. | | isLocalizing | boolean | Whether a localization or tracking run is currently in progress. | | getClient() | MultisetClient | Access the underlying MultisetClient. | | getBaseLayer() | XRWebGLLayer \| null | The session's base layer, or null outside a session. Only needed if you render yourself — the adapters use it to size their XR framebuffer. | | getXRSession() | XRSession \| null | The live WebXR session, or null when none is running. Mainly useful for domOverlayState: dom-overlay is only an optional feature of the session request, so without it HTML mounted over the session still renders but never receives taps — and nothing else will tell you why. | | getOverlayRoot() | HTMLElement \| undefined | The element passed as overlayRoot. Mount in-session UI here so it receives taps while AR is presenting. | | dispose() | void | End the session, clear background timers, remove context loss listeners, and release all resources. |

Adapter hooks

Used internally by ThreeAdapter. Only call these when building a custom renderer adapter.

| Method | Description | |---|---| | setXRFrameHandler(fn) | Called every XR frame with pose, view, viewport, and framebuffer info. | | setAdapterResultHandler(fn) | Called after a successful VPS localization with the result and tracker-space matrix. | | setAdapterObjectTrackingHandler(fn) | Called after a successful object tracking result with the result and tracker-space matrix. | | setAdapterSessionHandlers(onStart, onEnd) | Called on session start/end, before user callbacks. |

ThreeAdapter

Wires XRSessionManager to a Three.js renderer. Handles XR framebuffer binding, camera matrix sync, preview loop, resize, and optional map mesh / gizmo / object mesh display.

import { ThreeAdapter } from '@multisetai/vps/three';

new ThreeAdapter(options: IThreeAdapterOptions)

IThreeAdapterOptions

| Parameter | Type | Description | |---|---|---| | session | XRSessionManager | Required. | | renderer | THREE.WebGLRenderer | Required. | | scene | THREE.Scene | Required. | | camera | THREE.PerspectiveCamera | Required. | | showMesh? | boolean | Show the VPS map mesh after localization. Default false. | | showGizmo? | boolean | Show a transform gizmo after localization. Default true. | | showObjectMeshes? | boolean | Load and display a 3D outline mesh for each detected object. Default false. | | useDefaultButton? | boolean | Mount the built-in START AR / STOP AR button. Default true. Set to false to drive the session via startSession() / stopSession(). | | buttonContainer? | HTMLElement | Where to append the built-in button. Defaults to overlayRoot or document.body. | | onButtonCreated? | (button: HTMLButtonElement) => void | Called after the built-in button is created. | | onXRFrame? | (event: IXRFrameEvent) => void | Called every XR frame after camera matrices are synced, before the scene is rendered. Use this to update scene objects each frame. | | onLocalizationSuccess? | (result: ILocalizeAndMapDetails, worldFromMap: THREE.Matrix4) => void | Called immediately after a successful VPS localization. worldFromMap transforms map-space coordinates to Three.js world space — use it to place content at known map coordinates. | | onObjectMeshLoaded? | (objectCode: string) => void | Called when a detected object's 3D mesh has been loaded and placed in the scene. Only fires when showObjectMeshes: true. |

Static methods

| Method | Returns | Description | |---|---|---| | ThreeAdapter.isSupported() | Promise<boolean> | Returns true if the browser supports immersive-ar WebXR sessions. |

Methods

| Method | Returns | Description | |---|---|---| | initialize(buttonContainer?) | HTMLButtonElement \| null | Start the preview render loop, attach resize handler, and mount the built-in button. Returns null when useDefaultButton: false. | | isActive() | boolean | Whether an XR session is currently running. | | isLocalizing | boolean | Whether a localization or tracking run is currently in progress. | | startSession() | Promise<void> | Start an AR session. Must be called from within a user gesture handler. | | stopSession() | void | Stop the active AR session. No-op if no session is running. | | localizeFrame() | Promise<ILocalizeAndMapDetails \| null> | Capture and localize one frame. | | trackObjects() | Promise<IObjectTrackingResponse \| null> | Capture one frame and run object detection. Requires mapType: 'object-tracking' on the client. | | clearObjectMeshes() | void | Remove all object meshes from the scene that were placed by showObjectMeshes. | | dispose() | void | Stop loops, remove listeners, dispose Three.js resources, and end the session. |

Events and scene access

The onLocalizationSuccess / onXRFrame options are single-slot: setting one replaces it. Use these listeners instead when more than one part of your app needs to react — anything layered on top of the adapter (MapSpace, Navigation, your own code) uses them, so they compose.

Every add*Listener returns its own unsubscribe function, which is usually easier than keeping a reference for the matching remove*Listener.

| Method | Returns | Description | |---|---|---| | addLocalizationListener(fn) | () => void | fn(result, worldFromMap) after every successful localization. | | removeLocalizationListener(fn) | void | Unsubscribe. Equivalent to calling the returned function. | | addSessionStartListener(fn) | () => void | Fires when the AR session starts. | | removeSessionStartListener(fn) | void | Unsubscribe. | | addSessionEndListener(fn) | () => void | Fires when the AR session ends. | | removeSessionEndListener(fn) | void | Unsubscribe. | | addFrameListener(fn) | () => void | fn(event) every XR frame, after camera matrices are synced and before the scene renders — so anything you move lands in the same frame. | | removeFrameListener(fn) | void | Unsubscribe. | | waitForLocalization() | Promise<ILocalizeAndMapDetails> | Resolves immediately if this session has already localized, otherwise on the next success. Never rejects. Replaces the usual "do X once we are localized" callback dance. | | getLastLocalization() | ILocalizationSnapshot \| null | The current session's most recent result plus its worldFromMap. Cleared on session end, so a stale pose can never be replayed into a new session. | | getScene() | THREE.Scene | The scene passed in options. | | getCamera() | THREE.Camera | The XR-driven camera. Read its pose with getWorldPosition() / matrixWorld, never camera.position — see the warning under Placing Content. |

NeedleAdapter

Needle Engine Behaviour that wires XRSessionManager to Needle's renderer and scene. Handles XR framebuffer binding, camera matrix sync, AR passthrough (transparent background), and optional map mesh / gizmo / object mesh display.

import { NeedleAdapter } from '@multisetai/vps/needle';

new NeedleAdapter(options: INeedleAdapterOptions)

Add to a scene via addNewComponent(gameObject, adapter) — this triggers awake(), which creates the session and mounts the button.

INeedleAdapterOptions

| Parameter | Type | Description | |---|---|---| | client | MultisetClient | Required. | | sessionOptions? | Omit<IXRSessionOptions, 'client'> | All session options and callbacks — forwarded directly to XRSessionManager. See IXRSessionOptions for the full list. | | showMesh? | boolean | Show the VPS map mesh after localization. Default false. | | showGizmo? | boolean | Show a transform gizmo after localization. Default false. | | showObjectMeshes? | boolean | Load and display a 3D outline mesh for each detected object. Default false. | | useDefaultButton? | boolean | Mount the built-in START AR / STOP AR button automatically in awake(). Default true. Set to false to drive the session via startSession() / stopSession(). | | buttonContainer? | HTMLElement | Where to append the built-in button. Defaults to overlayRoot or document.body. | | onButtonCreated? | (button: HTMLButtonElement) => void | Called after the built-in button is created. | | onXRFrame? | (event: IXRFrameEvent) => void | Called every XR frame after camera matrices are synced, before the scene is rendered. | | onLocalizationSuccess? | (result: ILocalizeAndMapDetails, worldFromMap: THREE.Matrix4) => void | Called after a successful VPS localization. worldFromMap transforms map-space coordinates to Three.js world space. | | onObjectMeshLoaded? | (objectCode: string) => void | Called when a detected object's 3D mesh has been loaded and placed in the scene. Only fires when showObjectMeshes: true. |

Static methods

| Method | Returns | Description | |---|---|---| | NeedleAdapter.isSupported() | Promise<boolean> | Returns true if the browser supports immersive-ar WebXR sessions. |

Methods

| Method | Returns | Description | |---|---|---| | isActive() | boolean | Whether an XR session is currently running. | | isLocalizing | boolean | Whether a localization or tracking run is currently in progress. | | startSession() | Promise<void> | Start an AR session. Must be called from within a user gesture handler. | | stopSession() | void | Stop the active AR session. No-op if no session is running. | | localizeFrame() | Promise<ILocalizeAndMapDetails \| null> | Capture and localize one frame. | | trackObjects() | Promise<IObjectTrackingResponse \| null> | Capture one frame and run object detection. Requires mapType: 'object-tracking' on the client. | | clearObjectMeshes() | void | Remove all object meshes placed by showObjectMeshes. | | registerAnchor(anchor) | void | Connect a dynamically created MapAnchor to the adapter. Registers localization listeners and immediately applies the last localization result if the session is already active. | | getSession() | XRSessionManager | Access the underlying session manager directly. Use only when you need low-level session control — for example getSession().getOverlayRoot() to mount UI that receives taps during AR. |

Events and scene access

Identical to ThreeAdapter — both adapters satisfy the same IVpsAdapter contract, which is what lets features like MapSpace and Navigation work on either without change.

Every add*Listener returns its own unsubscribe function. Either call that or the matching remove*Listener from your component's onDestroy — skipping it leaves the adapter holding a reference to a destroyed component.

| Method | Returns | Description | |---|---|---| | addLocalizationListener(fn) | () => void | fn(result, worldFromMap) after every successful localization. Prefer this over the constructor's onLocalizationSuccess when several components need to react. | | removeLocalizationListener(fn) | void | Unsubscribe. | | addSessionStartListener(fn) | () => void | Fires when AR begins. Useful for showing in-session UI. | | removeSessionStartListener(fn) | void | Unsubscribe. | | addSessionEndListener(fn) | () => void | Fires when AR ends. Useful for hiding anchored content between sessions. | | removeSessionEndListener(fn) | void | Unsubscribe. | | addFrameListener(fn) | () => void | fn(event) every XR frame, after camera matrices are synced and before the scene renders. | | removeFrameListener(fn) | void | Unsubscribe. | | waitForLocalization() | Promise<ILocalizeAndMapDetails> | Resolves immediately if this session has already localized, otherwise on the next success. Never rejects. | | getLastLocalization() | ILocalizationSnapshot \| null | The current session's most recent result plus its worldFromMap. Cleared on session end. | | getScene() | THREE.Scene | Needle's scene. | | getCamera() | THREE.Camera | The XR-driven camera. Read its pose with getWorldPosition() / matrixWorld, never camera.position. |

IVpsAdapter

The surface shared by ThreeAdapter and NeedleAdapter. Type against this and your code works on either — and on any future adapter.

import type { IVpsAdapter } from '@multisetai/vps/three';

function attachMyFeature(adapter: IVpsAdapter) {
  const off = adapter.addLocalizationListener((result, worldFromMap) => { /* ... */ });
  return off;
}

Both adapters satisfy it structurally — neither declares implements IVpsAdapter — and a compile-time guard in each entry point fails the build if one drifts from the interface.

It covers: isActive(), isLocalizing, getScene(), getCamera(), getLastLocalization(), the four add*Listener / remove*Listener pairs, waitForLocalization(), startSession(), stopSession(), localizeFrame() and trackObjects(). This is what MapSpace and Navigation depend on, which is why neither imports a concrete adapter.

ILocalizationSnapshot is { result: ILocalizeAndMapDetails; worldFromMap: THREE.Matrix4 }.

MapSpace

The VPS map coordinate frame. Nest your map-anchored content under it, and on every successful localization it is moved so its origin coincides with the scanned map's origin — every descendant follows by ordinary parenting.

A child's local position is therefore its map coordinate. That is what makes it cheap: relocalization, background localization and session restarts change only this one transform, so nothing computed relative to it ever needs recomputing.

It exists in two forms, and they are the same object:

| | Import | Use in | |---|---|---| | Package class | import { MapSpace } from '@multisetai/vps/three' | plain three.js, or from code in a Needle project | | Needle component | import { MapSpace } from './MapSpace.js' | Unity — a template file you copy into src/scripts/ |

The template is a thin Behaviour that owns a package MapSpace bound to its GameObject and forwards to it, so behaviour is identical. The Unity→three.js handedness correction lives in the package class — one verified implementation rather than a copy in every project.

import { MapSpace } from '@multisetai/vps/three';

const mapSpace = new MapSpace(new THREE.Object3D());
scene.add(mapSpace.object);
mapSpace.connect(adapter);                                  // ThreeAdapter or NeedleAdapter

mapSpace.add(marker, new THREE.Vector3(1.5, 0, -2));        // position IS a map coordinate

Options and fields

| Name | Type | Default | Description | |---|---|---|---| | hideUntilLocalized | boolean | true | Hide the object until the first localization, and re-hide on session end. Read live, so you can set it to false at runtime to keep content visible between sessions. In Needle this deactivates the entire subtree — see the setup notes. |

Methods

| Method | Returns | Description | |---|---|---| | connect(adapter) | void | Subscribe to an adapter so this frame is placed on every localization. Safe to call repeatedly — previous subscriptions are removed first. If the adapter has already localized in the current session, that result is replayed immediately, so a MapSpace created mid-session is placed at once. | | disconnect() | void | Remove every subscription made by connect(). | | applyLocalization(result, worldFromMap) | void | Place the frame directly, bypassing events. Useful in tests, or from a component that receives the result by its own route. | | add(object, mapCoordinate?) | void | Parent an object to this frame, optionally at a map coordinate. | | mapToWorld(v, target?) | THREE.Vector3 | Map space → world space. | | worldToMap(v, target?) | THREE.Vector3 | World space → map space. Use this to convert the camera pose before any map-space calculation. | | dispose() | void | Same as disconnect(). | | object | THREE.Object3D | Getter. The wrapped object — add it to your scene. | | isLocalized | boolean | Getter. True once a localization has been applied in the current session. | | MapSpace.toLocal(unityCoord, target?) | THREE.Vector3 | Static. Convert a Unity/left-handed coordinate copied from the portal's Map Viewer into map space. Editor-authored children get this from Needle's exporter and must not use it; content created in code must. |

In Unity

MultisetVPS discovers and wires all MapSpace components at startup. A scene should contain exactly one — MultisetVPS warns if it finds more, since they would all be moved to the same origin. The Needle component also exposes connectAdapter(adapter) and applyLocalization(result, worldFromMap), matching MapAnchor, so it can be registered at runtime with NeedleAdapter.registerAnchor(mapSpace). Reach the underlying package object through .space — for example mapSpace.space.worldToMap(...).

MapAnchor

Needle Engine Behaviour that anchors a single GameObject to the VPS map origin after localization.

Not exported from the package — MapAnchor is a template file you copy into your own src/scripts/ folder. Import it relatively: import { MapAnchor } from './MapAnchor.js'.

In Unity, add the component via the Inspector — MultisetVPS discovers and wires all MapAnchor instances at startup automatically. For laying out multiple POIs, prefer MapSpace. Do not nest a MapAnchor inside a MapSpace — the offset would be applied twice.

For runtime-spawned objects use NeedleAdapter.registerAnchor() (see MapAnchor — zero-code object placement above).

Fields

| Field | Type | Default | Description | |---|---|---|---| | offset | THREE.Vector3 | (0, 0, 0) | Position offset from the map origin in metres. When isRightHanded is false (default), enter Unity Inspector values directly — X is negated automatically. When true, supply Three.js values as-is. | | matchOrientation | boolean | true | Align the object's rotation to the map's orientation. | | rotationOffset | THREE.Euler | (0°, 0°, 0°) | Additional rotation applied on top of the map orientation. Only applied when matchOrientation is true. When isRightHanded is false (default), enter Unity Inspector values — Y and Z are negated automatically. | | hideUntilLocalized | boolean | true | Hide the object until the first successful localization. Re-hides on session end. | | isRightHanded | boolean | false | When false (default), offset and rotationOffset are treated as Unity (left-handed) values and converted automatically (negate X in position; negate Y and Z in rotation). Set to true if you are supplying Three.js (right-handed) values directly. |

Methods

| Method | Description | |---|---| | connectAdapter(adapter) | Called automatically by MultisetVPS. Registers localization and session-end listeners on the adapter. | | applyLocalization(result, worldFromMap) | Apply a localization result directly — positions and shows the object. Called internally by registerAnchor; also useful for testing or custom placement logic. |

Navigation

AR wayfinding state machine. Adapter-agnostic and free of DOM, geometry and renderer assumptions — see the full navigation guide.

import { Navigation, NavMeshPathfinder, buildPathRibbon } from '@multisetai/vps/navigation';

const pathfinder = await NavMeshPathfinder.fromObject3D(navMesh, { space: mapSpace.object });
const navigation = await Navigation.create({ adapter, mapSpace, pathfinder, pois });

Requires a MapSpace — every route is computed in map space, which is what makes relocalization free.

Methods and properties

| Member | Returns | Description | |---|---|---| | Navigation.create(options) | Promise<Navigation> | Static. Build and attach. Async so a future wasm-backed pathfinder can be awaited without changing call sites. | | setDestination(target) | void | Accepts an IMapPOI, a registered POI id, or a bare map coordinate. Emits unreachable and refuses to start if no route exists. | | stop() | void | Stop navigating and clear the path. | | recalculate() | void | Force an immediate recalculation, ignoring the interval and movement threshold. | | state | NavigationState | 'unlocalized' | 'idle' | 'navigating' | 'off-navmesh' | 'arrived'. | | destination | IMapPOI \| null | | | currentPath | readonly THREE.Vector3[] | Corners, in map space. Empty when not navigating. | | remainingDistance | number | Metres left along the current path. | | pois | readonly IMapPOI[] | | | setPOIs(list) / addPOI(poi) / removePOI(id) / getPOI(id) | | Manage the POI registry at runtime. Removing the active destination stops navigation. | | distanceTo(poi) | number | Walking distance in metres, or -1 when unknown. Throttled and cached, so it is safe to call per frame. | | isReachable(poi) | boolean | | | nearestPOI() | IMapPOI \| null | Closest by walking distance, skipping unreachable ones. | | getViewerMapPosition(target?) | THREE.Vector3 \| null | Viewer position in map space, or null before the first localization. | | diagnose() | NavigationDiagnosis | 'ok' | 'no-navmesh' | 'not-localized' | 'off-navmesh' | 'no-pois' | 'pois-off-navmesh'. The first thing to call when navigation "does nothing". | | on(event, fn) | () => void | Subscribe; returns unsubscribe. Events below. | | attach() / detach() | void | Subscribe to / unsubscribe from the adapter. create() attaches for you. | | update(deltaSeconds) | void | Advance manually. Only needed if you drive your own loop — normally the adapter ticks it. | | dispose() | void | | | Navigation.pathLength(corners) | number | Static. Summed distance between consecutive corners. |

Events

| Event | Payload | |---|---| | stateChanged | { state, previous } | | destinationChanged | IMapPOI \| null | | pathUpdated | { corners, remainingDistance } | | arrived | IMapPOI | | unreachable | IMapPOI — no complete route; navigation did not start | | tick | { deltaSeconds } — every frame, from the XR loop in-session and requestAnimationFrame outside one, so animation and UI work in a desktop preview |

NavMeshPathfinder

three-pathfinding behind a contract that holds. three-pathfinding is an optional peer dependency, loaded on demand — install it only if you build one of these.

| Member | Returns | Description | |---|---|---| | NavMeshPathfinder.fromObject3D(object, options?) | Promise<NavMeshPathfinder> | Static. Merges every descendant mesh and transforms it into options.space — pass mapSpace.object. | | NavMeshPathfinder.fromGeometry(geometry, options?) | Promise<NavMeshPathfinder> | Static. From geometry already in map space. | | findPath(from, to) | THREE.Vector3[] \| null | Corners inclusive of both ends. null means no complete route — a partial path is never returned as success. | | clampToNavMesh(p, maxDistance?) | THREE.Vector3 \| null | The viewer's projection: 3D distance, preferring the surface beneath. | | snapDestination(p, label?) | THREE.Vector3 \| null | A destination's projection: horizontal distance only, so any height works. | | geometry | THREE.BufferGeometry | Getter. The merged navmesh, in map space. Use it to build a debug overlay. | | groupCount | number | Getter. Disconnected walkable regions. More than one on a single floor means the navmesh is torn. | | dispose() | void | |

Options: space, weldTolerance, destinationSnapRadius (default 1 m, horizontal), destinationSnapWarnHeight (3 m), startRegionTolerance (1 m). The navigation guide explains why destination height is ignored and why these defaults are what they are.

StraightLinePathfinder implements the same IPathfinder interface and walks straight through walls — for development before a navmesh exists.

buildPathRibbon(corners, options?)

Path corners → ribbon triangles. The only rendering code in the package, because it is the only part with no design content and one correct answer. You own the Mesh and the material:

mesh.geometry = buildPathRibbon(corners, { width: 0.35, heightAboveFloor: 0.1 });

Vertex contract, stable API — write a shader against it: uv.x = distance along the path in metres (cumulative, horizontal, not normalised), uv.y = 0…1 across the width, two vertices per corner, one quad per segment, indexed, no normals. Metres keep a pattern's real-world size constant whatever the path length, and let it flow unbroken across corners.

Options

| Option | Default | Description | |---|---|---| | width | 0.35 | Ribbon width in metres. | | heightAboveFloor | 0.1 | Lift above the walkable surface. Raise it if the ribbon z-fights the floor. | | cornerRadius | 0.4 | Radius used to round off interior corners. 0 gives sharp corners. | | cornerSegments | 4 | Points per rounded corner. Higher is smoother and costs triangles. | | miterLimit | 3 | Cap on how far a sharp joint may extend, as a multiple of half-width. |

It handles the cases that are easy to get wrong, each of which shipped as a visible defect before testing caught it:

• Corners are rounded. At a sharp corner the two vertices are offset along the miter — the angle bisector — not perpendicular to either segment, so the quad is a trapezoid and any pattern on it is sheared by up to half the turn angle: ~45° on a right angle, which reads as arrows visibly bending. Rounding spreads that over a short arc, taking the worst edge angle from 45° to 76° where 90° is no shear. The radius clamps per corner to 40% of the shorter adjacent segment so tight zig-zags cannot fold the ribbon back on itself, and endpoints never move.
• Sharp miters are capped. The 1/cos(θ/2) scale that keeps ribbon width constant through a turn goes to infinity as the turn approaches 180°, firing a spike across the scene. Past the cap the joint narrows instead — a pinched corner is a much better failure mode.
• Coincident corners are dropped. A flat ribbon cannot express a purely vertical step, and a repeated corner has no direction; both give a zero-width joint. Pathfinders do emit these, so it runs on every path rather than being treated as bad input.
• Degenerate input returns an empty geometry rather than NaNs, so callers can hide the mesh on geometry.getAttribute('position')?.count instead of special-casing.

If you tile an arrow texture on it

Arrow size and arrow spacing must be separate controls. Mapping one texture repeat across the whole spacing interval — the obvious shortcut — stretches each arrow by spacing / width, which for a 0.35 m ribbon at 2 m spacing is 5.7×. Map the texture over an explicit arrow length and leave the remainder of the interval empty:

float along = vUv.x - uScrollOffset;                       // metres
float cell  = fract(along / max(uArrowSpacing, 0.0001));
float u     = cell * uArrowSpacing / max(uArrowLength, 0.0001);
if (u > 1.0) discard;                                      // the gap between arrows

Default the arrow length to the ribbon width and a square texture comes out undistorted. Arrow art is also conventionally a silhouette in the alpha channel with flat RGB, so treat the texture as a mask and take the colour from a uniform — multiplying by texel.rgb gives black arrows whatever colour you set. The samples' NavigationVisuals.ts implements both.

→ Full navigation guide

MultisetVPS

Inspector-driven Needle Engine component that bootstraps the full VPS stack — credentials, session, UI buttons, and MapSpace / MapAnchor discovery — from Unity Inspector fields alone.

Not exported from the package. MultisetVPS is a template file you copy into your own src/scripts/ folder, because Needle's Unity codegen only scans your project. Import it relatively if you need it in code:

import { MultisetVPS } from './MultisetVPS.js';
import { MapType } from './MapType.js';

See Unity Inspector workflow for setup. The template files handle TypeStore registration automatically — no manual register() call needed.

Inspector fields

| Field | Type | Default | Description | |---|---|---|---| | clientId | string | "" | Your Multiset client ID. | | clientSecret | string | "" | Your Multiset client secret. | | mapCode | string | "" | Map/map-set code, or comma-separated object codes for object-tracking mode. | | mapType | MapType | SingleMap | SingleMap, MapSet, or ObjectTracking. | | showMesh | boolean | true | Show the VPS map mesh after localization (VPS modes only). | | showGizmo | boolean | true | Show a transform gizmo after localization (VPS modes only). | | showObjectMeshes | boolean | false | Load and display a 3D outline mesh for each detected object (OT mode only). | | autoLocalize | boolean | true | Run one localization automatically when the session starts (VPS modes). | | relocalization | boolean | false | Re-localize whenever tracking is lost and then recovered. | | backgroundLocalization | boolean | false | Periodically localize in the background while the session is active. | | bgLocalizationInterval | number | 0 | Seconds between background localization attempts (10–180). 0 = SDK default. | | confidenceCheck | boolean | false | Only accept results above confidenceThreshold. | | confidenceThreshold | number | 0.5 | Minimum confidence (0.2–0.8). | | poseTimeoutMs | number | 0 | Max ms to wait for a valid viewer pose. 0 = SDK default (10 000 ms). | | convertToGeoCoordinates | boolean | false | Request geographic coordinates in the localization response. | | passGeoPose | boolean | false | Send a geolocation hint with each request. | | use2DFiltering | boolean | false | Skip altitude in geo filtering. Only valid when passGeoPose is enabled. | | hintPosition | string | "" | Local-space position hint "x,y,z". | | hintRadius | number | 0 | Search radius in metres around hintPosition. | | hintMapCodes | string | "" | Comma-separated map codes to restrict search (map-set mode only). | | autoTracking | boolean | false | Detect objects automatically when the session starts (OT mode). | | restartTracking | boolean | false | Re-attempt tracking when XR tracking is lost and recovered (OT mode). | | trackingCaptureDelayMs | number | 0 | Ms to wait before capturing a frame for tracking. |

Properties

| Property | Type | Description | |---|---|---| | adapter | NeedleAdapter \| null | The underlying NeedleAdapter after start() completes. Use this to call registerAnchor(), add listeners, or access the session directly. null until start resolves. |

Placing Content at Map Coordinates

Using Needle Engine? You do not need any of this. Use MapSpace to lay content out in the Unity Inspector, or MapAnchor for individual objects. The section below is for ThreeAdapter and custom renderers.

After localization, the onLocalizationSuccess callback on ThreeAdapter provides a worldFromMap matrix that converts any point from VPS map space into Three.js world space. Use this to anchor scene objects to specific physical locations in the scanned map — independently of where the user started the AR session.

const adapter = new ThreeAdapter({
  session,
  renderer, scene, camera,
  onLocalizationSuccess: (result, worldFromMap) => {
    // mapPoint is a position you measured from the scanned map (in metres)
    const mapPoint = new THREE.Vector3(1.5, 0, -2.0);

    const marker = new THREE.Mesh(
      new THREE.SphereGeometry(0.05),
      new THREE.MeshBasicMaterial({ color: 0x00ff88 })
    );
    marker.position.copy(mapPoint.applyMatrix4(worldFromMap));
    scene.add(marker);
  },
});

Note — worldFromMap is recomputed on every successful localization. If you re-localize, update or re-add your objects so they stay in sync with the latest result.

Styling the AR Button

The built-in button ships with minimal inline styles. Use these CSS classes to override appearance from your own stylesheet:

| Class | When present | |---|---| | `.multiset-a