# CameraArm

> Talos 0.7 · Since 0.6

{@link CameraHandle.arm}: what the engine rig's boom is doing this frame.

## Signature

```ts
export interface CameraArm {
  /** True while a `third-person` or `orbit` rig resolved its arm this frame. Every number is 0 when false. */
  readonly active: boolean
  /** The length the rig asked for, metres: the `distance` of the last `set`. */
  readonly desired: number
  /** The length it has, pivot to eye, after collision and the recovery ease. */
  readonly length: number
  /** Shorter than the arm's minimum (0.5 m): the eye is in or against the character. */
  readonly collapsed: boolean
  /** Geometry is shortening the arm. */
  readonly blocked: boolean
  /** What is shortening it, or null. */
  readonly blocker: EntityHandle | null
  /** 0..1, how far the followed character is faded away (see `fadeStart`). */
  readonly fade: number
  /** Radius of the sphere the boom sweeps: `probeRadius`, widened so the near plane never enters a wall. */
  readonly probeRadius: number
}
```

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

## Members

| Member | Signature | Description |
|---|---|---|
| `active` | `readonly active: boolean` | True while a `third-person` or `orbit` rig resolved its arm this frame. Every number is 0 when false. |
| `desired` | `readonly desired: number` | The length the rig asked for, metres: the `distance` of the last `set`. |
| `length` | `readonly length: number` | The length it has, pivot to eye, after collision and the recovery ease. |
| `collapsed` | `readonly collapsed: boolean` | Shorter than the arm's minimum (0.5 m): the eye is in or against the character. |
| `blocked` | `readonly blocked: boolean` | Geometry is shortening the arm. |
| `blocker` | `readonly blocker: EntityHandle \| null` | What is shortening it, or null. |
| `fade` | `readonly fade: number` | 0..1, how far the followed character is faded away (see `fadeStart`). |
| `probeRadius` | `readonly probeRadius: number` | Radius of the sphere the boom sweeps: `probeRadius`, widened so the near plane never enters a wall. |

## Example

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

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

/**
 * The exit, which the player wins at once every coin is collected.
 *
 * It counts the `collected` events, and once `required` are in, the player walking into it wins.
 * Entering it early does nothing, so the order the coins are taken in is free.
 *
 * `goal-reached` is the event the built-in `hud` behaviour marks a goal done on. The scene's
 * `goal` components (coin-1, coin-2, exit, in that order) are what `critic.play` walks to.
 */
interface State {
  collected: string[]
  won: boolean
}

interface Props {
  /** Coins needed before the exit counts. Default 1. */
  required?: number
  /** String key shown as the objective on a win. Default `exit.won`. */
  wonKey?: string
  /** Tag the player carries. Default `player`. */
  playerTag?: string
}

export default {
  init(ctx) {
    if (!Array.isArray(ctx.state.collected)) ctx.state.collected = []
    if (typeof ctx.state.won !== "boolean") ctx.state.won = false
  },

  onEvent(ctx, event) {
    if (event.name !== "collected") return
    const goal = (event.data as { goal?: string } | null)?.goal
    if (typeof goal !== "string" || ctx.state.collected.includes(goal)) return
    ctx.state.collected.push(goal)
    ctx.events.emit("goal-reached", { goal })
  },

  onTrigger(ctx, trigger) {
    if (ctx.state.won || !trigger.entering) return
    if (!trigger.other.hasTag(ctx.props.playerTag ?? "player")) return
    if (ctx.state.collected.length < (ctx.props.required ?? 1)) return
    ctx.state.won = true
    ctx.events.emit("goal-reached", { goal: ctx.entity.id })
    // A HUD text value is a key into `meta.strings`, not the text itself.
    ctx.hud.objective(ctx.props.wonKey ?? "exit.won")
  },
} satisfies Behavior<State, Props>
```