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
dispose()	void	End session, remove listeners, release resources
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

Event Listeners

NeedleAdapter supports multiple subscribers per event, unlike the single-callback pattern on XRSessionManager.

Method	Description
addLocalizationListener(fn)	Subscribe to (result, worldFromMap) on each successful localization
removeLocalizationListener(fn)	Unsubscribe
addSessionStartListener(fn)	Subscribe to session start
removeSessionStartListener(fn)	Unsubscribe
addSessionEndListener(fn)	Subscribe to session end
removeSessionEndListener(fn)	Unsubscribe

Always call the matching remove* method in onDestroy() to avoid memory leaks.

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.