# CameraParams

> Talos 0.6 · Since 0.6

Settings for {@link CameraHandle.set}.

Every key is optional and keeps its previous value when absent, except `distance`. Any other key is passed through to the rig.

## Signature

```ts
export interface CameraParams {
  /**
   * Vertical field of view in degrees, for every kind. Sticky: it stands until another `set` names
   * one or `follow(null)`. `null` drops it, so the scene camera's `fov` is drawn again.
   */
  fov?: number | null
  /**
   * How far the camera sees, in metres, for every kind. Absent, the scene camera's `far` decides,
   * and failing that `meta.bounds`. A value under one metre is ignored.
   */
  far?: number
  /**
   * `"orthographic"` draws the view as a box instead of a pyramid (a 2D, isometric or top-down game); `fov` is
   * then ignored. `"perspective"` switches back. Absent keeps the scene camera's `projection`. Sticky, like
   * the three lens keys below, until `follow(null)`; each one lies over the scene camera's own value.
   */
  projection?: "perspective" | "orthographic"
  /** Orthographic: half the view's height in world units. Wins over `pixelsPerUnit`. Not above zero: ignored. */
  orthoSize?: number
  /** Orthographic: screen pixels per world unit; with no `orthoSize` from scene or script, sizes the view from the viewport. */
  pixelsPerUnit?: number
  /** Orthographic: round the eye to the pixel grid (1 / `pixelsPerUnit`, else one screen pixel) so pixel art holds still. */
  pixelSnap?: boolean
  /** Boom length in metres, for `third-person` and `orbit`. */
  distance?: number
  /** Yaw in radians about world +Y, measured the way {@link EntityHandle.teleport} measures it. */
  yaw?: number
  /** Pitch in radians; positive looks up. */
  pitch?: number
  /** Radius of the sphere the boom sweeps to keep itself out of geometry. Sticky: omitting it keeps the last value. */
  probeRadius?: number
  /**
   * Metres up world +Y from the follow target to the eye — the eye itself in `first-person`, the
   * pivot the boom swings around in `third-person` and `orbit`.
   *
   * Defaults to 1.65, a standing character measured from the feet, so a character scene is
   * unchanged. `0` means the anchor the script named **is** the eye, which is what a vehicle
   * wants: a car has already authored `driver-eye` and `chase-anchor` at the height it wants,
   * and the default sat an extra standing person on the roof.
   *
   * Sticky, like `probeRadius` and unlike `distance`: omitting it keeps the last value rather
   * than returning to the default. A value that is not finite is ignored.
   */
  eyeHeight?: number
  /** `"fixed"` only: a world `[x, y, z]` the rig is bolted to — makes it live without a follow target. */
  position?: [number, number, number]
  /** `"fixed"` only: `[x, y, z]` from the followed entity (the isometric follow-cam). The alternative to `position`. */
  offset?: [number, number, number]
  /** `"fixed"` only: a world point to look at; without one it looks at the followed entity, else along yaw/pitch. */
  target?: [number, number, number]
  /**
   * Seconds without a steer before the rig swings back behind the followed entity — the way it visibly faces:
   * a character, or a car whose chase camera comes back round after the player stops turning the view. A `set`
   * that writes a different `yaw` is a steer. `null` or a negative number turns it off. Sticky.
   */
  recenterDelay?: number | null
  /** How fast the recenter swing turns, degrees per second; default 90. Sticky. */
  recenterSpeedDeg?: number
  /**
   * Seconds of the followed entity's horizontal travel the followed point leads by, so more of the way ahead is
   * on screen: 0.3 at 10 m/s is 3 m ahead. 0 (the default) is off. Never applied to the first-person eye. Sticky.
   */
  lookAhead?: number
  /** Longest the look-ahead lead may be, metres; default 2. Sticky. */
  lookAheadMax?: number
  /** How quickly the lead settles on a new direction, per second; default 3. Sticky. */
  lookAheadRate?: number
  /**
   * `third-person` and `orbit`: arm length, metres, below which the followed character starts to fade (a
   * screen-door dither), so an arm a wall has collapsed shows the world rather than the inside of the character.
   * Default 1; 0 turns fading off. Sticky, like every wall-handling key below.
   */
  fadeStart?: number
  /** Arm length, metres, at which the character is gone entirely. Default 0.45. */
  fadeFull?: number
  /** How quickly the fade follows the arm, per second. Default 12. */
  fadeRate?: number
  /**
   * How quickly the arm grows back once a wall clears, per second. Default 5; 0 snaps back. The arm always
   * shortens at once: easing into a wall is clipping through it.
   */
  recoverRate?: number
  /** Metres to shift the pivot sideways, towards the side with room, while a wall has the arm short. Default 0 (off). */
  shoulder?: number
  /**
   * Swing the yaw gently away from a wall that is shortening the arm, after `avoidDelay` seconds without a steer.
   * Default false: in a game with camera-relative controls, a camera that turns by itself also turns the player's
   * "forward", and a run along a wall curves off it.
   */
  avoidWalls?: boolean
  /** Fastest the avoid swing turns, degrees per second. Default 60. */
  avoidSpeedDeg?: number
  /** How far either side the avoid feelers look, degrees. Default 30. */
  avoidAngleDeg?: number
  /** Seconds after a steer before the avoid swing may act. Default 0.5. */
  avoidDelay?: number
  [key: string]: unknown
}
```

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

## Members

| Member | Signature | Description |
|---|---|---|
| `fov` | `fov?: number \| null` | Vertical field of view in degrees, for every kind. Sticky: it stands until another `set` names one or `follow(null)`. `null` drops it, so the scene camera's `fov` is drawn again. |
| `far` | `far?: number` | How far the camera sees, in metres, for every kind. Absent, the scene camera's `far` decides, and failing that `meta.bounds`. A value under one metre is ignored. |
| `projection` | `projection?: "perspective" \| "orthographic"` | `"orthographic"` draws the view as a box instead of a pyramid (a 2D, isometric or top-down game); `fov` is then ignored. `"perspective"` switches back. Absent keeps the scene camera's `projection`. Sticky, like the three lens keys below, until `follow(null)`; each one lies over the scene camera's own value. |
| `orthoSize` | `orthoSize?: number` | Orthographic: half the view's height in world units. Wins over `pixelsPerUnit`. Not above zero: ignored. |
| `pixelsPerUnit` | `pixelsPerUnit?: number` | Orthographic: screen pixels per world unit; with no `orthoSize` from scene or script, sizes the view from the viewport. |
| `pixelSnap` | `pixelSnap?: boolean` | Orthographic: round the eye to the pixel grid (1 / `pixelsPerUnit`, else one screen pixel) so pixel art holds still. |
| `distance` | `distance?: number` | Boom length in metres, for `third-person` and `orbit`. |
| `yaw` | `yaw?: number` | Yaw in radians about world +Y, measured the way {@link EntityHandle.teleport} measures it. |
| `pitch` | `pitch?: number` | Pitch in radians; positive looks up. |
| `probeRadius` | `probeRadius?: number` | Radius of the sphere the boom sweeps to keep itself out of geometry. Sticky: omitting it keeps the last value. |
| `eyeHeight` | `eyeHeight?: number` | Metres up world +Y from the follow target to the eye — the eye itself in `first-person`, the pivot the boom swings around in `third-person` and `orbit`. Defaults to 1.65, a standing character measured from the feet, so a character scene is unchanged. `0` means the anchor the script named **is** the eye, which is what a vehicle wants: a car has already authored `driver-eye` and `chase-anchor` at the height it wants, and the default sat an extra standing person on the roof. Sticky, like `probeRadius` and unlike `distance`: omitting it keeps the last value rather than returning to the default. A value that is not finite is ignored. |
| `position` | `position?: [number, number, number]` | `"fixed"` only: a world `[x, y, z]` the rig is bolted to — makes it live without a follow target. |
| `offset` | `offset?: [number, number, number]` | `"fixed"` only: `[x, y, z]` from the followed entity (the isometric follow-cam). The alternative to `position`. |
| `target` | `target?: [number, number, number]` | `"fixed"` only: a world point to look at; without one it looks at the followed entity, else along yaw/pitch. |
| `recenterDelay` | `recenterDelay?: number \| null` | Seconds without a steer before the rig swings back behind the followed entity — the way it visibly faces: a character, or a car whose chase camera comes back round after the player stops turning the view. A `set` that writes a different `yaw` is a steer. `null` or a negative number turns it off. Sticky. |
| `recenterSpeedDeg` | `recenterSpeedDeg?: number` | How fast the recenter swing turns, degrees per second; default 90. Sticky. |
| `lookAhead` | `lookAhead?: number` | Seconds of the followed entity's horizontal travel the followed point leads by, so more of the way ahead is on screen: 0.3 at 10 m/s is 3 m ahead. 0 (the default) is off. Never applied to the first-person eye. Sticky. |
| `lookAheadMax` | `lookAheadMax?: number` | Longest the look-ahead lead may be, metres; default 2. Sticky. |
| `lookAheadRate` | `lookAheadRate?: number` | How quickly the lead settles on a new direction, per second; default 3. Sticky. |
| `fadeStart` | `fadeStart?: number` | `third-person` and `orbit`: arm length, metres, below which the followed character starts to fade (a screen-door dither), so an arm a wall has collapsed shows the world rather than the inside of the character. Default 1; 0 turns fading off. Sticky, like every wall-handling key below. |
| `fadeFull` | `fadeFull?: number` | Arm length, metres, at which the character is gone entirely. Default 0.45. |
| `fadeRate` | `fadeRate?: number` | How quickly the fade follows the arm, per second. Default 12. |
| `recoverRate` | `recoverRate?: number` | How quickly the arm grows back once a wall clears, per second. Default 5; 0 snaps back. The arm always shortens at once: easing into a wall is clipping through it. |
| `shoulder` | `shoulder?: number` | Metres to shift the pivot sideways, towards the side with room, while a wall has the arm short. Default 0 (off). |
| `avoidWalls` | `avoidWalls?: boolean` | Swing the yaw gently away from a wall that is shortening the arm, after `avoidDelay` seconds without a steer. Default false: in a game with camera-relative controls, a camera that turns by itself also turns the player's "forward", and a run along a wall curves off it. |
| `avoidSpeedDeg` | `avoidSpeedDeg?: number` | Fastest the avoid swing turns, degrees per second. Default 60. |
| `avoidAngleDeg` | `avoidAngleDeg?: number` | How far either side the avoid feelers look, degrees. Default 30. |
| `avoidDelay` | `avoidDelay?: number` | Seconds after a steer before the avoid swing may act. Default 0.5. |

## Example

The tested fixture `fixtures/host/door.ts`.

```ts
import type { Behavior } from "@argus/api"
// docs/API.md, "Joints": a door on a hinge that swings open while the player is near and closes
// behind them. Typechecked by packages/api's tests.
export default {
  update(ctx) {
    const player = ctx.world.find("player")
    const near = player !== null && ctx.entity.distanceTo(player) < 2
    ctx.joint?.setMotor(near ? Math.PI / 2 : 0, { mode: "position", maxForce: 200 })
  },
} satisfies Behavior
```