OpenXRFbSpatialAnchorManager

Inherits: Node

Provides an easy-to-use way to interact with Meta's Spatial Anchors.

Description

Provides an easy-to-use way to interact with Meta's Spatial Anchors.

Spatial anchors allow the developer to place virtual objects in a real world location that is persisted over time and adjusted by the headsets tracking.

This node allows creating, loading, or removing spatial anchors; and instantiating a scene to represent the virtual objects located at those anchors. Each instantiated scene will be added as a child of an XRAnchor3D node that will be positioned using tracking data from the headset.

Even though the spatial anchors are saved to the headset's local storage, only the UUID and position are saved. Any application-specific data about what those spatial anchors actually represent (for example, what virtual object is placed there) must be saved by the developer in some other way (for example, as a file saved in user://). For this reason, spatial anchors aren't automatically loaded (like OpenXRFbSceneManager does for scene anchors), and the developer must call load_anchors to reload persisted anchors.

Properties

PackedScene	scene
StringName	scene_setup_method	`&"setup_scene"`
bool	visible	`true`

Methods

void	create_anchor ( Transform3D transform, Dictionary custom_data={} )
XRAnchor3D	get_anchor_node ( StringName uuid ) const
Array	get_anchor_uuids ( ) const
OpenXRFbSpatialEntity	get_spatial_entity ( StringName uuid ) const
void	hide ( )
void	load_anchor ( StringName uuid, Dictionary custom_data={}, StorageLocation location=0 )
void	load_anchors ( StringName[] uuids, Dictionary all_custom_data={}, StorageLocation location=0, bool erase_unknown_anchors=false )
void	show ( )
void	track_anchor ( OpenXRFbSpatialEntity spatial_entity )
void	untrack_anchor ( Variant spatial_entity_or_uuid )

Signals

openxr_fb_spatial_anchor_create_failed ( Transform3D transform, Dictionary custom_data )

Emitted after create_anchor is called, if the operation was unsuccessful.

openxr_fb_spatial_anchor_load_failed ( StringName uuid, Dictionary custom_data, int location )

Emitted after load_anchor or load_anchors is called, if the operation was unsuccessful.

openxr_fb_spatial_anchor_track_failed ( Object spatial_entity )

Emitted after track_anchor is called, if the operation was unsuccessful.

openxr_fb_spatial_anchor_tracked ( Object anchor_node, Object spatial_entity, bool is_new )

Emitted any time a new spatial anchor is successfully tracked, as a result of calling create_anchor, load_anchor, load_anchors or track_anchor.

openxr_fb_spatial_anchor_untracked ( Object anchor_node, Object spatial_entity )

Emitted any time a spatial anchor is untracked as a result of calling untrack_anchor.

This signal will be emitted regardless of whether the operation was fully successful or not.

Property Descriptions

PackedScene scene

void set_scene ( PackedScene value )
PackedScene get_scene ( )

The scene to be instantiated automatically for each spatial anchor.

This is optional - using the openxr_fb_spatial_anchor_tracked signal and creating any necessary nodes from there is a valid alternative approach.

StringName scene_setup_method = &"setup_scene"

void set_scene_setup_method ( StringName value )
StringName get_scene_setup_method ( )

The method that will be called on scenes after they have been instantiated for a spatial anchor.

The method will be called with a single OpenXRFbSpatialEntity argument, representing the spatial anchor.

bool visible = true

void set_visible ( bool value )
bool get_visible ( )

Controls the visibility of the spatial anchors managed by this node.

Method Descriptions

void create_anchor ( Transform3D transform, Dictionary custom_data={} )

Creates a new spatial anchor at the given position (in global space).

The custom_data argument is application-specific data about what the spatial entity represents (for example, what virtual object should be placed there). This data will be stashed on OpenXRFbSpatialEntity.custom_data.

This is an asynchronous operation - the openxr_fb_spatial_anchor_tracked signal will be emitted if creation was successful, or the openxr_fb_spatial_anchor_create_failed signal will be emitted if unsuccessful.

XRAnchor3D get_anchor_node ( StringName uuid ) const

Gets the XRAnchor3D node which was created for the spatial entity with the given UUID.

Note: All anchors will be created asynchronously via create_anchor, load_anchor, load_anchors, or track_anchor.

Array get_anchor_uuids ( ) const

Gets the UUIDs of all spatial anchors that have been created.

Note: All anchors will be created asynchronously via create_anchor, load_anchor, load_anchors, or track_anchor.

OpenXRFbSpatialEntity get_spatial_entity ( StringName uuid ) const

Gets the spatial entity identified by the given UUID.

Note: All anchors will be created asynchronously via create_anchor, load_anchor, load_anchors, or track_anchor.

void hide ( )

Hides all spatial anchors created by this manager.

void load_anchor ( StringName uuid, Dictionary custom_data={}, StorageLocation location=0 )

Loads a spatial anchor with the given UUID from the given storage.

The custom_data argument is application-specific data about what the spatial entity represents (for example, what virtual object should be placed there). This data will be stashed on OpenXRFbSpatialEntity.custom_data.

This is an asynchronous operation - the openxr_fb_spatial_anchor_tracked signal will be emitted if the load was successful, or the openxr_fb_spatial_anchor_load_failed signal will be emitted if unsuccessful.

void load_anchors ( StringName[] uuids, Dictionary all_custom_data={}, StorageLocation location=0, bool erase_unknown_anchors=false )

Loads a list of spatial anchors with the given UUIDs from the given storage.

The all_custom_data argument is a Dictionary containing application-specific data about what the spatial entity represents (for example, what virtual object should be placed there), keyed by the UUID of the spatial anchor its associated with. This data will be stashed on OpenXRFbSpatialEntity.custom_data.

If erase_unknown_anchors is true, then all spatial anchors tracked by the headset that aren't in the given list of UUIDs will be erased. This can be used to clean up the list of spatial anchors, if some weren't erased from storage.

This is an asynchronous operation - the openxr_fb_spatial_anchor_tracked signal will be emitted (for each anchor) if the load was successful, or the openxr_fb_spatial_anchor_load_failed signal will be emitted (for each anchor) if unsuccessful.

void show ( )

Shows all spatial anchors created by this manager, if they had been previously hidden.

void track_anchor ( OpenXRFbSpatialEntity spatial_entity )

Tracks an existing OpenXRFbSpatialEntity.

This is an asynchronous operation - the openxr_fb_spatial_anchor_tracked signal will be emitted if the tracking was successful, or the openxr_fb_spatial_anchor_track_failed signal will be emitted if unsuccessful.

void untrack_anchor ( Variant spatial_entity_or_uuid )

Untracks the given spatial anchor (either by UUID or OpenXRFbSpatialEntity object).

This will remove the XRAnchor3D node and will erase the anchor from local headset storage automatically. If it's been stored in the cloud, it can be erased by calling OpenXRFbSpatialEntity.erase_from_storage.

This is an asynchronous operation - the openxr_fb_spatial_anchor_untracked signal will be emitted regardless of whether the operation was fully successful or not.