# Hit

> Talos next · Since 0.6; changed in 0.7

Result of a raycast or shape cast.

A cast that hits nothing answers `null`, never `undefined`.

## Signature

```ts
export interface Hit {
  /** The entity whose collider was hit. */
  entity: EntityHandle
  /** Where the cast met it, world space, metres. */
  point: Vec3
  /** The surface normal at `point`. */
  normal: Vec3
  /** From the ray's `from` (or the shape's start) to the hit, in metres: `dir` is normalised first, so this is a length, not a multiple of `dir`. */
  distance: number
  /** Present only when the hit was on an instanced mesh: the stable id of the instance hit (see {@link Instances}). Absent for every other hit. */
  instance?: number
}
```

Import: `import type { Hit } from "@argus/api"`

## Members

| Member | Signature | Description |
|---|---|---|
| `entity` | `entity: EntityHandle` | The entity whose collider was hit. |
| `point` | `point: Vec3` | Where the cast met it, world space, metres. |
| `normal` | `normal: Vec3` | The surface normal at `point`. |
| `distance` | `distance: number` | From the ray's `from` (or the shape's start) to the hit, in metres: `dir` is normalised first, so this is a length, not a multiple of `dir`. |
| `instance` | `instance?: number` | Present only when the hit was on an instanced mesh: the stable id of the instance hit (see {@link Instances}). Absent for every other hit. |

## Example

The tested fixture `fixtures/recipes/collectible-and-goal/scenes/behaviors/collectible.ts`.

```ts
import type { Behavior } from "@argus/api"

/**
 * A coin the player collects by walking into it.
 *
 * It says so once, as `collected`, and leaves the world. Counting is somebody else's job —
 * `goal-exit.ts` — so a coin never needs to know how many there are.
 *
 * The contact is `onTrigger`, which needs three things in the scene: a collider with
 * `isTrigger: true` (the volume), a `trigger` component (what fires), and a body on the player —
 * the character controller's capsule is one.
 */
interface State {
  collected: boolean
}

interface Props {
  /** Tag the toucher must carry. Default `player`. */
  playerTag?: string
}

export default {
  init(ctx) {
    if (typeof ctx.state.collected !== "boolean") ctx.state.collected = false
  },

  onTrigger(ctx, trigger) {
    if (ctx.state.collected || !trigger.entering) return
    if (!trigger.other.hasTag(ctx.props.playerTag ?? "player")) return
    ctx.state.collected = true
    // The `goal` component on this coin has the same id, so the playtester and the HUD agree.
    ctx.events.emit("collected", { goal: ctx.entity.id })
    // Last: after `despawn` every member of this entity's handles throws.
    ctx.entity.despawn()
  },
} satisfies Behavior<State, Props>
```