# CAMERA

> The CAMERA engine component on a table object — three guardrails enforced by the runtime so an added object camera can never take over what players see.

- Source: https://diceytable.com/docs/editor/inspector/camera
- Last verified: 2026-09-19

`CAMERA` is the second of the two **optional Engine components** (`tone="engine"`) an author
can add to a table object — the other is [`LIGHT`](https://diceytable.com/docs/editor/inspector/light). It is
absent by default and only appears once added from **`+ ADD COMPONENT`**.

Source: `CAMERA_FIELDS` and the `camera` descriptor in
`packages/shared/src/componentInspector.ts`; schema in `packages/shared/src/objectComponents.ts`
(`objectCameraComponentPropsSchema`); guardrails enforced in
`TabletopRuntime.applyObjectComponents`.

## Why this component ships with guardrails, stated once

PlayCanvas renders through **every enabled camera**, and the highest-priority one wins. An
author who adds a `camera` component without understanding that could put every player at the
table inside their prop with no in-band way back. Three guardrails close that hole, enforced
by the runtime rather than left as advice:

1. **Added disabled.** `enabled` defaults to `false` for `camera` — every other component
   defaults to `true`. Turning a camera on is a second, explicit action.
2. **Priority can never outrank the table camera.** The table camera is priority `0`; the
   runtime clamps an authored `priority` to `Math.max(1, Math.min(31, …))` before applying
   it, so an object camera is pinned strictly below the one players actually play through.
3. **At most one object camera enabled at a time.** If a second camera's `enabled` flips true
   while another object's camera is already enabled, the runtime forces the newcomer's
   *effective* `enabled` to `false` (the authored value is left alone) and logs
   `"<label>'s camera stays off — another entity's camera is already enabled."` once per
   object, rather than letting the two fight non-deterministically.

## Fields

> **Lengths are shown in your chosen unit.** Every range and default below is quoted in
> **world units (feet)**, which is how the file stores them. The field itself shows and reads
> whichever unit you picked in [File ▸ Preferences](https://diceytable.com/docs/editor/interface/preferences) — so a
> `Range` of `8` reads as `2438.4` with millimetres selected, and is still `8` in the file.

| Field | Type | Range / units | Default | Runtime effect | Replicates |
|---|---|---|---|---|---|
| **Projection** | select | `Perspective`, `Orthographic` | `perspective` | Chooses between FOV-based and fixed-volume projection. | Yes — `TableObjectState.components[]` (`opaqueEq`) |
| **Field of view** | slider | 1–179°, step 1 | `45` | Only shown for `Perspective`. Vertical FOV. | Yes |
| **Ortho height** | number | 0.01–1000, step 0.5 | `4` | Only shown for `Orthographic`. Half-height of the orthographic view volume. | Yes |
| **Clear color** | color | hex `#rrggbb` | `#0d0d10` | The color drawn where nothing else is rendered, when this camera is the active view. | Yes |
| **Near clip** | number | 0.001–100, step 0.01 | `0.1` | Nearest visible distance. | Yes |
| **Far clip** | number | 0.1–10,000, step 1 | `1000` | Farthest visible distance. | Yes |
| **Priority** | number | 0–31, step 1 (int) | `0` | Authored value; **the runtime clamps the effective priority to 1–31** so it can never reach the table camera's `0`. Chooses between object cameras when more than one exists — it cannot promote one above what players actually play through. The Inspector's own hint states this plainly. | Yes |

`Field of view` is visible only when `Projection` is `Perspective`; `Ortho height` only when
it is `Orthographic` — the same `visibleWhen` mechanism `LIGHT` uses.

## The component header

Same enable checkbox + kebab menu (Disable/Enable, Reset to default, Remove component…) every
optional component gets — full detail on `inspector/add-component.md` (not this page). The
one `CAMERA`-specific nuance: **enabling it here is the second of the "added disabled" flow**
above — adding the component and enabling it are two separate clicks by design.

## See also

- [light.md](https://diceytable.com/docs/editor/inspector/light) — the other optional component, and the sibling
  this page's `visibleWhen` pattern is shared with.
- [The scene model](https://diceytable.com/docs/editor/concepts/scene-model#optional-components-light-and-camera) —
  why `camera` is optional rather than intrinsic.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `ObjectComponentState`, the `camera` variant's replicated props.
