# CameraArm

> Talos next · 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/drone-search/scenes/behaviors/carrier.ts`.

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

/** Moves a kinematic body round `props.path` (world [x, z] points) at `props.speed` m/s, facing where it goes: the
 * stand-in for a boat or a truck the drone launches from, and for the contact it looks for. */
interface Props {
  path: [number, number][]
  speed: number
}

interface State {
  next: number
}

export default {
  init(ctx) {
    ctx.state.next ??= 0
  },
  update(ctx, dt) {
    const path = ctx.props.path
    const goal = path[ctx.state.next % path.length]
    if (goal === undefined) return
    const p = ctx.entity.position
    const to: [number, number, number] = [goal[0], p[1], goal[1]]
    ctx.entity.lookAt(to)
    if (ctx.entity.moveToward(to, ctx.props.speed * dt)) ctx.state.next = (ctx.state.next + 1) % path.length
  },
} satisfies Behavior<State, Props>
```