# XrAnchor

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-anchor.js#L34

An anchor keeps track of a position and rotation that is fixed relative to the real world. This
allows the application to adjust the location of virtual objects placed in the scene in a way
that helps with maintaining the illusion that the placed objects are really present in the
user's environment.

## Accessors

### persistent

```ts
get persistent(): boolean
```

Gets whether an anchor is persistent.

### uuid

```ts
get uuid(): string | null
```

Gets the UUID string of a persisted anchor or null if the anchor is not persisted.

## Methods

### destroy

```ts
destroy(): void
```

Destroy an anchor.

### forget

```ts
forget(callback?: XrAnchorForgetCallback): void
```

Removes the persistent UUID of an anchor from the underlying system. This effectively makes
the anchor non-persistent, so it will not be restored in future WebXR sessions.

**Parameters**

- `callback` ([`XrAnchorForgetCallback`](https://api.playcanvas.com/engine/types/XrAnchorForgetCallback.md), optional): Optional callback function to be called when
  the anchor has been forgotten or if an error occurs.

**Example**

```ts
// Forget the anchor and log the result or error
anchor.forget((err) => {
    if (err) {
        console.error('Failed to forget anchor:', err);
    } else {
        console.log('Anchor has been forgotten');
    }
});
```

### getPosition

```ts
getPosition(): Vec3
```

Get the world space position of an anchor.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The world space position of an anchor.

### getRotation

```ts
getRotation(): Quat
```

Get the world space rotation of an anchor.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): The world space rotation of an anchor.

### persist

```ts
persist(callback?: XrAnchorPersistCallback): void
```

Persists the anchor between WebXR sessions by generating a universally unique identifier
(UUID) for the anchor. This UUID can be used later to restore the anchor from the underlying
system. Note that the underlying system may have a limit on the number of anchors that can
be persisted per origin.

**Parameters**

- `callback` ([`XrAnchorPersistCallback`](https://api.playcanvas.com/engine/types/XrAnchorPersistCallback.md), optional): Optional callback function to be called when
  the persistent UUID has been generated or if an error occurs.

**Example**

```ts
// Persist the anchor and log the UUID or error
anchor.persist((err, uuid) => {
    if (err) {
        console.error('Failed to persist anchor:', err);
    } else {
        console.log('Anchor persisted with UUID:', uuid);
    }
});
```

## Events

### EVENT_CHANGE

```ts
static EVENT_CHANGE: string = 'change'
```

Fired when an anchor's position and/or rotation is changed.

**Example**

```ts
anchor.on('change', () => {
    // anchor has been updated
    entity.setPosition(anchor.getPosition());
    entity.setRotation(anchor.getRotation());
});
```

### EVENT_DESTROY

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

Fired when an anchor is destroyed.

**Example**

```ts
// once anchor is destroyed
anchor.once('destroy', () => {
    // destroy its related entity
    entity.destroy();
});
```

### EVENT_FORGET

```ts
static EVENT_FORGET: string = 'forget'
```

Fired when an anchor has been forgotten.

**Example**

```ts
anchor.on('forget', () => {
    // anchor has been forgotten
});
```

### EVENT_PERSIST

```ts
static EVENT_PERSIST: string = 'persist'
```

Fired when an anchor has been persisted. The handler is passed the UUID string that can
be used to restore this anchor.

**Example**

```ts
anchor.on('persist', (uuid) => {
    // anchor has been persisted
});
```

## 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`