camera
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-clipcamera-fov-overrides-scenecamera-hides-everythingcamera-layers-invalidcamera-probe-wider-than-bodycamera-projection-invalidcamera-rig-invaliddangling-targetfeel/camera-clipfeel/camera-closefeel/camera-collapsedfeel/camera-occludedfeel/camera-wall-collapsefeel/controls-rotatedfeel/teleport-facing-ignoredlayer-unknownlook-value-not-finitelook-value-out-of-rangephysics.layer-unknownprimary-camerareplay-camera-unknownshots-invalidsplat-view-outsideteleport-heading-ignoredui.describe.model-view-value.tentative
Example
From the contract's tested fixture fixtures/contract/full20/scene.json#cam-overview.
{
"type": "camera",
"kind": "orbit",
"fov": 45,
"distance": 18
}