NeedleAdapter

Needle Engine Behaviour that wires XRSessionManager to Needle's renderer

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

A Needle Engine Behaviour that owns XRSessionManager and wires it to Needle's render loop. It replaces Needle's built-in WebXR session on awake(). Use NeedleAdapter programmatically for custom logic; use MultisetVPS when you want Inspector-driven setup.

Constructor

new NeedleAdapter(options: INeedleAdapterOptions)

Options

Parameter	Type	Default	Description
client	MultisetClient	Required	Authorized HTTP client
sessionOptions	Omit<IXRSessionOptions, 'client'>	—	All XRSessionManager options except client. See XRSessionManager.
showMesh	boolean	false	Download and display the map mesh after localization
showGizmo	boolean	false	Display a transform gizmo at the map origin
showObjectMeshes	boolean	false	Download and display 3D outline meshes for detected objects
useDefaultButton	boolean	true	Mount the built-in AR button in awake()
buttonContainer	HTMLElement	—	Container element for the AR button
onButtonCreated	(button: HTMLButtonElement) => void	—	Called when the button is created
onXRFrame	(event: IXRFrameEvent) => void	—	Called every XR frame
onLocalizationSuccess	(result: ILocalizeAndMapDetails, worldFromMap: THREE.Matrix4) => void	—	Called after successful localization
onObjectMeshLoaded	(objectCode: string) => void	—	Called when an object mesh finishes loading

Static Methods

Method	Returns	Description
NeedleAdapter.isSupported()	Promise<boolean>	Check if the browser supports immersive-ar

Instance Methods

Method	Returns	Description
startSession()	Promise<void>	Start the AR session from a user gesture handler
stopSession()	void	Stop the active session
localizeFrame()	Promise<ILocalizeAndMapDetails | null>	Capture and localize one frame
trackObjects()	Promise<IObjectTrackingResponse | null>	Capture and run object detection
isActive()	boolean	Whether an AR session is running
clearObjectMeshes()	void	Remove all loaded object meshes
getSession()	XRSessionManager	Access the underlying session manager. Use getSession().getOverlayRoot() to mount UI that receives taps during a session.
registerAnchor(anchor: IMapAnchor)	void	Wire a runtime-spawned MapAnchor to this adapter. Replays the last localization result immediately if one is available.

Properties

Property	Type	Description
isLocalizing	boolean	Whether localization or tracking is in progress

Events and Scene Access

The onLocalizationSuccess and onXRFrame options are single-slot: setting one replaces it. Use the listeners below when more than one part of your app needs to react. Anything layered on the adapter, including MapSpace and Navigation, 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 the current session has already localized, otherwise on the next success. Never rejects.
getLastLocalization()	ILocalizationSnapshot | null	The current session's most recent result and its worldFromMap. Cleared when the session ends, so a stale pose can never be replayed into a new session.
getScene()	THREE.Scene	The active scene
getCamera()	THREE.Camera	The XR-driven camera

waitForLocalization() replaces the usual "do this once we are localized" callback plumbing:

await adapter.waitForLocalization();
// the map frame is positioned; safe to read poses or start navigation

Read the camera pose with camera.getWorldPosition(target) or camera.matrixWorld, never camera.position. During a session the adapter writes matrixWorld directly and leaves position and quaternion untouched, so reading position returns a stale value.

IVpsAdapter

Both adapters satisfy the same IVpsAdapter contract, so a feature written against it works on either one and on any future adapter.

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

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

They satisfy it structurally, so neither declares implements. A compile-time guard in each entry point fails the build if one drifts from the interface. ILocalizationSnapshot is { result: ILocalizeAndMapDetails; worldFromMap: THREE.Matrix4 }.

Needle Lifecycle

Method	Called when
awake()	Component added to scene. Disables Needle's built-in WebXR, creates XRSessionManager, mounts the AR button.
onDestroy()	Component removed. Disposes session, world, removes all listeners.