Skip to main content

Class: AnchorManager

Defined in: src/world/anchors/AnchorManager.ts:60

Creates and tracks spatial anchors, and restores previously saved ones.

Anchors let content stay attached to a real place as the platform refines its understanding of the room. With persistence enabled, handles are saved so the same content can be recovered in a later session.

Every anchor API this uses is optional in WebXR, so the manager degrades quietly: on a platform without anchors, creation returns null and nothing throws.

Extends​

Constructors​

Constructor​

new AnchorManager(injectedStore?): AnchorManager

Defined in: src/world/anchors/AnchorManager.ts:98

Parameters​

injectedStore?​

AnchorStore

Returns​

AnchorManager

Overrides​

Script.constructor

Properties​

capability​

capability: AnchorCapability = 'unsupported'

Defined in: src/world/anchors/AnchorManager.ts:68

What the current platform supports; refreshed each frame.


isXRScript​

isXRScript: boolean = true

Defined in: src/core/Script.ts:100

Inherited from​

Script.isXRScript


lastError​

lastError: unknown = null

Defined in: src/world/anchors/AnchorManager.ts:76

The most recent failure, or null.

Exposed rather than only logged so callers can surface anchor problems in their own UI instead of leaving the user with silently missing content.


xb?​

optional xb: XBObjectOptions

Defined in: src/interaction/InteractionTypes.ts:34

Inherited from​

Script.xb


dependencies​

static dependencies: object

Defined in: src/world/anchors/AnchorManager.ts:61

options​

options: typeof WorldOptions = WorldOptions

rendererHolder​

rendererHolder: typeof RendererHolder = RendererHolder

xrReferenceSpaceCache​

xrReferenceSpaceCache: typeof XRReferenceSpaceCache = XRReferenceSpaceCache

Methods​

create()​

create(pose, label, poseSpace, anchorSpace): Promise<TrackedAnchor | null>

Defined in: src/world/anchors/AnchorManager.ts:195

Creates an anchor at a pose.

Parameters​

pose​

XRRigidTransform

Pose for the new anchor.

label​

string

Label carried through persistence.

poseSpace​

Space the pose is expressed in. Defaults to the frame's reference space.

XRReferenceSpaceType | XRSpace | null

anchorSpace​

Space to anchor against. Defaults to 'bounded-floor'.

XRReferenceSpaceType | XRSpace

Returns​

Promise<TrackedAnchor | null>

The tracked anchor, or null when it could not be created.


delete()​

delete(id): void

Defined in: src/world/anchors/AnchorManager.ts:586

Stops tracking an anchor and forgets any saved handle for it.

Parameters​

id​

string

Id of a tracked anchor.

Returns​

void


dispose()​

dispose(): void

Defined in: src/world/anchors/AnchorManager.ts:758

Releases every tracked anchor. Saved handles are left in storage.

Returns​

void

Overrides​

Script.dispose


forgetAll()​

forgetAll(): void

Defined in: src/world/anchors/AnchorManager.ts:677

Forgets every saved handle, leaving live anchors alone.

Returns​

void


getAll()​

getAll(): TrackedAnchor[]

Defined in: src/world/anchors/AnchorManager.ts:605

Every anchor currently tracked.

Returns​

TrackedAnchor[]

The tracked anchors.


getPose()​

getPose(id, referenceSpace?): XRPose | null

Defined in: src/world/anchors/AnchorManager.ts:550

Reads an anchor's current pose.

Parameters​

id​

string

Id of a tracked anchor.

referenceSpace?​

XRReferenceSpace

Space to express the pose in. Not needed for simulated anchors, which hold their own pose.

Returns​

XRPose | null

The pose, or null when the anchor is not currently tracked.


init()​

init(dependencies): void

Defined in: src/world/anchors/AnchorManager.ts:108

Initializes the manager.

Parameters​

dependencies​

Resolved dependencies: the world options carrying the anchor settings, and the renderer supplying the reference space that anchor poses are expressed against.

options​

WorldOptions

rendererHolder?​

RendererHolder

xrReferenceSpaceCache?​

XRReferenceSpaceCache

Returns​

void

Overrides​

Script.init


initPhysics()​

initPhysics(_physics): void | Promise<void>

Defined in: src/core/Script.ts:119

Enables depth-aware interactions with physics. See /samples/advanced/ballpit

Parameters​

_physics​

Physics

Returns​

void | Promise<void>

Inherited from​

Script.initPhysics


onHoverEnter()​

onHoverEnter(_event): void

Defined in: src/core/Script.ts:222

Called when a source starts hovering over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

Script.onHoverEnter


onHoverExit()​

onHoverExit(_event): void

Defined in: src/core/Script.ts:228

Called when a source stops hovering over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

Script.onHoverExit


onHovering()​

onHovering(_event): void

Defined in: src/core/Script.ts:234

Called while a source hovers over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

Script.onHovering


onKeyDown()​

onKeyDown(_event): void

Defined in: src/core/Script.ts:159

Called on keyboard keypress.

Parameters​

_event​

KeyEvent

Event containing .code to read the keyboard key.

Returns​

void

Inherited from​

Script.onKeyDown


onKeyUp()​

onKeyUp(_event): void

Defined in: src/core/Script.ts:160

Parameters​

_event​

KeyEvent

Returns​

void

Inherited from​

Script.onKeyUp


onLongSelect()​

onLongSelect(_event): void

Defined in: src/core/Script.ts:153

Called when an object selection reaches the long-select delay.

Parameters​

_event​

LongSelectEvent

Returns​

void

Inherited from​

Script.onLongSelect


onObjectGrabbing()​

onObjectGrabbing(_event): void

Defined in: src/core/Script.ts:260

Called every frame a hand is grabbing this object.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

Script.onObjectGrabbing


onObjectGrabEnd()​

onObjectGrabEnd(_event): void

Defined in: src/core/Script.ts:265

Called when a hand stops grabbing this object. This ends built-in direct-touch manipulation without ending contact.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

Script.onObjectGrabEnd


onObjectGrabStart()​

onObjectGrabStart(_event): void

Defined in: src/core/Script.ts:256

Called when a hand starts grabbing this object (touching + pinching). A grab starts built-in direct-touch manipulation when enabled.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

Script.onObjectGrabStart


onObjectLongSelect()​

onObjectLongSelect(_event): void

Defined in: src/core/Script.ts:210

Called once when a captured selection is held for the long-select delay. Manipulation captures do not emit this callback.

Parameters​

_event​

LongSelectEvent

The controller and completed hold duration. Call event.stopPropagation() to stop bubbling to ancestor Scripts. Call event.stopGlobalPropagation() to suppress global selection callbacks for the rest of this capture

Returns​

void

Inherited from​

Script.onObjectLongSelect


onObjectManipulate()​

onObjectManipulate(_event): void

Defined in: src/core/Script.ts:216

Called for each phase of an automatic object manipulation. Call event.stopPropagation() to stop bubbling. Calling preventDefault() on a start event suppresses the automatic action.

Parameters​

_event​

ManipulationEvent

Returns​

void

Inherited from​

Script.onObjectManipulate


onObjectSelectEnd()​

onObjectSelectEnd(_event): void

Defined in: src/core/Script.ts:201

Called when a source stops selecting the object this Script represents.

Parameters​

_event​

SelectEndEvent

The completed state and end reason. Call event.stopPropagation() to stop bubbling to ancestor Scripts. Call event.stopGlobalPropagation() to suppress global selection callbacks for the rest of this capture

Returns​

void

Inherited from​

Script.onObjectSelectEnd


onObjectSelectStart()​

onObjectSelectStart(_event): void

Defined in: src/core/Script.ts:193

Called when a source starts selecting the object this Script represents.

Parameters​

_event​

SelectEvent

event.target is the logical object and event.source.controller identifies the controller. Call event.stopPropagation() to stop bubbling to ancestor Scripts. Call event.stopGlobalPropagation() to suppress global selection callbacks for the rest of this capture

Returns​

void

Inherited from​

Script.onObjectSelectStart


onObjectTouchEnd()​

onObjectTouchEnd(_event): void

Defined in: src/core/Script.ts:251

Called when a hand's index finger stops touching this object. This ends the default selection lifecycle after the touch callback.

Parameters​

_event​

ObjectTouchEvent

Returns​

void

Inherited from​

Script.onObjectTouchEnd


onObjectTouching()​

onObjectTouching(_event): void

Defined in: src/core/Script.ts:246

Called every frame that a hand's index finger is touching this object. The object remains selected during these frames unless touch selection was prevented when contact started.

Parameters​

_event​

ObjectTouchEvent

Returns​

void

Inherited from​

Script.onObjectTouching


onObjectTouchStart()​

onObjectTouchStart(_event): void

Defined in: src/core/Script.ts:240

Called when a hand's index finger starts touching this object. Direct touch starts the object's selection lifecycle by default. Call event.preventDefault() to handle contact without selecting.

Parameters​

_event​

ObjectTouchStartEvent

Returns​

void

Inherited from​

Script.onObjectTouchStart


onSelect()​

onSelect(_event): void

Defined in: src/core/Script.ts:145

Called whenever pinch / mouse click successfully completes, globally.

Parameters​

_event​

SelectEvent

The interaction source and completed target.

Returns​

void

Inherited from​

Script.onSelect


onSelectEnd()​

onSelectEnd(_event): void

Defined in: src/core/Script.ts:139

Called whenever pinch / mouse click discontinues, globally.

Parameters​

_event​

SelectEndEvent

The completed state and end reason.

Returns​

void

Inherited from​

Script.onSelectEnd


onSelecting()​

onSelecting(_event): void

Defined in: src/core/Script.ts:150

Called whenever pinch / mouse click is happening, globally.

Parameters​

_event​

SelectEvent

Returns​

void

Inherited from​

Script.onSelecting


onSelectStart()​

onSelectStart(_event): void

Defined in: src/core/Script.ts:133

Called whenever pinch / mouse click starts, globally.

Parameters​

_event​

SelectEvent

The interaction source and optional captured target.

Returns​

void

Inherited from​

Script.onSelectStart


onSessionEnded()​

onSessionEnded(): void

Defined in: src/world/anchors/AnchorManager.ts:168

Releases everything belonging to a session that has ended.

Anchors do not survive their session, so keeping them would leave dead handles that later restores would treat as already restored. Saved records are untouched, since restoring them is the entire point.

Returns​

void


onSimulatorStarted()​

onSimulatorStarted(): void

Defined in: src/core/Script.ts:125

Returns​

void

Inherited from​

Script.onSimulatorStarted


onSqueeze()​

onSqueeze(_event): void

Defined in: src/core/Script.ts:182

Called whenever gamepad trigger successfully completes, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

Script.onSqueeze


onSqueezeEnd()​

onSqueezeEnd(_event): void

Defined in: src/core/Script.ts:171

Called whenever gamepad trigger stops, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

Script.onSqueezeEnd


onSqueezeStart()​

onSqueezeStart(_event): void

Defined in: src/core/Script.ts:166

Called whenever gamepad trigger starts, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

Script.onSqueezeStart


onSqueezing()​

onSqueezing(_event): void

Defined in: src/core/Script.ts:176

Called whenever gamepad is being triggered, globally.

Parameters​

_event​

SelectEvent

Returns​

void

Inherited from​

Script.onSqueezing


onXRSessionEnded()​

onXRSessionEnded(): void

Defined in: src/core/Script.ts:123

Returns​

void

Inherited from​

Script.onXRSessionEnded


onXRSessionStarted()​

onXRSessionStarted(_session?): void

Defined in: src/core/Script.ts:122

Parameters​

_session?​

XRSession

Returns​

void

Inherited from​

Script.onXRSessionStarted


persist()​

persist(id): Promise<boolean>

Defined in: src/world/anchors/AnchorManager.ts:437

Saves an anchor's handle so it can be restored in a later session.

Parameters​

id​

string

Id of a tracked anchor.

Returns​

Promise<boolean>

Whether a handle was saved.


physicsStep()​

physicsStep(): void

Defined in: src/core/Script.ts:120

Returns​

void

Inherited from​

Script.physicsStep


platformHandles()​

platformHandles(): string[]

Defined in: src/world/anchors/AnchorManager.ts:623

Every persistent handle the platform is currently holding for this origin.

Only the headset runtimes implement this; Chrome ships the anchors module without persistence, where the attribute is absent rather than empty. An empty result therefore means "nothing to report", not "the platform holds none".

Scoped to the origin, not to this store. Two pages on one origin see each other's handles here, so a handle missing from your own records is not evidence of a leak and must not be deleted on that basis.

Returns​

string[]

The handles, or an empty array when unavailable.


releaseAllPlatformHandles()​

releaseAllPlatformHandles(): Promise<number>

Defined in: src/world/anchors/AnchorManager.ts:651

Releases every persistent handle the platform is holding for this origin.

A recovery path, not routine cleanup. Platforms cap how many persistent anchors may exist, and once local records are gone nothing names the handles any more, so AnchorManager.forgetAll cannot reach them and the cap stays full forever. This reads the platform's own list instead.

Origin wide and destructive: another page on the same origin loses its anchors too. Offer it as an explicit choice, never as automatic cleanup.

The platform's list is not guaranteed to shrink as handles are released, so do not read it back afterwards to judge whether this worked. The returned count is what the platform actually accepted.

Returns​

Promise<number>

How many handles the platform accepted a release for.


restoreAll()​

restoreAll(session?): Promise<AnchorRestoreResult[]>

Defined in: src/world/anchors/AnchorManager.ts:490

Restores every saved anchor.

Re-localisation is probabilistic, so a handle that cannot be resolved here is reported as not-found rather than treated as an error, and one failure never stops the rest of the batch.

Parameters​

session?​

XRSession | null

Returns​

Promise<AnchorRestoreResult[]>

One result per saved record, in stored order.


update()​

update(_time?, frame?): void

Defined in: src/world/anchors/AnchorManager.ts:133

Refreshes platform capability and drops anchors the platform has released.

Parameters​

_time?​

number

Frame timestamp, unused.

frame?​

XRFrame

The current XR frame.

Returns​

void

Overrides​

Script.update