---
url: /pawn/docs/guide/camera.md
description: >-
  CameraRig: orbit, pan and zoom by pointer, plus focus, follow, fit and reset.
  ChaseCamera: a camera behind a moving entity.
---

# Camera rig

`CameraRig` is a plugin that lets people move the camera: drag to rotate
around a target, right-drag or Shift-drag to pan, wheel or pinch to zoom.
It reads pointers through [`Input`](./input.md) and works with perspective
and orthographic cameras.

```ts
import { CameraRig } from "@pawnjs/core";

const rig = new CameraRig({
  target: { y: 1 },
  maxPolarAngle: 1.4, // stay above the ground
});
engine.use(rig);
```

The rig takes the camera's position at the first frame and orbits the
target from there. It moves the camera of the engine's first view, or of
`view` when given.

| Gesture | Mouse | Touch |
|---|---|---|
| Rotate | drag | one finger |
| Pan | right-drag, middle-drag, Shift/Ctrl/Cmd-drag | two fingers |
| Zoom | wheel | pinch |

A perspective camera zooms by moving closer to the target; an orthographic
camera by changing `camera.zoom`. Moves are damped (`halfLife` is the
half-life in seconds, 0 turns it off) and keep going while the engine's
`timeScale` is 0.

On touch screens the canvas needs a `touch-action` that leaves the gestures
to the page: `none` gives the rig every gesture, `pan-y` keeps vertical
scrolling of the page and gives the rig horizontal drags and pinching.

Drag to orbit, wheel or pinch to zoom, and click a tower to focus it:

```ts
import {
  CameraRig,
  Clickable,
  Engine,
  Hoverable,
  Position,
  Scale,
  Shape,
  View,
} from "@pawnjs/core";
import { AmbientLight, DirectionalLight, PerspectiveCamera } from "three";

export default function camera(canvas: HTMLCanvasElement): Engine {
  // `pan-y` keeps the page scrolling on touch and gives the rig the rest.
  canvas.style.cssText =
    "display:block;width:100%;height:100%;touch-action:pan-y";
  const engine = new Engine({ canvas, seed: 3 });
  const { world, random } = engine;

  engine.scene.add(new AmbientLight(0xffffff, 0.6));
  const sun = new DirectionalLight(0xffffff, 2);
  sun.position.set(6, 10, 4);
  engine.scene.add(sun);

  const view = new PerspectiveCamera(45, 1, 0.1, 200);
  view.position.set(8, 8, 10);
  engine.views.add(new View({ camera: view, background: 0x09090b }));

  const rig = new CameraRig({ maxPolarAngle: 1.35, maxDistance: 30 });
  engine.use(rig);

  world.spawn(
    Shape({ kind: "plane", color: "#27272a" }),
    Scale({ x: 12, y: 1, z: 12 }),
  );
  // A small town of towers; click one to fly to it.
  for (let i = 0; i < 25; i++) {
    const height = random.range(0.5, 3);
    const tower = world.spawn(
      Shape({ kind: "box", color: "#e2e8f0" }),
      Position({
        x: (i % 5) * 2 - 4,
        y: height / 2,
        z: Math.floor(i / 5) * 2 - 4,
      }),
      Scale({ x: 1, y: height, z: 1 }),
      Hoverable({ tint: "#6366f1", amount: 0.7 }),
      Clickable,
    );
    engine.events.on(tower, "click", () => rig.focus(tower, { distance: 6 }));
  }

  engine.fitToElement(canvas);
  engine.start();
  return engine;
}

```

## Moving the camera from code

```ts
rig.focus(entity);                    // target the entity's position
rig.focus({ x: 0, y: 0, z: 0 }, { zoom: 2, immediate: true });
rig.follow(player, { y: 1 });         // keep the target on a moving entity
rig.fit(new Box3(min, max), { margin: 16 }); // frame the bounds
rig.reset();                          // back to where the rig started
```

`focus()` and `fit()` ease in with the rig's `halfLife` unless
`immediate: true`. `fit()` keeps the current direction and changes the
target and the zoom (orthographic) or distance (perspective). Panning stops
`follow()`; rotating and zooming keep it.

## Panels over the scene

When UI covers part of the canvas, tell the rig how much, in CSS pixels:

```ts
rig.padding = { right: 320, top: 80 };
rig.fit(bounds);
```

The target is then centered in the uncovered area (the projection is
shifted with `setViewOffset`), and `fit()` fits the bounds into that area.

## Clicks after a drag

The browser sends `click` when a drag ends, including one that rotates the
camera. [`Pointer`](./input#pointer) clicks only when the gesture was no
drag, so selecting on its clicks never fights the rig:

```ts
engine.plugin(Pointer).on("click", ({ entity }) => select(entity));
```

A gesture that a `Pointer` press listener captured, such as dragging an
entity with the [`Draggable`](./behaviors#ready-made-behaviors) behavior,
does not move the camera.

## Options

| Option | Default | Meaning |
|---|---|---|
| `view` | first view | View whose camera the rig moves. |
| `input` | `engine.plugin(Input)` | Input to read pointers from. |
| `target` | origin | Point to orbit. |
| `padding` | none | Area covered by UI, in CSS pixels per side. |
| `enableRotate`, `enablePan`, `enableZoom` | `true` | Which gestures move the camera. |
| `minDistance`, `maxDistance` | `0`, `Infinity` | Distance limits (perspective). |
| `minZoom`, `maxZoom` | `0`, `Infinity` | `camera.zoom` limits (orthographic). |
| `minPolarAngle`, `maxPolarAngle` | `0`, `π` | Angle from straight above, in radians. |
| `halfLife` | `0.06` | Half-life of moves, in seconds. |
| `rotateSpeed`, `panSpeed`, `zoomSpeed` | `1` | Gesture multipliers. |

All options except `view`, `input` and `target` are also properties that
can be changed later; `rig.enabled = false` ignores input but keeps
`focus()`, `follow()` and `fit()` working.

The [Energy flow](https://jakubprill.github.io/pawn/energy.html) and
CMS Health examples use the rig with an orthographic camera and panels
over the scene.

## Chase camera

`ChaseCamera` is a plugin for games: it sits behind an entity, in the
entity's own space, so it swings round with it in turns, and looks at a
point ahead of it. It trails the entity by a half-life, rolls part of the
way with it, eases its field of view and shakes on demand.

```ts
const chase = new ChaseCamera({
  target: ship,
  offset: { y: 3, z: 10 }, // behind and above a model whose nose is -z
  lookAt: { z: -9 },       // ahead of it
  lean: 0.5,               // roll half as far as the ship
});
engine.use(chase);

chase.fov = boosting ? 76 : 64;       // eases there
chase.shake({ strength: 0.4 });       // on a hit
chase.follow(null);                   // hand the camera to another one
chase.follow(ship);                   // and take it back: cuts to the spot
```

It moves the camera of the engine's first view, or of `view`, after the
game's systems have moved the target each frame. It runs on game time, so a
paused engine holds the camera and its shake still. `shake()` takes a
`strength` in meters (default `0.3`) and a `duration` in seconds (default
`0.4`); a weaker shake during a stronger one changes nothing. `cut()` jumps to the spot on
the next frame instead of easing there, as after a teleport. When the
target is destroyed, the camera stays where it was.

Tap to shake the camera:

```ts
import {
  ChaseCamera,
  Engine,
  Position,
  Rotation,
  Scale,
  Shape,
  View,
} from "@pawnjs/core";
import {
  AmbientLight,
  DirectionalLight,
  Matrix4,
  PerspectiveCamera,
  Quaternion,
  Vector3,
} from "three";

export default function chase(canvas: HTMLCanvasElement): Engine {
  canvas.style.cssText = "display:block;width:100%;height:100%";
  const engine = new Engine({ canvas, seed: 5 });
  const { world, random } = engine;

  engine.scene.add(new AmbientLight(0xffffff, 0.6));
  const sun = new DirectionalLight(0xffffff, 2);
  sun.position.set(6, 10, 4);
  engine.scene.add(sun);

  const camera = new PerspectiveCamera(60, 1, 0.1, 300);
  engine.views.add(new View({ camera, background: 0x09090b }));

  world.spawn(
    Shape({ kind: "plane", color: "#27272a" }),
    Scale({ x: 80, y: 1, z: 80 }),
  );
  // Towers inside and outside the ring the dart flies.
  for (let i = 0; i < 60; i++) {
    const angle = random.range(0, Math.PI * 2);
    const radius = i % 2 ? random.range(4, 10) : random.range(18, 30);
    const height = random.range(1, 6);
    world.spawn(
      Shape({ kind: "box", color: "#e2e8f0" }),
      Position({
        x: Math.cos(angle) * radius,
        y: height / 2,
        z: Math.sin(angle) * radius,
      }),
      Scale({ x: 1.5, y: height, z: 1.5 }),
    );
  }

  const dart = world.spawn(
    Shape({ kind: "box", color: "#6366f1" }),
    Position,
    Rotation,
    Scale({ x: 0.8, y: 0.3, z: 2 }),
  );
  // Behind and above the dart, looking ahead of it, rolling with it.
  const chase = new ChaseCamera({
    target: dart,
    offset: { y: 1.5, z: 5 },
    lookAt: { y: 0.5, z: -4 },
    lean: 0.6,
  });
  engine.use(chase);
  canvas.addEventListener("pointerdown", () => chase.shake({ strength: 0.5 }));

  // A wavy right-hand circle, nose first and banked into the turn.
  const at = new Vector3();
  const ahead = new Vector3();
  const up = new Vector3(0, 1, 0);
  const back = new Vector3(0, 0, 1);
  const basis = new Matrix4();
  const turn = new Quaternion();
  const bank = new Quaternion().setFromAxisAngle(back, -0.5);
  const place = (t: number, out: Vector3) =>
    out.set(Math.cos(t) * 14, 2 + Math.sin(t * 3), Math.sin(t) * 14);
  engine.addSystem(({ elapsed }) => {
    place(elapsed * 0.5, at);
    place(elapsed * 0.5 + 0.01, ahead);
    turn.setFromRotationMatrix(basis.lookAt(at, ahead, up)).multiply(bank);
    dart.set(Position, { x: at.x, y: at.y, z: at.z });
    dart.set(Rotation, { x: turn.x, y: turn.y, z: turn.z, w: turn.w });
  });

  engine.fitToElement(canvas);
  engine.start();
  return engine;
}

```

| Option | Default | Meaning |
|---|---|---|
| `view` | first view | View whose camera it moves. |
| `target` | none | Entity to chase; or `follow(entity)` later. |
| `offset` | `{ x: 0, y: 3, z: 8 }` | Where the camera sits, in the target's own space. |
| `lookAt` | `{ x: 0, y: 1, z: -8 }` | Point it looks at, in the target's own space. |
| `halfLife` | `0.06` | Seconds to cover half the way to its spot; 0 keeps it there. |
| `lean` | `0.5` | How far it rolls with the target, 0 (level) to 1. Where a level horizon points nowhere it rolls further: from nothing extra with the target on its side to all of it a third of the way on to upside down, as through a loop, and all the way while it looks almost straight up or down at a target whose up still reaches across the view. |
| `fov` | camera's | Field of view in degrees to ease toward. |
| `fovHalfLife` | `0.25` | Seconds for `fov` to cover half the way. |

All options except `view` and `target` are also properties; `offset` and
`lookAt` are `Vector3`s to change in place.
