# camera

> Talos 0.7 · Since 0.6

Use it in a scene entity's `components` list as `{ "type": "camera", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `kind` | `CameraKind` | yes |  | `first-person`, `third-person`, `fixed`, `orbit` |  |
| `fov` | `number` | yes |  |  |  |
| `primary` | `boolean` | no |  |  |  |
| `target` | `string` | no |  |  |  |
| `distance` | `number` | no |  |  |  |
| `far` | `number` | no |  |  |  |
| `projection` | `CameraProjection` | no |  | `perspective`, `orthographic` | "perspective" (the default) or "orthographic": parallel lines stay parallel and nothing shrinks with distance, the camera for a 2D, isometric or top-down game. Orthographic ignores `fov`. |
| `orthoSize` | `number` | no |  |  | Orthographic only: half the view's height in world units (metres); the width follows the aspect. Above zero. Absent: derived from `pixelsPerUnit` (viewport height / (2 * pixelsPerUnit)), else 5. |
| `pixelsPerUnit` | `number` | no |  |  | Orthographic only: screen pixels per world unit, above zero. With no `orthoSize`, sizes the view so one sprite texel at the same pixelsPerMetre is one screen pixel. |
| `pixelSnap` | `boolean` | no |  |  | Orthographic only, default false: round the camera's position to the pixel grid (1 / pixelsPerUnit, else one screen pixel) before drawing, so pixel art does not shimmer as the camera moves. |
| `priority` | `number` | no | `0` |  | Screen cameras compete: the highest priority is the view, ties going to `primary`, then the one activated most recently, then scene order. Default 0. A script rig (ctx.camera.set/follow) beats every scene camera unless it passes a priority. |
| `layers` | `string[]` | no |  |  | Draw only entities on these layers (names from the project's `layers`). Not with `hideLayers`, and not empty. Absent, with no `hideLayers`: every layer. |
| `hideLayers` | `string[]` | no |  |  | Draw every layer except these, and their shadows and reflections: `["viewmodel"]`. Not with `layers`, and not empty. |
| `output` | `CameraOutput` | no |  | `screen`, `overlay`, `viewport` | "screen" (the default) competes by `priority` for the window. "overlay" is drawn over the screen view every frame with depth cleared (a first-person viewmodel). "viewport" is drawn into the `viewport` rectangle (a minimap, split screen, picture in picture). |
| `viewport` | `unknown[]` | no |  |  | [x, y, width, height] as fractions 0..1 of the window from its top-left corner: where an `output: "viewport"` camera draws. Required for that output and only for it; inside the window, with width and height above zero. |
| `order` | `number` | no | `0` |  | Draw order among overlay and viewport cameras, lowest first. Default 0. |
| `blendIn` | `CameraBlend` | no |  |  | How the view blends to this camera when it becomes the screen view. Absent: a cut. |
| `rig` | `CameraRigSettings` | no |  |  | Opt-in: present (even `{}`) means the engine drives this camera as a rig of its `kind`, following `target` at `distance`. Absent: the entity's transform is the camera. Write `"rig": {}` for a camera that should follow its target. |

## Rules that can refuse it

- `camera-clip`
- `camera-fov-overrides-scene`
- `camera-hides-everything`
- `camera-layers-invalid`
- `camera-overlay-not-drawn`
- `camera-point-invalid`
- `camera-probe-wider-than-body`
- `camera-projection-invalid`
- `camera-rig-invalid`
- `camera-view-unknown`
- `dangling-target`
- `feel/camera-clip`
- `feel/camera-close`
- `feel/camera-collapsed`
- `feel/camera-occluded`
- `feel/camera-target-hidden`
- `feel/camera-wall-collapse`
- `feel/controls-rotated`
- `feel/player-fell-off`
- `feel/response-dead`
- `feel/response-slow`
- `feel/teleport-facing-ignored`
- `layer-unknown`
- `look-value-not-finite`
- `look-value-out-of-range`
- `physics.layer-unknown`
- `primary-camera`
- `render.hd.black_frame`
- `replay-camera-unknown`
- `shots-invalid`
- `splat-view-outside`
- `teleport-heading-ignored`
- `ui.describe.model-view-value.tentative`

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#cam-overview`.

```json
{
  "type": "camera",
  "kind": "orbit",
  "fov": 45,
  "distance": 18
}
```