# XrHitTest

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

Source: https://github.com/playcanvas/engine/blob/dfcc50fbbfba2388843041a875ec0ef5d1a586c5/src/framework/xr/xr-hit-test.js#L28

The Hit Test interface allows initiating hit testing against real-world geometry from various
sources: the view, input sources, or an arbitrary ray in space. Results reflect the underlying
AR system's understanding of the real world.

## Properties

### sources

```ts
sources: XrHitTestSource[] = []
```

List of active [XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md).

## Accessors

### available

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

True if Hit Test is available. This information is available only when the session has started.

### supported

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

True if AR Hit Test is supported.

## Methods

### start

```ts
start(options?: object): void
```

Attempts to start hit test with provided reference space.

**Parameters**

- `options` (`object`, optional, default `{}`): Optional object for passing arguments.
    - `options.callback` ([`XrHitTestStartCallback`](https://api.playcanvas.com/engine/types/XrHitTestStartCallback.md), optional): Optional callback function called once
      hit test source is created or failed.
    - `options.entityTypes` (`string[]`, optional): Optional list of underlying entity types against
      which hit tests will be performed. Defaults to [ [XRTRACKABLE_PLANE](https://api.playcanvas.com/engine/variables/XRTRACKABLE_PLANE.md) ]. Can be any
      combination of the following:

      - [XRTRACKABLE_POINT](https://api.playcanvas.com/engine/variables/XRTRACKABLE_POINT.md): Point - indicates that the hit test results will be computed
      based on the feature points detected by the underlying Augmented Reality system.
      - [XRTRACKABLE_PLANE](https://api.playcanvas.com/engine/variables/XRTRACKABLE_PLANE.md): Plane - indicates that the hit test results will be computed
      based on the planes detected by the underlying Augmented Reality system.
      - [XRTRACKABLE_MESH](https://api.playcanvas.com/engine/variables/XRTRACKABLE_MESH.md): Mesh - indicates that the hit test results will be computed
      based on the meshes detected by the underlying Augmented Reality system.
    - `options.offsetRay` ([`Ray`](https://api.playcanvas.com/engine/classes/Ray.md), optional): Optional ray by which
      hit test ray can be offset.
    - `options.profile` (`string`, optional): if hit test source meant to match input source instead
      of reference space, then name of profile of the [XrInputSource](https://api.playcanvas.com/engine/classes/XrInputSource.md) should be provided.
    - `options.spaceType` (`string`, optional): Reference space type. Defaults to
      [XRSPACE_VIEWER](https://api.playcanvas.com/engine/variables/XRSPACE_VIEWER.md). Can be one of the following:

      - [XRSPACE_VIEWER](https://api.playcanvas.com/engine/variables/XRSPACE_VIEWER.md): Viewer - hit test will be facing relative to viewers space.
      - [XRSPACE_LOCAL](https://api.playcanvas.com/engine/variables/XRSPACE_LOCAL.md): Local - represents a tracking space with a native origin near the
      viewer at the time of creation.
      - [XRSPACE_LOCALFLOOR](https://api.playcanvas.com/engine/variables/XRSPACE_LOCALFLOOR.md): Local Floor - represents a tracking space with a native origin
      at the floor in a safe position for the user to stand. The y axis equals 0 at floor level.
      Floor level value might be estimated by the underlying platform.
      - [XRSPACE_BOUNDEDFLOOR](https://api.playcanvas.com/engine/variables/XRSPACE_BOUNDEDFLOOR.md): Bounded Floor - represents a tracking space with its native
      origin at the floor, where the user is expected to move within a pre-established boundary.
      - [XRSPACE_UNBOUNDED](https://api.playcanvas.com/engine/variables/XRSPACE_UNBOUNDED.md): Unbounded - represents a tracking space where the user is
      expected to move freely around their environment, potentially long distances from their
      starting point.

**Example**

```ts
// start hit testing from viewer position facing forwards
app.xr.hitTest.start({
    spaceType: XRSPACE_VIEWER,
    callback: (err, hitTestSource) => {
        if (err) return;
        hitTestSource.on('result', (position, rotation) => {
            // position and rotation of hit test result
        });
    }
});
```

**Example**

```ts
// start hit testing using an arbitrary ray
const ray = new Ray(new Vec3(0, 0, 0), new Vec3(0, -1, 0));
app.xr.hitTest.start({
    spaceType: XRSPACE_LOCAL,
    offsetRay: ray,
    callback: (err, hitTestSource) => {
        // hit test source that will sample real world geometry straight down
        // from the position where AR session started
    }
});
```

**Example**

```ts
// start hit testing for touch screen taps
app.xr.hitTest.start({
    profile: 'generic-touchscreen',
    callback: (err, hitTestSource) => {
        if (err) return;
        hitTestSource.on('result', (position, rotation, inputSource) => {
            // position and rotation of hit test result
            // that will be created from touch on mobile devices
        });
    }
});
```

## Events

### EVENT_ADD

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

Fired when new [XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md) is added to the list. The handler is passed the
[XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md) object that has been added.

**Example**

```ts
app.xr.hitTest.on('add', (hitTestSource) => {
    // new hit test source is added
});
```

### EVENT_AVAILABLE

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

Fired when hit test becomes available.

**Example**

```ts
app.xr.hitTest.on('available', () => {
    console.log('Hit Testing is available');
});
```

### EVENT_ERROR

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

Fired when failed create hit test source. The handler is passed the Error object.

**Example**

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

### EVENT_REMOVE

```ts
static EVENT_REMOVE: string = 'remove'
```

Fired when [XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md) is removed to the list. The handler is passed the
[XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md) object that has been removed.

**Example**

```ts
app.xr.hitTest.on('remove', (hitTestSource) => {
    // hit test source is removed
});
```

### EVENT_RESULT

```ts
static EVENT_RESULT: string = 'result'
```

Fired when hit test source receives new results. It provides transform information that
tries to match real world picked geometry. The handler is passed the [XrHitTestSource](https://api.playcanvas.com/engine/classes/XrHitTestSource.md)
that produced the hit result, the [Vec3](https://api.playcanvas.com/engine/classes/Vec3.md) position, the [Quat](https://api.playcanvas.com/engine/classes/Quat.md) rotation and the
[XrInputSource](https://api.playcanvas.com/engine/classes/XrInputSource.md) (if it is a transient hit test source).

**Example**

```ts
app.xr.hitTest.on('result', (hitTestSource, position, rotation, inputSource) => {
    target.setPosition(position);
    target.setRotation(rotation);
});
```

### EVENT_UNAVAILABLE

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

Fired when hit test becomes unavailable.

**Example**

```ts
app.xr.hitTest.on('unavailable', () => {
    console.log('Hit Testing is 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`