# camera

> Talos next · Since 0.6; changed in next

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, every sprite's and every tilemap layer's to the drawn view's pixel grid before drawing, so pixel art does not shimmer as the camera moves. |
| `referenceResolution` | `unknown[]` | no |  |  | Orthographic only: `[width, height]` in pixels of the reference view the view's size is measured in. Absent: 1920x1080. Both above zero (`camera-projection-invalid`). With `pixelPerfect` this is the art resolution the scene is drawn at, so a 320x180 pixel game says `[320, 180]` with `pixelsPerUnit` set to its art pixels per world unit. Single-view only: a split-screen layout measures each cell of the 1920x1080 reference. |
| `pixelPerfect` | `boolean` | no |  |  | Orthographic only, default false: draw the scene at the `referenceResolution` (art) size, then scale it up by the largest whole number that fits the window with nearest filtering; the rest of the window is black letterbox bars. In a window smaller than the art the image is scaled down to fit instead. Combine with `pixelSnap` so sprites and tiles land on the art grid. Ignored by a perspective camera and by split-screen. |
| `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`, `texture` | "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). "texture" is drawn into a texture materials name, described by `texture` (a mirror, a monitor). |
| `sensor` | `CameraSensor` | no |  |  | A thermal look over this camera's view (`output: "viewport"` only). Absent: drawn as it is, at no cost. |
| `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. |
| `texture` | `CameraTexture` | no |  |  | What an `output: "texture"` camera draws into: its size, how often, mirrored or not, and how near the screen camera must be. Required for that output and only for it. A material shows it by naming `"camera:<this entity's id>"` as a texture (docs/RENDERING.md, Camera textures). Drawn by the standard renderer (no GI or reflections), HD or not. |
| `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.camera-texture-missing`
- `render.hd.black_frame`
- `replay-camera-unknown`
- `shots-invalid`
- `splat-view-outside`
- `teleport-heading-ignored`
- `terrain/look-far-rock-off`
- `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
}
```