Class XrAnchors

Anchors provide an ability to specify a point in the world that needs to be updated to correctly reflect the evolving understanding of the world by the underlying AR system, such that the anchor remains aligned with the same place in the physical world. Anchors tend to persist better relative to the real world, especially during a longer session with lots of movement.

app.xr.start(camera, pc.XRTYPE_AR, pc.XRSPACE_LOCALFLOOR, {
    anchors: true
});

Hierarchy (View Summary)

EventHandler
- XrAnchors

Index

Accessors

available

get available(): boolean
True if Anchors are available. This information is available only when session has started.

Returns boolean
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:487

list

get list(): XrAnchor[]
List of available XrAnchors.

Returns XrAnchor[]
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:526

persistence

get persistence(): boolean
True if Anchors support persistence.

Returns boolean
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:496

supported

get supported(): boolean
True if Anchors are supported.

Returns boolean
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:478

uuids

get uuids(): string[]
Array of UUID strings of persistent anchors, or null if not available.

Returns string[]
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:505

Methods

create

create(
    position: Vec3 | XRHitTestResult,
    rotation?: Quat | XrAnchorCreateCallback,
    callback?: XrAnchorCreateCallback,
): void

Create an anchor using position and rotation, or from hit test result.

Parameters

position: Vec3 | XRHitTestResult
Position for an anchor or a hit test result.
Optionalrotation: Quat | XrAnchorCreateCallback
Rotation for an anchor or a callback if creating from a hit test result.
Optionalcallback: XrAnchorCreateCallback
Callback to fire when anchor was created or failed to be created.

Returns void

Example

// create an anchor using a position and rotation
app.xr.anchors.create(position, rotation, function (err, anchor) {
    if (!err) {
        // new anchor has been created
    }
});

Example

// create an anchor from a hit test result
hitTestSource.on('result', (position, rotation, inputSource, hitTestResult) => {
    app.xr.anchors.create(hitTestResult, function (err, anchor) {
        if (!err) {
            // new anchor has been created
        }
    });
});

fire

fire(
    name: string,
    arg1?: any,
    arg2?: any,
    arg3?: any,
    arg4?: any,
    arg5?: any,
    arg6?: any,
    arg7?: any,
    arg8?: any,
): EventHandler
Fire an event, all additional arguments are passed on to the event listener.
Parameters
- name: string
  Name of event to fire.
- Optionalarg1: any
  First argument that is passed to the event handler.
- Optionalarg2: any
  Second argument that is passed to the event handler.
- Optionalarg3: any
  Third argument that is passed to the event handler.
- Optionalarg4: any
  Fourth argument that is passed to the event handler.
- Optionalarg5: any
  Fifth argument that is passed to the event handler.
- Optionalarg6: any
  Sixth argument that is passed to the event handler.
- Optionalarg7: any
  Seventh argument that is passed to the event handler.
- Optionalarg8: any
  Eighth argument that is passed to the event handler.
Returns EventHandler
Self for chaining.
Example
```
obj.fire('test', 'This is the message');
```
Inherited from EventHandler.fire
- Defined in submodules/engine/src/core/event-handler.js:265

forget

forget(uuid: string, callback?: XrAnchorForgetCallback): void
Forget an anchor by removing its UUID from underlying systems.
Parameters
- uuid: string
  UUID string associated with persistent anchor.
- Optionalcallback: XrAnchorForgetCallback
  Callback to fire when anchor persistent data was removed or error if failed.
Returns void
Example
```
// forget all available anchors
const uuids = app.xr.anchors.uuids;
for(let i = 0; i < uuids.length; i++) {
    app.xr.anchors.forget(uuids[i]);
}
```
- Defined in submodules/engine/src/framework/xr/xr-anchors.js:358

hasEvent

hasEvent(name: string): boolean
Test if there are any handlers bound to an event name.
Parameters
- name: string
  The name of the event to test.
Returns boolean
True if the object has handlers bound to the specified event name.
Example
```
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
```
Inherited from EventHandler.hasEvent
- Defined in submodules/engine/src/core/event-handler.js:333

off

off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Parameters
- Optionalname: string
  Name of the event to unbind.
- Optionalcallback: HandleEventCallback
  Function to be unbound.
- Optionalscope: object
  Scope that was used as the this when the event is fired.
Returns EventHandler
Self for chaining.
Example
```
const handler = function () {
};
obj.on('test', handler);

obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
```
Inherited from EventHandler.off
- Defined in submodules/engine/src/core/event-handler.js:145

on

on(name: string, callback: HandleEventCallback, scope?: object): EventHandle
Attach an event handler to an event.
Parameters
- name: string
  Name of the event to bind the callback to.
- callback: HandleEventCallback
  Function that is called when event is fired. Note the callback is limited to 8 arguments.
- Optionalscope: object = ...
  Object to use as 'this' when the event is fired, defaults to current this.
Returns EventHandle
Can be used for removing event in the future.
Example
```
obj.on('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
```
Example
```
const evt = obj.on('test', function (a, b) {
    console.log(a + b);
});
// some time later
evt.off();
```
Inherited from EventHandler.on
- Defined in submodules/engine/src/core/event-handler.js:102

once

once(name: string, callback: HandleEventCallback, scope?: object): EventHandle
Attach an event handler to an event. This handler will be removed after being fired once.
Parameters
- name: string
  Name of the event to bind the callback to.
- callback: HandleEventCallback
  Function that is called when event is fired. Note the callback is limited to 8 arguments.
- Optionalscope: object = ...
  Object to use as 'this' when the event is fired, defaults to current this.
Returns EventHandle
- can be used for removing event in the future.
Example
```
obj.once('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled
```
Inherited from EventHandler.once
- Defined in submodules/engine/src/core/event-handler.js:122

restore

restore(uuid: string, callback?: XrAnchorCreateCallback): void

Restore anchor using persistent UUID.

Parameters

uuid: string
UUID string associated with persistent anchor.
Optionalcallback: XrAnchorCreateCallback
Callback to fire when anchor was created or failed to be created.

Returns void

Example

// restore an anchor using uuid string
app.xr.anchors.restore(uuid, function (err, anchor) {
    if (!err) {
        // new anchor has been created
    }
});

Example

// restore all available persistent anchors
const uuids = app.xr.anchors.uuids;
for(let i = 0; i < uuids.length; i++) {
    app.xr.anchors.restore(uuids[i]);
}

Events

`Static`EVENT_ADD

EVENT_ADD: string = 'add'

Fired when a new XrAnchor is added. The handler is passed the XrAnchor that was added.

Example

app.xr.anchors.on('add', (anchor) => {
    console.log('Anchor added');
});

`Static`EVENT_AVAILABLE

EVENT_AVAILABLE: string = 'available'

Fired when anchors become available.

Example

app.xr.anchors.on('available', () => {
    console.log('Anchors are available');
});

`Static`EVENT_DESTROY

EVENT_DESTROY: string = 'destroy'

Fired when an XrAnchor is destroyed. The handler is passed the XrAnchor that was destroyed.

Example

app.xr.anchors.on('destroy', (anchor) => {
    console.log('Anchor destroyed');
});

`Static`EVENT_ERROR

EVENT_ERROR: string = 'error'

Fired when an anchor failed to be created. The handler is passed an Error object.

Example

app.xr.anchors.on('error', (err) => {
    console.error(err.message);
});

`Static`EVENT_UNAVAILABLE

EVENT_UNAVAILABLE: string = 'unavailable'

Fired when anchors become unavailable.

Example

app.xr.anchors.on('unavailable', () => {
    console.log('Anchors are unavailable');
});

Class XrAnchors

Hierarchy (View Summary)

Index

Accessors

Methods

Events

Accessors

available

Returns boolean

list

Returns XrAnchor[]

persistence

Returns boolean

supported

Returns boolean

uuids

Returns string[]

Methods

create

Parameters

Returns void

Example

Example

fire

Parameters

Returns EventHandler

Example

forget

Parameters

Returns void

Example

hasEvent

Parameters

Returns boolean

Example

off

Parameters

Returns EventHandler

Example

on

Parameters

Returns EventHandle

Example

Example

once

Parameters

Returns EventHandle

Example

restore

Parameters

Returns void

Example

Example

Events

StaticEVENT_ADD

Example

StaticEVENT_AVAILABLE

Example

StaticEVENT_DESTROY

Example

StaticEVENT_ERROR

Example

StaticEVENT_UNAVAILABLE

Example

Settings

On This Page

`Static`EVENT_ADD

`Static`EVENT_AVAILABLE

`Static`EVENT_DESTROY

`Static`EVENT_ERROR

`Static`EVENT_UNAVAILABLE