Talos Engine
Start a pilot
Menu
Talos docs

camera

Since 0.6Changed in next
Plain text

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

Fields

FieldTypeRequiredDefaultAllowed valuesDescription
kindCameraKindyesfirst-person, third-person, fixed, orbit
fovnumberyes
primarybooleanno
targetstringno
distancenumberno
farnumberno
projectionCameraProjectionnoperspective, 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.
orthoSizenumbernoOrthographic 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.
pixelsPerUnitnumbernoOrthographic 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.
pixelSnapbooleannoOrthographic 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.
referenceResolutionunknown[]noOrthographic 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.
pixelPerfectbooleannoOrthographic 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.
prioritynumberno0Screen 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.
layersstring[]noDraw only entities on these layers (names from the project's layers). Not with hideLayers, and not empty. Absent, with no hideLayers: every layer.
hideLayersstring[]noDraw every layer except these, and their shadows and reflections: ["viewmodel"]. Not with layers, and not empty.
outputCameraOutputnoscreen, 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).
sensorCameraSensornoA thermal look over this camera's view (output: "viewport" only). Absent: drawn as it is, at no cost.
viewportunknown[]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.
textureCameraTexturenoWhat 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.
ordernumberno0Draw order among overlay and viewport cameras, lowest first. Default 0.
blendInCameraBlendnoHow the view blends to this camera when it becomes the screen view. Absent: a cut.
rigCameraRigSettingsnoOpt-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

Example

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

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