Camera

Camera gives you full control over the camera in a World scene. Drop it as a child of World to replace the default camera and controls with your own configuration.

When World detects a <Camera> child, it automatically skips its built-in camera and orbit controls — no extra flags needed.

tsx

import { Camera } from "@carverjs/core/components";

Quick Start #

Perspective camera with orbit controls #

tsx

<World>
  <Camera type="perspective" controls="orbit" />
  <Actor type="primitive" shape="box" color="red" />
</World>

Orthographic camera (2D-style) #

tsx

<World mode="2d">
  <Camera type="orthographic" />
  <Actor type="sprite" src="/player.png" />
</World>

Follow a target #

tsx

const playerRef = useRef<Group>(null);

<World>
  <Camera
    type="perspective"
    follow={{
      target: playerRef,
      offset: [0, 5, 10],
      smoothing: 0.1,
    }}
  />
  <Actor ref={playerRef} type="model" src="/player.glb" />
</World>

Get the imperative API #

tsx

<Camera
  type="perspective"
  controls="orbit"
  onReady={(api) => {
    // api.shake(), api.moveTo(), api.lookAt()
  }}
/>

Props Reference #

Prop	Type	Default	Description
`type`	`"perspective" \| "orthographic"`	`"perspective"`	Camera projection type
`controls`	`"orbit" \| "map" \| "pointerlock" \| "none"`	`"none"`	Controls mode
`follow`	`CameraFollowConfig`	—	Follow configuration. Omit for a static camera
`perspectiveProps`	`PerspectiveCameraProps`	—	Overrides for the PerspectiveCamera (when `type="perspective"`)
`orthographicProps`	`OrthographicCameraProps`	—	Overrides for the OrthographicCamera (when `type="orthographic"`)
`orbitControlsProps`	`OrbitControlsProps`	—	Overrides for OrbitControls (when `controls="orbit"`)
`mapControlsProps`	`MapControlsProps`	—	Overrides for MapControls (when `controls="map"`)
`pointerLockControlsProps`	`PointerLockControlsProps`	—	Overrides for PointerLockControls (when `controls="pointerlock"`)
`onReady`	`(api: UseCameraReturn) => void`	—	Callback receiving the imperative camera API

Built-in Defaults #

Property	Perspective	Orthographic
Position	`[0, 5, 10]`	`[0, 0, 100]`
FOV / Zoom	`75`	`50`
Near	`0.1`	`0.1`
Far	`1000`	`1000`

`CameraFollowConfig` #

Field	Type	Default	Description
`target`	`RefObject<Object3D>`	—	Required. Ref to the Object3D to follow
`offset`	`[x, y, z]`	`[0, 5, 10]`	Position offset from the target
`smoothing`	`number`	`0.1`	Lerp factor (0–1). Lower = smoother, higher = snappier
`lookAt`	`boolean`	`true`	Whether the camera looks at the target
`lookAtOffset`	`[x, y, z]`	`[0, 0, 0]`	Offset for the look-at point

Controls #

Mode	Description
`"none"`	No controls — camera is static or driven by `follow` / imperative API
`"orbit"`	Click-drag to orbit around a point, scroll to zoom
`"map"`	Pan and zoom controls suited for top-down views
`"pointerlock"`	First-person style — locks the cursor and rotates on mouse move

Ref #

Camera forwards a ref to the underlying Three.js camera object:

tsx

const cameraRef = useRef<PerspectiveCamera>(null);
<Camera ref={cameraRef} type="perspective" />

Type Definitions #

See Types for CameraType, CameraControlsType, CameraFollowConfig, PerspectiveCameraProps, OrthographicCameraProps, MapControlsProps, PointerLockControlsProps, and UseCameraReturn.