# XrAnchors

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: XR

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/xr/xr-anchors.js#L35

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.

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

## Accessors

### available

```ts
get available(): boolean
```

True if Anchors are available. This information is available only when session has started.

### list

```ts
get list(): XrAnchor[]
```

List of available [XrAnchor](https://api.playcanvas.com/engine/classes/XrAnchor.md)s.

### persistence

```ts
get persistence(): boolean
```

True if Anchors support persistence.

### supported

```ts
get supported(): boolean
```

True if Anchors are supported.

### uuids

```ts
get uuids(): string[] | null
```

Array of UUID strings of persistent anchors, or null if not available.

## Methods

### create

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

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

**Parameters**

- `position` (`XRHitTestResult |` [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Position for an anchor or a hit test result.
- `rotation` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md) `|` [`XrAnchorCreateCallback`](https://api.playcanvas.com/engine/types/XrAnchorCreateCallback.md), optional): Rotation for an anchor or a callback if
  creating from a hit test result.
- `callback` ([`XrAnchorCreateCallback`](https://api.playcanvas.com/engine/types/XrAnchorCreateCallback.md), optional): Callback to fire when anchor was created or
  failed to be created.

**Example**

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

**Example**

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

### forget

```ts
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.
- `callback` ([`XrAnchorForgetCallback`](https://api.playcanvas.com/engine/types/XrAnchorForgetCallback.md), optional): Callback to fire when anchor persistent data
  was removed or error if failed.

**Example**

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

### restore

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

Restore anchor using persistent UUID.

**Parameters**

- `uuid` (`string`): UUID string associated with persistent anchor.
- `callback` ([`XrAnchorCreateCallback`](https://api.playcanvas.com/engine/types/XrAnchorCreateCallback.md), optional): Callback to fire when anchor was created or
  failed to be created.

**Example**

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

**Example**

```ts
// 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

### EVENT_ADD

```ts
static EVENT_ADD: string = 'add'
```

Fired when a new [XrAnchor](https://api.playcanvas.com/engine/classes/XrAnchor.md) is added. The handler is passed the [XrAnchor](https://api.playcanvas.com/engine/classes/XrAnchor.md) that
was added.

**Example**

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

### EVENT_AVAILABLE

```ts
static EVENT_AVAILABLE: string = 'available'
```

Fired when anchors become available.

**Example**

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

### EVENT_DESTROY

```ts
static EVENT_DESTROY: string = 'destroy'
```

Fired when an [XrAnchor](https://api.playcanvas.com/engine/classes/XrAnchor.md) is destroyed. The handler is passed the [XrAnchor](https://api.playcanvas.com/engine/classes/XrAnchor.md) that
was destroyed.

**Example**

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

### EVENT_ERROR

```ts
static EVENT_ERROR: string = 'error'
```

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

**Example**

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

### EVENT_UNAVAILABLE

```ts
static EVENT_UNAVAILABLE: string = 'unavailable'
```

Fired when anchors become unavailable.

**Example**

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

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`