Klipp

Full documentation content.

<page path="/getting-started/introduction" title="Introduction"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/getting-started/introduction
Description: A camera toolkit for the web, inspired by Unity Cinemachine.

# Introduction

A camera toolkit for the web, inspired by Unity Cinemachine.

Describe the shots you want. **Klipp** picks the right one and smoothly blends between them.

```bash
npm install @pmndrs/klipp
```

> \[!WARNING] Early-stage and experimental. The API may still change.

> \[!TIP] See it in action on the [examples site](https://pmndrs.github.io/klipp/examples/).

## Why Klipp?

Most 3D projects rebuild the same camera code: an offset that follows the player, damping, a dead zone, a cutscene camera and a smooth way back. Klipp brings the virtual camera model from engines like Unity to the web: each shot is described on its own, the one with the highest priority is on screen, and switching between shots is a blend.

## One system, any renderer

The core is a complete camera system with no renderer or framework attached. Integrations are thin layers on top of it: three.js and React Three Fiber today, with more to come, like TresJS. Each page shows the core and every integration in tabs.

## What it looks like

A follow camera, and a cutscene camera that takes over when it turns on. Turning it off blends back.

**Core**

**three.js**

**React Three Fiber**

```ts
import { vec3 } from 'math';
import { Klipp, FollowBody, HardLockToTargetBody, HardLookAtAim, targetPose, VirtualCamera } from '@pmndrs/klipp';

const klipp = new Klipp();
const player = targetPose.create(); // keep player.position up to date
const spot = targetPose.create();
vec3.set(spot.position, 10, 2, 0);

const follow = new VirtualCamera('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBody(player, { offset: [0, 3, 8], damping: 0.5 });
follow.aim = new HardLookAtAim(player);

const cutscene = new VirtualCamera('cutscene', { priority: 20, active: false });
klipp.add(cutscene);
cutscene.body = new HardLockToTargetBody(spot);
cutscene.aim = new HardLookAtAim(player);

// every frame
klipp.update(dt);
engineCamera.setPosition(klipp.shot.position);
engineCamera.setRotation(klipp.shot.quaternion);
```

```ts
import { Vector3 } from 'three';
import { KlippThree, FollowBodyThree, HardLockToTargetBodyThree, HardLookAtAimThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const klipp = new KlippThree(camera);

const follow = new VirtualCameraThree('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8), damping: 0.5 });
follow.aim = new HardLookAtAimThree(player);

const cutscene = new VirtualCameraThree('cutscene', { priority: 20, active: false });
klipp.add(cutscene);
cutscene.body = new HardLockToTargetBodyThree(new Vector3(10, 2, 0));
cutscene.aim = new HardLookAtAimThree(player);

// every frame, before rendering
klipp.update(dt);
```

```tsx
import { Klipp, VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

<Klipp>
  <VirtualCamera name="follow" priority={10}>
    <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
    <Aim.HardLookAt target={playerRef} />
  </VirtualCamera>

  <VirtualCamera name="cutscene" priority={20} active={isCutscene}>
    <Body.HardLockToTarget target={[10, 2, 0]} />
    <Aim.HardLookAt target={playerRef} />
  </VirtualCamera>
</Klipp>
```

## Next steps

1. [Installation](/klipp/docs/getting-started/installation)
2. [Core concepts](/klipp/docs/getting-started/core-concepts)
3. [Your first camera](/klipp/docs/getting-started/your-first-camera)
4. [Building on the core](/klipp/docs/getting-started/building-on-the-core), for your own integration or for data and functions
]]></page>
<page path="/getting-started/installation" title="Installation"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/getting-started/installation
Description: Install Klipp and pick the right entry point.

# Installation

Install Klipp and pick the right entry point.

```bash
npm install @pmndrs/klipp
```

The core and each integration have their own entry point. Each one only needs the libraries it adapts to, all of them optional peer dependencies:

| Entry point           | What's in it                                                                                                                               | Install as well                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| `@pmndrs/klipp`       | The core: `Klipp`, `VirtualCamera`, every piece as a class, and the data and functions underneath.                                         | nothing                                |
| `@pmndrs/klipp/three` | The core classes for three.js, ending in `Three`: they read `Object3D` targets and drive a `PerspectiveCamera` or an `OrthographicCamera`. | `three`                                |
| `@pmndrs/klipp/react` | React Three Fiber components, built on the three.js classes.                                                                               | `three`, `react`, `@react-three/fiber` |
| `@pmndrs/klipp/dom`   | Mouse, touch and wheel input, and debug overlays.                                                                                          | nothing, runs in a browser             |

Vectors in the core are plain arrays from [`math`](https://github.com/pmndrs/math): `[x, y, z]` and `[x, y, z, w]`. Add it to your dependencies to use its `vec3` and `quat` functions. Constants like `BlendCurves` always come from the core.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { Klipp, FollowBody, HardLookAtAim, targetPose, BlendCurves } from '@pmndrs/klipp';
```

```bash
npm install three
```

```ts
import { BlendCurves } from '@pmndrs/klipp';
import { KlippThree, FollowBodyThree, HardLookAtAimThree } from '@pmndrs/klipp/three';
```

```bash
npm install three react @react-three/fiber
```

```tsx
import { BlendCurves } from '@pmndrs/klipp';
import { Klipp, VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';
```

[Your first camera](/klipp/docs/getting-started/your-first-camera) builds a complete scene with each of them.
]]></page>
<page path="/getting-started/core-concepts" title="Core concepts"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/getting-started/core-concepts
Description: Virtual cameras, priority, the pieces that build a shot, and targets.

# Core concepts

Virtual cameras, priority, the pieces that build a shot, and targets.

## Virtual cameras

A virtual camera is a shot you might want to show. You can have as many as you like. Klipp decides which one is on screen:

- the **active** camera with the highest `priority` wins,
- an inactive camera is out of the running completely,
- when the winner changes, Klipp [blends](/klipp/docs/blending/introduction) from the old shot to the new one.

## Building a shot

Each camera is made of up to four kinds of pieces, which run in this order every frame:

| Piece                                           | What it does       | How many | Examples                                     |
| ----------------------------------------------- | ------------------ | -------- | -------------------------------------------- |
| [Body](/klipp/docs/body/introduction)           | Moves the camera   | one      | `Follow`, `OrbitFollow`, `PositionComposer`  |
| [Aim](/klipp/docs/aim/introduction)             | Rotates the camera | one      | `HardLookAt`, `RotationComposer`             |
| [Extension](/klipp/docs/extension/introduction) | Adjusts the shot   | any      | `GroupFraming`, `Lens`                       |
| [Noise](/klipp/docs/noise/introduction)         | Adds shake on top  | any      | `BasicMultiChannelPerlin`, `ImpulseListener` |

A few Extensions run earlier, because the Body or Aim works with what they set: `Lens` runs first, and `FollowZoom` and `Confiner` right after the Body. See [Extensions](/klipp/docs/extension/introduction).

Body and Aim are independent, so a camera can follow one object while looking at another. Every piece is optional: a camera without an Aim keeps its starting rotation.

## One piece in every integration

Every piece is a core class. Integrations adapt it to their world: in three.js, `FollowBodyThree` is `FollowBody` reading `Object3D` targets, and the React `<Body.Follow>` creates one for you. Settings have the same names everywhere.

## Targets

Pieces follow and look at targets:

- **Core:** the core doesn't know about your scene. A target is a `TargetPose` you keep up to date from wherever your data lives: `position`, and `rotation` with `hasRotation`. Pieces that frame by size, like the composers, also read its `extent`.
- **three.js and React Three Fiber:** a target is an `Object3D`, a ref to one, or a fixed point: a `Vector3` or `[x, y, z]`. Objects are tracked live, including their rotation.

A target of `null`, or a ref that is still empty, is ignored until it resolves.

## Damping

Most pieces take a `damping` setting that makes them ease toward their goal instead of snapping to it. It's a time in seconds: `0` is instant, `0.5` feels smooth, `2` feels heavy.

Pass `{ into, from }` to ease differently while the gap is growing (`into`) and while it's closing again (`from`).

Next to `damping` you'll usually find `maxSpeed`, which caps how fast the camera may move while catching up.

## Changing settings while running

Settings are plain fields, so you can change them at any time, even every frame. Vector fields are always `[x, y, z]` arrays. In React, `ref` gives you the piece itself, so you can change it without re-rendering.

## Usage

Feeding a target:

**Core**

**three.js**

**React Three Fiber**

```ts
import { quat, vec3 } from 'math';
import { targetPose } from '@pmndrs/klipp';

const player = targetPose.create();
player.extent.radius = 0.5; // for pieces that frame by size

// every frame, before klipp.update
vec3.copy(player.position, playerPosition);
quat.copy(player.rotation, playerRotation);
player.hasRotation = true;
```

```ts
new HardLookAtAimThree(player);               // an Object3D
new HardLookAtAimThree({ current: player });  // a ref to one
new HardLookAtAimThree(new Vector3(0, 1, 0)); // a fixed point, or [0, 1, 0]
```

```tsx
<Aim.HardLookAt target={playerRef} />   // a ref to an Object3D
<Aim.HardLookAt target={player} />      // an Object3D
<Aim.HardLookAt target={[0, 1, 0]} />   // a fixed point, like <mesh position>
```

Ready to build one? Continue with [Your first camera](/klipp/docs/getting-started/your-first-camera).
]]></page>
<page path="/getting-started/your-first-camera" title="Your first camera"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/getting-started/your-first-camera
Description: Build a follow camera and switch to a second shot, step by step.

# Your first camera

Build a follow camera and switch to a second shot, step by step.

This guide builds a camera that follows a moving box, then adds a second shot and switches between the two.

**Core**

**three.js**

**React Three Fiber**

The core works with any renderer. Where the code touches yours, it says `engine`.

### Create Klipp

```ts title="main.ts"
import { Klipp } from '@pmndrs/klipp';

const klipp = new Klipp();
klipp.setSize(canvas.width, canvas.height);
```

`setSize` matters for pieces that frame by screen position, like the composers. Call it again whenever the viewport resizes.

### Add a moving target

The core doesn't read your scene. A target is a `TargetPose` you keep up to date. After `update`, `klipp.shot` holds the shot to put on your camera:

```ts
import { vec3 } from 'math';
import { targetPose } from '@pmndrs/klipp';

const player = targetPose.create();

function frame(dt: number) {
  const t = engine.time;
  vec3.set(player.position, Math.sin(t) * 4, 0.5, Math.cos(t) * 4);
  engine.box.setPosition(player.position);

  klipp.update(dt);
  engine.camera.setPosition(klipp.shot.position); // [x, y, z]
  engine.camera.setRotation(klipp.shot.quaternion); // [x, y, z, w]
  engine.camera.setFov(klipp.shot.fov); // degrees
  engine.render();
}
```

### Add a virtual camera

A virtual camera is one shot, described by a **Body**, which decides where the camera is, and an **Aim**, which decides where it looks:

```ts
import { FollowBody, HardLookAtAim, VirtualCamera } from '@pmndrs/klipp';

const follow = new VirtualCamera('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBody(player, { offset: [0, 3, 8] });
follow.aim = new HardLookAtAim(player);
```

The camera now stays 8 units behind and 3 units above the box, looking straight at it.

### Smooth it out

`damping` lets the camera lag behind a little instead of being glued to the box. The value is roughly how many seconds it takes to catch up:

```ts
follow.body = new FollowBody(player, { offset: [0, 3, 8], damping: 0.5 });
```

### Add a second shot

A wide overview camera with a higher `priority`, turned on and off with `active`:

```ts
import { HardLockToTargetBody, VirtualCamera } from '@pmndrs/klipp';

const above = targetPose.create();
vec3.set(above.position, 0, 15, 15);
const center = targetPose.create();

const overview = new VirtualCamera('overview', { priority: 20, active: false });
klipp.add(overview);
overview.body = new HardLockToTargetBody(above);
overview.aim = new HardLookAtAim(center);

button.onclick = () => {
  overview.active = !overview.active;
};
```

The highest-priority active camera is the one on screen. Toggle `overview` and Klipp blends between the two shots.

### Change the blend

By default a blend takes 2 seconds with an ease-in-out curve:

```ts
import { BlendCurves } from '@pmndrs/klipp';

const klipp = new Klipp({ defaultBlend: { curve: BlendCurves.easeInOut, time: 0.8 } });
```

### Create Klipp

`KlippThree` drives a three.js camera:

```ts title="main.ts"
import { GridHelper, PerspectiveCamera, Scene, WebGLRenderer } from 'three';
import { KlippThree } from '@pmndrs/klipp/three';

const renderer = new WebGLRenderer();
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);

const scene = new Scene();
scene.add(new GridHelper(20, 20));
const camera = new PerspectiveCamera(50, innerWidth / innerHeight);

const klipp = new KlippThree(camera);
klipp.setSize(innerWidth, innerHeight);
```

`setSize` matters for pieces that frame by screen position, like the composers. Call it again whenever the viewport resizes.

### Add a moving box

Any `Object3D` can be a target. `klipp.update` writes the shot to the camera:

```ts
import { BoxGeometry, Mesh, MeshNormalMaterial } from 'three';

const player = new Mesh(new BoxGeometry(), new MeshNormalMaterial());
scene.add(player);

let last = 0;
renderer.setAnimationLoop((time) => {
  const t = time / 1000;
  player.position.set(Math.sin(t) * 4, 0.5, Math.cos(t) * 4);

  klipp.update(t - last);
  last = t;
  renderer.render(scene, camera);
});
```

### Add a virtual camera

A virtual camera is one shot, described by a **Body**, which decides where the camera is, and an **Aim**, which decides where it looks:

```ts
import { Vector3 } from 'three';
import { FollowBodyThree, HardLookAtAimThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const follow = new VirtualCameraThree('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8) });
follow.aim = new HardLookAtAimThree(player);
```

The camera now stays 8 units behind and 3 units above the box, looking straight at it.

### Smooth it out

`damping` lets the camera lag behind a little instead of being glued to the box. The value is roughly how many seconds it takes to catch up:

```ts
follow.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8), damping: 0.5 });
```

### Add a second shot

A wide overview camera with a higher `priority`, turned on and off with `active`. A target can also be a fixed point:

```ts
import { Vector3 } from 'three';
import { HardLockToTargetBodyThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const overview = new VirtualCameraThree('overview', { priority: 20, active: false });
klipp.add(overview);
overview.body = new HardLockToTargetBodyThree(new Vector3(0, 15, 15));
overview.aim = new HardLookAtAimThree(new Vector3(0, 0, 0));

button.onclick = () => {
  overview.active = !overview.active;
};
```

The highest-priority active camera is the one on screen. Toggle `overview` and Klipp blends between the two shots.

### Change the blend

By default a blend takes 2 seconds with an ease-in-out curve:

```ts
import { BlendCurves } from '@pmndrs/klipp';

const klipp = new KlippThree(camera, { defaultBlend: { curve: BlendCurves.easeInOut, time: 0.8 } });
```

### Start with a scene

A box that moves in a circle. A ref to it will be the target:

```tsx title="App.tsx"
import { useRef } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import type { Mesh } from 'three';

function Player({ ref }) {
  useFrame(({ clock }) => {
    const t = clock.getElapsedTime();
    ref.current.position.set(Math.sin(t) * 4, 0.5, Math.cos(t) * 4);
  });

  return (
    <mesh ref={ref}>
      <boxGeometry />
      <meshNormalMaterial />
    </mesh>
  );
}

export default function App() {
  const playerRef = useRef<Mesh>(null);

  return (
    <Canvas>
      <Player ref={playerRef} />
      <gridHelper args={[20, 20]} />
    </Canvas>
  );
}
```

### Add `<Klipp>`

`<Klipp>` drives the camera. Put it anywhere inside `<Canvas>`:

```tsx
import { Klipp } from '@pmndrs/klipp/react';

<Canvas>
  <Klipp>{/* cameras go here */}</Klipp>
  <Player ref={playerRef} />
</Canvas>
```

### Add a virtual camera

A `<VirtualCamera>` is one shot, described by a **Body**, which decides where the camera is, and an **Aim**, which decides where it looks:

```tsx
import { Klipp, VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

<Klipp>
  <VirtualCamera name="follow" priority={10}>
    <Body.Follow target={playerRef} offset={[0, 3, 8]} />
    <Aim.HardLookAt target={playerRef} />
  </VirtualCamera>
</Klipp>
```

The camera now stays 8 units behind and 3 units above the box, looking straight at it.

### Smooth it out

`damping` lets the camera lag behind a little instead of being glued to the box. The value is roughly how many seconds it takes to catch up:

```tsx
<Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
```

### Add a second shot

A wide overview camera with a higher `priority`, turned on and off with `active`. A target can also be a fixed point, `[x, y, z]`:

```tsx title="App.tsx" collapsible
import { useRef, useState } from 'react';
import { Canvas } from '@react-three/fiber';
import type { Mesh } from 'three';
import { Klipp, VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

export default function App() {
  const playerRef = useRef<Mesh>(null);
  const [overview, setOverview] = useState(false);

  return (
    <>
      <button onClick={() => setOverview(!overview)}>Toggle overview</button>
      <Canvas>
        <Klipp>
          <VirtualCamera name="follow" priority={10}>
            <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
            <Aim.HardLookAt target={playerRef} />
          </VirtualCamera>

          <VirtualCamera name="overview" priority={20} active={overview}>
            <Body.HardLockToTarget target={[0, 15, 15]} />
            <Aim.HardLookAt target={[0, 0, 0]} />
          </VirtualCamera>
        </Klipp>
        <Player ref={playerRef} />
        <gridHelper args={[20, 20]} />
      </Canvas>
    </>
  );
}
```

The highest-priority active camera is the one on screen. Toggle `overview` and Klipp blends between the two shots.

### Change the blend

By default a blend takes 2 seconds with an ease-in-out curve:

```tsx
import { BlendCurves } from '@pmndrs/klipp';

<Klipp defaultBlend={{ curve: BlendCurves.easeInOut, time: 0.8 }}>
```

## Where to go next

- [Body](/klipp/docs/body/introduction) and [Aim](/klipp/docs/aim/introduction) for every way to position and aim a camera.
- [Blending](/klipp/docs/blending/introduction) for curves, per-camera transitions and blend hints.
- [Building on the core](/klipp/docs/getting-started/building-on-the-core) to read your engine's objects directly, or to use plain data and functions.
]]></page>
<page path="/getting-started/building-on-the-core" title="Building on the core"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/getting-started/building-on-the-core
Description: Integrate Klipp with your own renderer or engine, or use the data and functions underneath.

# Building on the core

Integrate Klipp with your own renderer or engine, or use the data and functions underneath.

The core is the whole camera system. An integration only adapts the two places where it meets your world: where the shot goes, and where the targets come from. Klipp's own integrations are built exactly this way.

## Your own integration

### Put the shot on your camera

Read `klipp.shot` after `update`. To update your camera only when the shot changes, extend `Klipp` and override `write` instead:

```ts title="EngineKlipp.ts"
import { Klipp, type CameraState } from '@pmndrs/klipp';

class EngineKlipp extends Klipp {
  protected override write(shot: CameraState, transformChanged: boolean, lensChanged: boolean) {
    if (transformChanged) engine.camera.setTransform(shot.position, shot.quaternion);
    if (lensChanged) engine.camera.setFov(shot.fov);
  }
}
```

### Read your targets

Every piece with a target reads it through `readTarget`. By default the target is a `TargetPose` you fill in yourself. To follow your engine's objects directly, extend the piece and fill the pose from them:

```ts title="EngineFollow.ts"
import { quat, vec3 } from 'math';
import { FollowBody, targetPose, type TargetPose } from '@pmndrs/klipp';

class EngineFollow extends FollowBody<EngineObject | null> {
  private readonly pose = targetPose.create();

  protected override readTarget(): TargetPose | null {
    if (!this.target) return null;
    vec3.copy(this.pose.position, this.target.worldPosition);
    quat.copy(this.pose.rotation, this.target.worldRotation);
    this.pose.hasRotation = true;
    return this.pose;
  }
}

camera.body = new EngineFollow(player, { offset: [0, 3, 8] });
```

The same works for `HardLockToTargetBody`, `OrbitFollowBody`, `PositionComposerBody`, `HardLookAtAim`, `RotateWithFollowTargetAim`, `RotationComposerAim` and `PanTiltAim`. `FollowZoomExtension` reads its target the same way, `ConfinerExtension` its bounds through `readBounds` and `GroupFramingExtension` its members through `readMembers`.

Name your classes after the core one with a suffix of your own, like `FollowBodyThree`, which is `FollowBody` reading an `Object3D`.

For logic of your own, write a [custom piece](/klipp/docs/advanced/custom-components).

## Data and functions

Under its classes, every piece is plain data and functions on [`math`](https://github.com/pmndrs/math), in a namespace named after it, with the same three parts. For example, `FollowBody` has:

- `FollowParams`, and `follow.createParams(settings)` for the defaults: its settings (`offset`, `damping`, ...).
- `FollowState` and `follow.createState()`: the memory it keeps between frames, like damping velocity.
- `follow.update(out, state, params, ...)`: advances one frame and writes into a `CameraState`.

A class is a thin wrapper that passes itself as `params`. Calling the functions directly gives you full control, for example from an ECS or a simulation:

```ts
import { cameraState, follow, targetPose, hardLookAt } from '@pmndrs/klipp';

const camera = cameraState.create();
const state = follow.createState();
const params = follow.createParams({ offset: [0, 3, 8], damping: 0.5 });
const player = targetPose.create();

function frame(dt: number, justActivated: boolean) {
  follow.update(camera, state, params, player, dt, justActivated);
  hardLookAt.update(camera, player.position);
}
```

`justActivated` is `true` on a camera's first frame, and again when it turns back on, so smoothing starts from the right place. Virtual cameras pass it for you.

Picking the camera and blending works the same way. `klippState.tick` returns the shot, and pushes transitions to `state.events` as data:

```ts
import { klippState, cameraState } from '@pmndrs/klipp';

const klipp = klippState.create();
const klippParams = klippState.createParams();
klippState.register(klipp, { name: 'follow', priority: 10, state: camera });

function frame(dt: number) {
  const shot = klippState.tick(klipp, klippParams, dt);
  klipp.events.length = 0;
  // write shot to your camera, for example only when cameraState.transformEquals says it moved
}
```

### With an ECS

Because state is plain data, it can live in components. A sketch with [Koota](https://github.com/pmndrs/koota):

```ts
import { createWorld, trait } from 'koota';
import { cameraState, follow, targetPose } from '@pmndrs/klipp';

const Camera = trait(() => cameraState.create());
const Target = trait(() => targetPose.create());
const Follow = trait(() => ({ state: follow.createState(), params: follow.createParams({ offset: [0, 3, 8] }) }));

const world = createWorld();
world.spawn(Camera, Target, Follow);

function frame(dt: number) {
  world.query(Camera, Target, Follow).updateEach(([camera, target, { state, params }]) => {
    follow.update(camera, state, params, target, dt, false);
  });
}
```

### What's available

Each piece is a namespace with the same names: `update` runs one frame, `createState()` makes its memory and `createParams()` its settings. The other namespaces are the parts they share.

| Area                | Namespaces                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------- |
| Body                | `follow`, `hardLockToTarget`, `orbitFollow`, `positionComposer`                             |
| Aim                 | `hardLookAt`, `panTilt`, `rotateWithFollowTarget`, `rotationComposer`                       |
| Extension           | `cameraOffset`, `confiner`, `followZoom`, `groupFraming`, `lens`, `recomposer`              |
| Noise               | `basicMultiChannelPerlin`, `impulseListener`, `impulses`                                    |
| Following a target  | `tracker` (shared by `follow` and `orbitFollow`), `threeRing` (the `threeRing` orbit style) |
| Targets             | `targetExtent`, `targetPose`                                                                |
| Input               | `consumedInput`, `inputAxis`, `inputMapping`                                                |
| Choosing the camera | `klippState`                                                                                |
| Blending            | `blend`, `cameraState.lerp`                                                                 |
| Damping             | `damping`, `predictor`                                                                      |
| Debugging           | `debugZones`                                                                                |
| Output              | `cameraState.lensEquals`, `cameraState.transformEquals`                                     |
]]></page>
<page path="/api/klipp" title="Klipp"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/api/klipp
Description: Picks the winning camera, blends between shots and drives the real camera.

# Klipp

Picks the winning camera, blends between shots and drives the real camera.

The camera director: it runs every [virtual camera](/klipp/docs/api/virtual-camera), picks the winner, blends between shots, and puts the result on your camera.

`Klipp` works with any renderer: put its `shot` on your camera after `update`. Integrations write it for you, like `KlippThree` for three.js and `<Klipp>` for React Three Fiber.

## Members

| Member                                           | Description                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add(camera)`, `remove(camera)`                  | Adds or removes a [virtual camera](/klipp/docs/api/virtual-camera). Adding moves it from any other klipp.                                                                                                                                                                                                                         |
| `update(dt)`                                     | Runs one frame. Returns `true` while something is still moving or the shot changed.                                                                                                                                                                                                                                               |
| `shot`                                           | The current shot, see below.                                                                                                                                                                                                                                                                                                      |
| `setSize(width, height)`                         | The viewport size in pixels, for pieces that frame by screen position.                                                                                                                                                                                                                                                            |
| `orthographic`                                   | Whether the camera being driven is orthographic. See [Orthographic cameras](#orthographic-cameras).                                                                                                                                                                                                                               |
| `defaultBlend`, `customBlends`                   | The blends, changeable at any time.                                                                                                                                                                                                                                                                                               |
| `registerUpdate(fn)`                             | Runs `fn` every frame before the cameras, for input. Returns a function that stops it.                                                                                                                                                                                                                                            |
| `whileOnScreen(camera, start, { waitForBlend })` | Calls `start` while `camera` is on screen, and the function it returns once it leaves, for example to connect input. A camera in a [group](/klipp/docs/groups/introduction) is on screen only while the group is too. With `waitForBlend` (the default), only once the blend into it has finished. Returns a function that stops. |
| `mode`                                           | `'enabled'`, `'standby'` or `'disabled'`. See below.                                                                                                                                                                                                                                                                              |
| `activeCameraName`, `isActive(name)`             | The winner, the camera the shot is heading to.                                                                                                                                                                                                                                                                                    |
| `activeCameraState`                              | The winner's own state, before blending.                                                                                                                                                                                                                                                                                          |
| `liveCameraName`, `isLive(name)`                 | The camera fully on screen, once the blend into it has finished.                                                                                                                                                                                                                                                                  |
| `isBlending`                                     | Whether a blend is in progress.                                                                                                                                                                                                                                                                                                   |

Klipp is also an event target, see [Events](/klipp/docs/api/events).

## `mode`

| Mode         | Cameras update | Camera is written |
| ------------ | -------------- | ----------------- |
| `'enabled'`  | yes            | yes               |
| `'standby'`  | yes            | no                |
| `'disabled'` | no             | no                |

Use `'standby'` to hand the camera to something else for a while (an editor, a photo mode). Klipp keeps its cameras updated in the background, so they're ready the moment you switch back.

## The shot

`shot` is a `CameraState`:

| Field                    | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `position`, `quaternion` | Where the camera is and how it's turned: `[x, y, z]` and `[x, y, z, w]`.                             |
| `fov`, `near`, `far`     | Lens settings, `fov` in degrees.                                                                     |
| `orthographicSize`       | Half the view's height in world units, used by an orthographic camera instead of `fov`.              |
| `viewOffset`             | Shifts the view without moving the camera, as a fraction of half the viewport. `[0, 0]` is centered. |

`shot` changes only once the first camera goes live, and stays put in `'standby'`. To react only when it changes, override `write`, see [Building on the core](/klipp/docs/getting-started/building-on-the-core#your-own-integration).

## Orthographic cameras

An orthographic camera shows `orthographicSize` world units above and below the center of the view, at any distance. Each virtual camera has its own size, like its `fov`: set it with [`Lens`](/klipp/docs/extension/lens) or in `initialState`, and blends move between sizes.

`orthographic` tells the pieces whether the camera being driven is orthographic. `KlippThree` and `<Klipp>` set it from their camera, also when it is swapped, for example for drei's `<OrthographicCamera makeDefault>`. On the core, set it yourself.

`KlippThree` keeps the camera's `left`, `right`, `top` and `bottom` and writes the size through `zoom`, so after a resize the same part of the world stays in view. New virtual cameras start from the size of the camera `KlippThree` was created with, like `<Canvas orthographic camera={{ zoom: 50 }}>`. A camera swapped in later leaves the size of existing virtual cameras alone.

## Usage

**Core**

**three.js**

**React Three Fiber**

`Klipp` works with any renderer. Call `update` every frame and put `shot` on your camera:

```ts
import { BlendCurves, Klipp, VirtualCamera } from '@pmndrs/klipp';

const klipp = new Klipp({ defaultBlend: { curve: BlendCurves.easeInOut, time: 1 } });
klipp.setSize(canvas.width, canvas.height);
klipp.add(new VirtualCamera('main', { priority: 10 }));

function frame(dt: number) {
  if (klipp.update(dt)) {
    engine.camera.setTransform(klipp.shot.position, klipp.shot.quaternion);
    engine.camera.setFov(klipp.shot.fov);
    engine.render();
  }
}
```

New cameras start from `initialCameraState`, an option of `Klipp`. Pass your camera's starting pose there. For an orthographic camera, set `orthographic` to `true` and use `shot.orthographicSize` instead of `fov`.

`KlippThree` is `Klipp` driving a three.js camera. `update` writes the shot to it:

```ts
import { BlendCurves } from '@pmndrs/klipp';
import { KlippThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const klipp = new KlippThree(camera, { defaultBlend: { curve: BlendCurves.easeInOut, time: 1 } });
klipp.setSize(innerWidth, innerHeight);
klipp.add(new VirtualCameraThree('main', { priority: 10 }));

renderer.setAnimationLoop(() => {
  klipp.update(dt);
  renderer.render(scene, camera);
});
```

New cameras start from the camera's lens, position and rotation at the time `KlippThree` is created. It drives a `PerspectiveCamera` or an [`OrthographicCamera`](#orthographic-cameras), and `klipp.camera` can be swapped at any time: the new camera gets the shot on the next frame. `camera.aspect`, or an orthographic camera's `left`, `right`, `top` and `bottom`, stay yours to update on resize, next to `setSize`.

`<Klipp>` creates a `KlippThree` on the React Three Fiber camera and runs it every frame. It has to be inside `<Canvas>`.

```tsx
import { BlendCurves } from '@pmndrs/klipp';
import { Klipp } from '@pmndrs/klipp/react';

<Canvas>
  <Klipp defaultBlend={{ curve: BlendCurves.easeInOut, time: 1 }}>
    <VirtualCamera name="main" priority={10}>...</VirtualCamera>
  </Klipp>
</Canvas>
```

| Prop           | Description                                                                                             | Default                                     |
| -------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `defaultBlend` | How to blend between cameras. See [Blending](/klipp/docs/blending/introduction).                        | `{ curve: BlendCurves.easeInOut, time: 2 }` |
| `customBlends` | Blends for specific camera pairs. See [Custom blends](/klipp/docs/blending/introduction#custom-blends). | `[]`                                        |
| `camera`       | The camera to drive.                                                                                    | the r3f default camera                      |
| `mode`         | `'enabled'`, `'standby'` or `'disabled'`. See [`mode`](#mode).                                          | `'enabled'`                                 |

Virtual cameras start from the real camera's lens, position and rotation, so whatever you set on `<Canvas camera={...}>` is the starting point. `<Canvas orthographic>` works too, see [Orthographic cameras](#orthographic-cameras). It keeps the viewport size in sync for you.

[`useKlipp()`](/klipp/docs/api/hooks#useklipp) gives you the `KlippThree` behind `<Klipp>`, with the members above, and [`<Klipp.Events>`](/klipp/docs/api/events) listens to every transition.
]]></page>
<page path="/api/virtual-camera" title="VirtualCamera"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/api/virtual-camera
Description: A single shot that competes for the screen.

# VirtualCamera

A single shot that competes for the screen.

A virtual camera describes one shot. Its pieces decide where the camera is and where it looks, and its `priority` decides when it's on screen.

## Choosing the winner

- The active camera with the highest `priority` wins.
- On a tie, the camera that was added, or set active, most recently wins.
- To switch shots, change `priority`, or turn a camera on or off. Either one triggers a blend.

## Members

| Member                                   | Description                                                                                                                                                                                       |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `body`, `aim`                            | The Body and Aim. Setting one replaces the previous.                                                                                                                                              |
| `setBody(piece)`, `setAim(piece)`        | The same, returning a function that removes the piece.                                                                                                                                            |
| `addExtension(piece)`, `addNoise(piece)` | Adds an Extension or Noise. They stack, in the order added, with a few Extensions running earlier, see [Extensions](/klipp/docs/extension/introduction). Each returns a function that removes it. |
| `name`, `priority`, `active`, `hints`    | The settings below, changeable at any time.                                                                                                                                                       |
| `state`                                  | The camera's own shot, written by its pieces every frame.                                                                                                                                         |

## Settings

| Setting         | Description                                                                                                                 | Default                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `name`          | Unique name. Used by [custom blends](/klipp/docs/blending/introduction#custom-blends) and [events](/klipp/docs/api/events). | required               |
| `priority`      | The active camera with the highest priority is on screen.                                                                   | `0`                    |
| `active`        | Whether this camera takes part at all. `false` also stops its pieces from running. Turning it back on starts it fresh.      | `true`                 |
| `hints`         | Changes the shape of blends in and out of this camera. See [Blend hints](/klipp/docs/blending/introduction#blend-hints).    | `BlendHints.none`      |
| `initialState`  | Starting pose, applied once. See below.                                                                                     | the real camera's pose |
| `standbyUpdate` | How this camera updates while another one is on screen: `'always'`, `'roundRobin'` or `'never'`. See below.                 | `'roundRobin'`         |

## `initialState`

Sets where the camera starts. Useful for a camera without a Body or Aim, since whatever you set here simply stays put.

It takes any camera state field, most commonly `position`, `quaternion` and `fov`. Pieces with damping ease in from it on the camera's first activation instead of snapping. In three.js and React, vectors also accept a `Vector3` or a single number, and `quaternion` a `Quaternion`.

## `standbyUpdate`

Cameras off screen don't need to update every frame: nobody sees them. By default they take turns, so many cameras cost about as much as two:

| Value          | Off screen, the camera                                                            |
| -------------- | --------------------------------------------------------------------------------- |
| `'roundRobin'` | takes turns with the other `'roundRobin'` cameras: one of them updates per frame. |
| `'always'`     | updates every frame.                                                              |
| `'never'`      | waits until it wins.                                                              |

The camera the shot heads to always updates, and one that skipped frames catches up with the time it missed, so switching to it is smooth. While a camera is off screen, its `state` is only as fresh as its last update: use `'always'` for a camera whose `state` you read every frame, like one shown with a frustum helper.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { FollowBody, HardLookAtAim, targetPose, VirtualCamera } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position and player.rotation up to date

const follow = new VirtualCamera('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBody(player, { offset: [0, 3, 8] });
follow.aim = new HardLookAtAim(player);

const map = new VirtualCamera('map', { priority: 20, active: false });
klipp.add(map);
map.active = mapOpen;
```

**`initialState`**

```ts
klipp.add(new VirtualCamera('fixed', { priority: 10, initialState: { position: [0, 10, 10], fov: 35 } }));
```

**`standbyUpdate`**

```ts
klipp.add(new VirtualCamera('security-cam', { priority: 5, standbyUpdate: 'never' }));
```

```ts
import { Vector3 } from 'three';
import { FollowBodyThree, HardLookAtAimThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const follow = new VirtualCameraThree('follow', { priority: 10 });
klipp.add(follow);
follow.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8) });
follow.aim = new HardLookAtAimThree(player);

const map = new VirtualCameraThree('map', { priority: 20, active: false });
klipp.add(map);
map.active = mapOpen;
```

**`initialState`**

```ts
klipp.add(new VirtualCameraThree('fixed', { priority: 10, initialState: { position: new Vector3(0, 10, 10), fov: 35 } }));
```

**`standbyUpdate`**

```ts
klipp.add(new VirtualCameraThree('security-cam', { priority: 5, standbyUpdate: 'never' }));
```

```tsx
import { VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} />
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>

<VirtualCamera name="map" priority={20} active={mapOpen}>...</VirtualCamera>
```

`ref` gives you the camera, with the members above.

**`initialState`**

```tsx
<VirtualCamera name="fixed" priority={10} initialState={{ position: [0, 10, 10], fov: 35 }}>
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```

**`<VirtualCamera.Events>`**

Listens to transitions involving this camera only. See [Events](/klipp/docs/api/events).

```tsx
<VirtualCamera name="boss" priority={50} active={bossFight}>
  <VirtualCamera.Events onBlendFinished={() => startBossMusic()} />
</VirtualCamera>
```

**`standbyUpdate`**

```tsx
<VirtualCamera name="security-cam" priority={5} standbyUpdate="never">...</VirtualCamera>
```
]]></page>
<page path="/api/hooks" title="Hooks"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/api/hooks
Description: Read Klipp's state from your own components.

# Hooks

Read Klipp's state from your own components.

Hooks are React only. Elsewhere, read the same values from [Klipp](/klipp/docs/api/klipp#members).

## `useIsActiveVirtualCamera`

Whether the nearest `<VirtualCamera>` is the current winner. Turns `true` as soon as the blend into it starts.

```tsx
function Hud() {
  const isActive = useIsActiveVirtualCamera();
  return isActive ? <Crosshair /> : null;
}

<VirtualCamera name="aim-down-sights" priority={20} active={aiming}>
  <Hud />
</VirtualCamera>
```

## `useIsLiveVirtualCamera`

Whether the nearest `<VirtualCamera>` is fully on screen. Turns `true` only once the blend into it has finished.

```tsx
const isLive = useIsLiveVirtualCamera();
```

## `useVirtualCamera`

The camera behind the nearest `<VirtualCamera>`, with its pieces and raw `state`. Mostly needed for [custom pieces](/klipp/docs/advanced/custom-components). It has the same members as any [virtual camera](/klipp/docs/api/virtual-camera#members).

```tsx
const camera = useVirtualCamera();
camera.state; // the camera's raw state
```

## `useKlipp`

The `KlippThree` behind the nearest `<Klipp>`, which knows about every camera. It has the same [members](/klipp/docs/api/klipp#members) as `Klipp`.

```tsx
const klipp = useKlipp();

klipp.activeCameraName; // the current winner
klipp.liveCameraName;   // the camera fully on screen
klipp.isBlending;       // whether a blend is in progress
```
]]></page>
<page path="/api/events" title="Events"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/api/events
Description: React to camera switches and blends.

# Events

React to camera switches and blends.

Every camera transition is reported as an event.

| Event           | Payload                  | Fires when                                      |
| --------------- | ------------------------ | ----------------------------------------------- |
| `activated`     | `{ incoming, outgoing }` | A camera becomes the winner.                    |
| `deactivated`   | `{ outgoing }`           | A camera has fully left the screen.             |
| `blendCreated`  | `{ incoming, outgoing }` | A blend starts.                                 |
| `blendFinished` | `{ incoming }`           | A blend ends and `incoming` is fully on screen. |
| `cut`           | `{ incoming, outgoing }` | A switch happens instantly, without a blend.    |

`incoming` and `outgoing` are camera names. `outgoing` is `null` for the very first camera.

A cut happens for the first camera ever shown, and for any blend with `time: 0`. A `time: 0` switch fires `blendCreated` too, but never `blendFinished`.

## Filtering per camera

Klipp hears every transition. A camera hears only the ones it is part of:

| Event                        | Passed on when this camera is |
| ---------------------------- | ----------------------------- |
| `activated`, `blendFinished` | `incoming`                    |
| `deactivated`                | `outgoing`                    |
| `blendCreated`, `cut`        | `incoming` or `outgoing`      |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
klipp.addEventListener('activated', (e) => console.log(`${e.outgoing} -> ${e.incoming}`));

const follow = new VirtualCamera('follow', { priority: 10 });
klipp.add(follow);
follow.addEventListener('deactivated', () => console.log('follow is off screen'));
```

```ts
klipp.addEventListener('activated', (e) => console.log(`${e.outgoing} -> ${e.incoming}`));

const follow = new VirtualCameraThree('follow', { priority: 10 });
klipp.add(follow);
follow.addEventListener('deactivated', () => console.log('follow is off screen'));
```

`<Klipp.Events>` hears every transition, and `<VirtualCamera.Events>` only its own camera's. Event names become props: `onActivated`, `onDeactivated`, `onBlendCreated`, `onBlendFinished` and `onCut`.

```tsx
<Klipp>
  <Klipp.Events onActivated={(e) => console.log(`${e.outgoing} -> ${e.incoming}`)} />

  <VirtualCamera name="follow" priority={10}>
    <Body.Follow target={playerRef} />
    <VirtualCamera.Events onDeactivated={() => console.log('follow is off screen')} />
  </VirtualCamera>
</Klipp>
```

A `<VirtualCamera>`'s `ref` is the camera, and has `addEventListener` too.
]]></page>
<page path="/body/introduction" title="Body"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/introduction
Description: Decides where the camera is.

# Body

Decides where the camera is.

A Body decides where the camera is. Where it looks is up to the [Aim](/klipp/docs/aim/introduction). Each virtual camera has at most one Body: setting another replaces it.

## Which one?

| Body                                                       | Use it for                                                                                         |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`HardLockToTarget`](/klipp/docs/body/hard-lock-to-target) | Placing the camera exactly on a target: first person, a camera mounted on something, a fixed spot. |
| [`Follow`](/klipp/docs/body/follow)                        | Keeping a fixed offset from a target: chase cameras, third person.                                 |
| [`OrbitFollow`](/klipp/docs/body/orbit-follow)             | Letting the user orbit and zoom around a target: third person, inspecting an object.               |
| [`PositionComposer`](/klipp/docs/body/position-composer)   | Keeping a target at a spot on screen: top-down, side-scrollers, anything with a fixed rotation.    |
| [`CameraControls`](/klipp/docs/body/camera-controls)       | Letting the user orbit, pan and zoom. three.js and React only.                                     |

Without a Body the camera stays at its starting position, [`initialState`](/klipp/docs/api/virtual-camera#initialstate).

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { FollowBody, HardLookAtAim, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position and player.rotation up to date

camera.body = new FollowBody(player, { offset: [0, 3, 8], damping: 0.5 });
camera.aim = new HardLookAtAim(player);
```

```ts
import { Vector3 } from 'three';
import { FollowBodyThree, HardLookAtAimThree } from '@pmndrs/klipp/three';

camera.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8), damping: 0.5 });
camera.aim = new HardLookAtAimThree(player);
```

```tsx
import { VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```
]]></page>
<page path="/body/hard-lock-to-target" title="HardLockToTarget"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/hard-lock-to-target
Description: Puts the camera exactly where the target is.

# HardLockToTarget

Puts the camera exactly where the target is.

Moves the camera to the target's position, with no offset. Good for first-person cameras, cameras attached to a moving object, or a camera at a fixed point.

## Settings

| Setting    | Description                                                                                                            | Default    |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- |
| `target`   | What to lock onto. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                   |            |
| `damping`  | Seconds to catch up with the target. `0` is instant. See [Damping](/klipp/docs/getting-started/core-concepts#damping). | `0`        |
| `maxSpeed` | Maximum catch-up speed, in units per second.                                                                           | `Infinity` |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { HardLockToTargetBody, RotateWithFollowTargetAim, targetPose } from '@pmndrs/klipp';

const head = targetPose.create(); // keep head.position, head.rotation and hasRotation up to date

camera.body = new HardLockToTargetBody(head);
camera.aim = new RotateWithFollowTargetAim(head);
```

```ts
import { HardLockToTargetBodyThree, RotateWithFollowTargetAimThree } from '@pmndrs/klipp/three';

camera.body = new HardLockToTargetBodyThree(head);
camera.aim = new RotateWithFollowTargetAimThree(head);
```

```tsx
<VirtualCamera name="first-person" priority={10}>
  <Body.HardLockToTarget target={headRef} />
  <Aim.RotateWithFollowTarget target={headRef} />
</VirtualCamera>
```

`ref` gives you the `HardLockToTargetBodyThree`.
]]></page>
<page path="/body/follow" title="Follow"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/follow
Description: Keeps the camera at a fixed offset from a target.

# Follow

Keeps the camera at a fixed offset from a target.

Keeps the camera at `offset` from the target. By default the offset turns with the target, so a chase camera stays behind a character as it turns.

## Settings

| Setting           | Description                                                                                                                       | Default          |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `target`          | What to follow. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                                 |                  |
| `offset`          | Where the camera sits relative to the target.                                                                                     | `[0, 0, 10]`     |
| `damping`         | Seconds to catch up with the target's position. `0` is instant. See [Damping](/klipp/docs/getting-started/core-concepts#damping). | `0`              |
| `rotationDamping` | Seconds to turn with the target, for every `bindingMode` but `worldSpace`. `0` is instant.                                        | `0`              |
| `maxSpeed`        | Maximum catch-up speed, in units per second.                                                                                      | `Infinity`       |
| `bindingMode`     | How the offset turns with the target. See below.                                                                                  | `'lockToTarget'` |

## `bindingMode`

| Mode                      | The offset turns with the target's                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `lockToTarget`            | full rotation, including roll.                                                                         |
| `lockToTargetNoRoll`      | yaw and pitch, but never rolls.                                                                        |
| `lockToTargetWithWorldUp` | yaw only. Good for flying or jumping targets.                                                          |
| `lockToTargetOnAssign`    | rotation at the moment `target` is set, the camera goes live or this mode is chosen, then stays fixed. |
| `worldSpace`              | nothing. The offset is always in world space.                                                          |

A target without rotation, like a fixed point, always uses world space.

The binding mode also tells Aims like [`HardLookAt`](/klipp/docs/aim/hard-look-at) which way is up, so with `lockToTarget` the camera rolls along with the target, and with `lockToTargetWithWorldUp` it never does.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { FollowBody, HardLookAtAim, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position and player.rotation up to date

camera.body = new FollowBody(player, { offset: [0, 3, 8], damping: 0.5 });
camera.aim = new HardLookAtAim(player);
```

Every binding mode but `worldSpace` turns the offset with the target, so fill in `player.rotation` and set `player.hasRotation`.

**`bindingMode`**

```ts
import { FollowBody, targetPose } from '@pmndrs/klipp';

const plane = targetPose.create(); // keep plane.position and plane.rotation up to date
camera.body = new FollowBody(plane, { offset: [0, 2, 10], bindingMode: 'lockToTargetWithWorldUp' });
```

```ts
import { Vector3 } from 'three';
import { FollowBodyThree, HardLookAtAimThree } from '@pmndrs/klipp/three';

camera.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8), damping: 0.5 });
camera.aim = new HardLookAtAimThree(player);
```

**`bindingMode`**

```ts
import { Vector3 } from 'three';

camera.body = new FollowBodyThree(plane, { offset: new Vector3(0, 2, 10), bindingMode: 'lockToTargetWithWorldUp' });
```

```tsx
<VirtualCamera name="chase" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```

`ref` gives you the `FollowBodyThree`.

**`bindingMode`**

```tsx

<Body.Follow target={planeRef} offset={[0, 2, 10]} bindingMode="lockToTargetWithWorldUp" />
```
]]></page>
<page path="/body/orbit-follow" title="OrbitFollow"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/orbit-follow
Description: Lets the user orbit and zoom around a target.

# OrbitFollow

Lets the user orbit and zoom around a target.

Puts the camera on a sphere around the target, or on a surface through [three rings](#three-rings). Three [`InputAxis`](/klipp/docs/input/input-axis) pick the spot: `horizontal` goes around the target and `vertical` up and down, both in degrees, and `radial` zooms. They can be driven by the mouse, touch, the wheel and pinches through an [input controller](/klipp/docs/input/input-controller), or from code. Pair it with an Aim that looks at the same target, like [`HardLookAt`](/klipp/docs/aim/hard-look-at), for an orbit or third person camera.

The camera sits `radius × exp(radial)` away from the target. `radial` is the natural log of the zoom: `0` is `radius`, `ln 2` twice as far, `ln 0.5` half as far. That way each step of the wheel zooms by the same ratio near and far, and a pinch zooms exactly as much as the fingers spread.

To start from a specific spot, pass a `position` to the camera's [`initialState`](/klipp/docs/api/virtual-camera#initialstate). `horizontal` and `vertical` are set from its direction around the target, `radial` keeps its value. Later on, `setFromPosition(position)` and `setFromRotation(rotation)` on the body ease the camera there with the axes' damping. On `OrbitFollowBodyThree` they also take a `Vector3` and a `Quaternion`.

## Settings

| Setting                            | Description                                                                                                                                              | Default                         |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `target`                           | What to orbit. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                                                         |                                 |
| `orbitStyle`                       | `'sphere'`, or `'threeRing'` for a surface through three rings.                                                                                          | `'sphere'`                      |
| `radius`                           | Distance from the target while `radial` is `0`, for `'sphere'`. Changes ease in with the `radial` axis' `damping`.                                       | `10`                            |
| `orbits`                           | The `top`, `center` and `bottom` ring for `'threeRing'`, each a `radius` and a `height` above the target.                                                | see [Three rings](#three-rings) |
| `splineCurvature`                  | How strongly the `'threeRing'` surface curves between the rings, from `0` to `1`.                                                                        | `0`                             |
| `targetOffset`                     | Center of the orbit relative to the target, turned by `bindingMode`.                                                                                     | `[0, 0, 0]`                     |
| `bindingMode`                      | How the orbit turns with the target. See [Follow](/klipp/docs/body/follow#bindingmode).                                                                  | `'worldSpace'`                  |
| `damping`                          | Seconds to catch up with the target. See [Damping](#damping).                                                                                            | `0`                             |
| `rotationDamping`                  | Seconds to turn with the target, for every `bindingMode` but `worldSpace`.                                                                               | `0`                             |
| `maxSpeed`                         | Maximum catch-up speed, in units per second.                                                                                                             | `Infinity`                      |
| `recenteringTarget`                | What `horizontal`'s `center` is measured from when it recenters: `'trackingTarget'` from behind the target, `'axisCenter'` from the `bindingMode` frame. | `'trackingTarget'`              |
| `horizontal`, `vertical`, `radial` | Settings for each axis, like `range`, `damping` or `recentering`. Later on, change them on `body.horizontal` and the others.                             | see [Axes](#axes)               |
| `autoNormalize`                    | React only. Keep `horizontal` inside its range after each drag. `autoNormalize` on the axis elsewhere.                                                   | `false`                         |
| `debug`                            | React only. Draws the orbit in the scene. See [Debugging](/klipp/docs/debugging/introduction#orbits).                                                    | `false`                         |

## Axes

| Axis         | Range            | Center                                    | Wraps |
| ------------ | ---------------- | ----------------------------------------- | ----- |
| `horizontal` | `[-180, 180]`    | `0`, the camera on the target's `+Z` side | yes   |
| `vertical`   | `[-90, 90]`      | `0`, level with the target                | no    |
| `radial`     | `[ln 0.5, ln 2]` | `0`                                       | no    |

Every axis starts at its `center`. Dragging right with a positive `gain` turns the view right, the same way as [`PanTilt`](/klipp/docs/aim/pan-tilt).

Axes with the same `recentering.time` [recenter](/klipp/docs/input/input-axis#recentering) together: input on one of them restarts the wait on the others. With `recenteringTarget: 'trackingTarget'`, the default, `horizontal` recenters to its `center` measured from behind the target's forward, `-Z`, whatever the `bindingMode`: `0` is right behind it, `180` in front of it.

## Three rings

With `orbitStyle: 'threeRing'`, `vertical` runs from the `bottom` ring at the start of its range, through `center`, to the `top` ring at its end, and `radial` scales the whole surface. The rings let the camera come closer when it looks from above or below.

By default all three rings have a `radius` of `10`, at heights `-10`, `0` and `10`: a plain cylinder whose center ring is where the sphere starts.

## Damping

`damping` makes the camera lag behind a moving target. Going around the orbit is never delayed by it, the camera turns around the target right away. To smooth the input itself, set `damping` on the axes.

An Aim with damping, like [`RotationComposer`](/klipp/docs/aim/rotation-composer), also follows the turns of the orbit without its damping, so the target stays in place on screen while the user drags.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { HardLookAtAim, OrbitFollowBody, targetPose } from '@pmndrs/klipp';
import { InputControllerDom } from '@pmndrs/klipp/dom';

const player = targetPose.create(); // keep player.position up to date

const body = new OrbitFollowBody(player, { radius: 8, damping: 0.3, radial: { damping: 0.15 } });
camera.body = body;
camera.aim = new HardLookAtAim(player);

const orbit = { axes: { x: body.horizontal, y: body.vertical }, gain: 0.3 };
const controller = new InputControllerDom({
  mouseButtons: { left: orbit },
  touches: { one: orbit },
  wheel: { axis: body.radial, gain: 0.001, invert: true },
  pinch: { axis: body.radial, invert: true },
});
klipp.whileOnScreen(camera, () => {
  controller.connect(canvas);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update());
```

Scrolling up and spreading a pinch are positive, while zooming in makes `radial` smaller, hence `invert`.

**Recentering**

```ts
const recentering = { enabled: true, wait: 1, time: 0.5 };
body.horizontal.recentering = recentering;
body.vertical.recentering = recentering;
```

```ts
import { Vector3 } from 'three';
import { HardLookAtAimThree, OrbitFollowBodyThree } from '@pmndrs/klipp/three';

const body = new OrbitFollowBodyThree(player, {
  radius: 8,
  targetOffset: new Vector3(0, 1.5, 0),
  damping: 0.3,
  radial: { damping: 0.15 },
});
camera.body = body;
camera.aim = new HardLookAtAimThree(player);
```

Map the input as on the core.

```tsx
import { Aim, Body, InputController, VirtualCamera } from '@pmndrs/klipp/react';

const orbit = { axes: { x: 'horizontal', y: 'vertical' }, gain: 0.3 };

<VirtualCamera name="orbit" priority={10}>
  <Body.OrbitFollow target={playerRef} radius={8} damping={0.3} radial={{ damping: 0.15 }}>
    <InputController
      mouseButtons={{ left: orbit }}
      touches={{ one: orbit }}
      wheel={{ axis: 'radial', gain: 0.001, invert: true }}
      pinch={{ axis: 'radial', invert: true }}
    />
  </Body.OrbitFollow>
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```

`ref` gives you the `OrbitFollowBodyThree`. Removing an axis setting brings back its default without moving the axis.

**Recentering**

```tsx
const recentering = { enabled: true, wait: 1, time: 0.5 };

<Body.OrbitFollow target={playerRef} horizontal={{ recentering }} vertical={{ recentering }} />
```
]]></page>
<page path="/body/position-composer" title="PositionComposer"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/position-composer
Description: Moves the camera to keep a target at a spot on screen.

# PositionComposer

Moves the camera to keep a target at a spot on screen.

Moves the camera, without rotating it, so the target stays at `screenPosition` and `cameraDistance` away. With a `deadZone` the target can move freely inside it before the camera reacts.

It's made for cameras that keep a fixed rotation, like top-down or side-scrolling games, so it's usually used without an Aim. The rotation then comes from the camera's [`initialState`](/klipp/docs/api/virtual-camera#initialstate).

It works with an [orthographic camera](/klipp/docs/api/klipp#orthographic-cameras) too. The screen then spans `orthographicSize` at any distance, so `cameraDistance` only sets how far back the camera sits.

The zones react to the target's edge, not just its center, so its size matters. `klipp.setSize` keeps the screen proportions in sync with your viewport.

## Settings

| Setting              | Description                                                                                                                                                   | Default             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `target`             | What to frame. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                                                              |                     |
| `targetOffset`       | Offset from the target, in the target's own space. Use it to frame a head instead of the feet.                                                                | `[0, 0, 0]`         |
| `cameraDistance`     | Distance from the camera to the target, along the view direction.                                                                                             | `10`                |
| `screenPosition`     | Where the target should be on screen. `[0, 0]` is the center, `±1` the edges, with `+y` up.                                                                   | `[0, 0]`            |
| `deadZone`           | How far the target can drift from `screenPosition` to each side before the camera reacts, in the same units: `[0.2, 0.1]` is a box `0.4` wide and `0.2` tall. | `[0, 0]`            |
| `hardLimit`          | How far the target can ever drift from `screenPosition` to each side, even while `damping` is catching up. `[0, 0]` turns it off.                             | `[0, 0]`            |
| `depthDeadZone`      | How far the target can move toward or away from the camera before it reacts, in world units.                                                                  | `0`                 |
| `damping`            | Seconds to catch up once the target leaves the dead zone. See [Damping](/klipp/docs/getting-started/core-concepts#damping).                                   | `0`                 |
| `maxSpeed`           | Maximum catch-up speed, in units per second.                                                                                                                  | `Infinity`          |
| `lookaheadTime`      | Seconds to look ahead of a moving target. See below.                                                                                                          | `0`                 |
| `lookaheadSmoothing` | Seconds used to smooth the target's measured speed for lookahead.                                                                                             | `1`                 |
| `lookaheadIgnoreY`   | Only look ahead horizontally, handy for jumping characters.                                                                                                   | `false`             |
| `radius`             | three.js and React. The target's radius. On the core, set the target's `extent`.                                                                              |                     |
| `size`               | three.js and React. The target's box size, used instead of `radius`.                                                                                          | measured for meshes |
| `debug`              | React only. Draws the zones on screen. See [Debugging](/klipp/docs/debugging/introduction).                                                                   | `false`             |

## Lookahead

With `lookaheadTime`, the camera frames where the target is going to be instead of where it is, so fast targets get room in front of them.

## Combining with an Aim

Avoid Aims that recenter the target every frame, like `HardLookAt`: they cancel out the dead zone and `screenPosition`. Use one of these instead:

- no Aim, for a fixed rotation,
- [`RotateWithFollowTarget`](/klipp/docs/aim/rotate-with-follow-target),
- [`RotationComposer`](/klipp/docs/aim/rotation-composer) with the same `screenPosition`, and a non-zero `deadZone` on both.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { PositionComposerBody, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position up to date
player.extent.radius = 0.5; // so the zones react to its edge
camera.body = new PositionComposerBody(player, { cameraDistance: 12, deadZone: [0.3, 0.2], damping: 0.3 });
```

The target's size comes from `player.extent`: a `radius`, or a box `size` with `hasSize` set. Its rotation is only used for `targetOffset`.

**Lookahead**

```ts
camera.body = new PositionComposerBody(player, { lookaheadTime: 0.4, lookaheadIgnoreY: true });
```

```ts
import { PositionComposerBodyThree } from '@pmndrs/klipp/three';

camera.body = new PositionComposerBodyThree(player, { cameraDistance: 12, deadZone: [0.3, 0.2], damping: 0.3 });
```

For meshes, the target's size is measured from its geometry. If the shape changes (an animated skinned mesh, for example), call `recalculateSize()` to measure it again.

**Lookahead**

```ts
camera.body = new PositionComposerBodyThree(player, { lookaheadTime: 0.4, lookaheadIgnoreY: true });
```

```tsx
<VirtualCamera name="platformer" priority={10}>
  <Body.PositionComposer target={playerRef} cameraDistance={12} deadZone={[0.3, 0.2]} damping={0.3} />
</VirtualCamera>
```

For meshes, the target's size is measured from its geometry. `ref` gives you the `PositionComposerBodyThree`: if the shape changes (an animated skinned mesh, for example), call `recalculateSize()` to measure it again.

**Lookahead**

```tsx
<Body.PositionComposer target={playerRef} lookaheadTime={0.4} lookaheadIgnoreY />
```
]]></page>
<page path="/body/camera-controls" title="CameraControls"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/body/camera-controls
Description: Lets the user orbit, pan and zoom with the mouse or touch.

# CameraControls

Lets the user orbit, pan and zoom with the mouse or touch.

A user-controlled orbit camera, built on [`camera-controls`](https://github.com/yomotsu/camera-controls). It still takes part in priority and blending like any other camera. Unlike other Bodies, it controls both position and rotation, so don't add an Aim next to it.

`camera-controls` is a three.js library, so this Body exists only in integrations built on three.js.

```bash
npm install camera-controls
```

With a `target`, the camera orbits around it and follows it when it moves. Without one, it's free: orbit, pan and zoom anywhere.

> \[!NOTE] Use `initialPosition` to set the starting point. The camera's `initialState` has no effect on `CameraControls`.

## Settings

| Setting            | Description                                                                                                     | Default |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------- |
| `target`           | What to orbit around. See [Targets](/klipp/docs/getting-started/core-concepts#targets). Omit for free controls. |         |
| `initialPosition`  | Where the camera starts.                                                                                        |         |
| `enableTransition` | Animate the internal `camera-controls` calls.                                                                   | `false` |
| `impl`             | A custom `CameraControls` subclass to use instead.                                                              |         |
| `waitForBlend`     | Ignore input until the blend into this camera has finished. An option of `klipp.whileOnScreen` in three.js.     | `true`  |
| `makeDefault`      | React only. Set as r3f's `state.controls` while it accepts input.                                               | `false` |
| `regress`          | React only. Lower render quality while moving (`performance.regress()`).                                        | `false` |

`controls` is the `camera-controls` instance, for its own options like `minDistance` or `dollySpeed`, and methods like `rotateTo` or `setLookAt`.

## Usage

**three.js**

**React Three Fiber**

```ts
import { CameraControlsBodyThree } from '@pmndrs/klipp/three/camera-controls';
import { VirtualCameraThree } from '@pmndrs/klipp/three';

const body = new CameraControlsBodyThree(ball);
body.controls.minDistance = 2;
const orbit = new VirtualCameraThree('orbit', { priority: 10 });
klipp.add(orbit);
orbit.body = body;

klipp.whileOnScreen(orbit, () => {
  body.controls.connect(renderer.domElement);
  return () => body.controls.disconnect();
});
```

`whileOnScreen` connects the controls only while their camera is on screen, so several orbit cameras don't fight over the mouse.

```tsx
import { CameraControls } from '@pmndrs/klipp/react/camera-controls';

<VirtualCamera name="orbit" priority={10}>
  <CameraControls target={ballRef} minDistance={2} />
</VirtualCamera>
```

Any option of a `camera-controls` instance can be passed as a prop, and its events too: `onControlStart`, `onControl`, `onControlEnd`, `onTransitionStart`, `onUpdate`, `onWake`, `onRest` and `onSleep`.

Input only works while this camera is on screen, so you can mount several orbit cameras without them fighting over the mouse.

`ref` gives you the `CameraControlsBodyThree`.
]]></page>
<page path="/aim/introduction" title="Aim"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/aim/introduction
Description: Decides where the camera looks.

# Aim

Decides where the camera looks.

An Aim rotates the camera. It never moves it, that's the [Body](/klipp/docs/body/introduction)'s job. Each virtual camera has at most one Aim: setting another replaces it. It always runs after the Body.

## Which one?

| Aim                                                                   | Use it for                                                            |
| --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`HardLookAt`](/klipp/docs/aim/hard-look-at)                          | Always looking straight at a target.                                  |
| [`RotationComposer`](/klipp/docs/aim/rotation-composer)               | Looking at a target smoothly, with a dead zone or off-center framing. |
| [`RotateWithFollowTarget`](/klipp/docs/aim/rotate-with-follow-target) | Copying a target's rotation: first person, mounted cameras.           |
| [`PanTilt`](/klipp/docs/aim/pan-tilt)                                 | Letting the user look around with the mouse or touch.                 |

Without an Aim the camera keeps its starting rotation, [`initialState`](/klipp/docs/api/virtual-camera#initialstate).

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { FollowBody, HardLookAtAim, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position up to date

camera.body = new FollowBody(player, { offset: [0, 3, 8] });
camera.aim = new HardLookAtAim(player);
```

```ts
import { Vector3 } from 'three';
import { FollowBodyThree, HardLookAtAimThree } from '@pmndrs/klipp/three';

camera.body = new FollowBodyThree(player, { offset: new Vector3(0, 3, 8) });
camera.aim = new HardLookAtAimThree(player);
```

```tsx
import { VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';

<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} />
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```
]]></page>
<page path="/aim/hard-look-at" title="HardLookAt"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/aim/hard-look-at
Description: Always looks straight at the target.

# HardLookAt

Always looks straight at the target.

Rotates the camera so the target is always in the center of the screen. It's always instant. For a smooth look-at, use [`RotationComposer`](/klipp/docs/aim/rotation-composer) with `damping`.

Which way is up comes from the Body, for example from Follow's [`bindingMode`](/klipp/docs/body/follow#bindingmode).

## Settings

| Setting  | Description                                                                        | Default |
| -------- | ---------------------------------------------------------------------------------- | ------- |
| `target` | What to look at. See [Targets](/klipp/docs/getting-started/core-concepts#targets). |         |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { HardLookAtAim, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position up to date

camera.aim = new HardLookAtAim(player);
```

```ts
import { HardLookAtAimThree } from '@pmndrs/klipp/three';

camera.aim = new HardLookAtAimThree(player);
```

```tsx
<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
  <Aim.HardLookAt target={playerRef} />
</VirtualCamera>
```

`ref` gives you the `HardLookAtAimThree`.
]]></page>
<page path="/aim/rotation-composer" title="RotationComposer"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/aim/rotation-composer
Description: Looks at a target with a dead zone, off-center framing and damping.

# RotationComposer

Looks at a target with a dead zone, off-center framing and damping.

Rotates the camera to keep the target at `screenPosition`. With a `deadZone` the target can move freely inside it before the camera turns, and `damping` makes the turn smooth. With the default settings it behaves like [`HardLookAt`](/klipp/docs/aim/hard-look-at).

The zones react to the target's edge, not just its center, so its size matters. `klipp.setSize` keeps the screen proportions in sync with your viewport. With an [orthographic camera](/klipp/docs/api/klipp#orthographic-cameras), the screen spans `orthographicSize` at any distance.

## Settings

| Setting              | Description                                                                                                                                                  | Default             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `target`             | What to look at. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                                                           |                     |
| `targetOffset`       | Offset from the target, in the target's own space. Use it to look at a head instead of the feet.                                                             | `[0, 0, 0]`         |
| `screenPosition`     | Where the target should be on screen. `[0, 0]` is the center, `±1` the edges, with `+y` up.                                                                  | `[0, 0]`            |
| `deadZone`           | How far the target can drift from `screenPosition` to each side before the camera turns, in the same units: `[0.2, 0.1]` is a box `0.4` wide and `0.2` tall. | `[0, 0]`            |
| `hardLimit`          | How far the target can ever drift from `screenPosition` to each side, even while `damping` is catching up. `[0, 0]` turns it off.                            | `[0, 0]`            |
| `damping`            | Seconds to catch up once the target leaves the dead zone. See [Damping](/klipp/docs/getting-started/core-concepts#damping).                                  | `0`                 |
| `maxSpeed`           | Maximum turn speed, in degrees per second.                                                                                                                   | `Infinity`          |
| `lookaheadTime`      | Seconds to look ahead of a moving target.                                                                                                                    | `0`                 |
| `lookaheadSmoothing` | Seconds used to smooth the target's measured speed for lookahead.                                                                                            | `1`                 |
| `lookaheadIgnoreY`   | Only look ahead horizontally, handy for jumping characters.                                                                                                  | `false`             |
| `radius`             | three.js and React. The target's radius. On the core, set the target's `extent`.                                                                             |                     |
| `size`               | three.js and React. The target's box size, used instead of `radius`.                                                                                         | measured for meshes |
| `debug`              | React only. Draws the zones on screen. See [Debugging](/klipp/docs/debugging/introduction).                                                                  | `false`             |

## Combining with `PositionComposer`

When pairing it with [`PositionComposer`](/klipp/docs/body/position-composer), use the same `screenPosition` on both, and give both a non-zero `deadZone`. Without a dead zone on each side they cancel each other out.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { RotationComposerAim, targetPose } from '@pmndrs/klipp';

const player = targetPose.create(); // keep player.position up to date
player.extent.radius = 0.5; // so the zones react to its edge
camera.aim = new RotationComposerAim(player, { deadZone: [0.2, 0.2], damping: 0.3 });
```

The target's size comes from `player.extent`, and its rotation is only used for `targetOffset`.

```ts
import { RotationComposerAimThree } from '@pmndrs/klipp/three';

camera.aim = new RotationComposerAimThree(player, { deadZone: [0.2, 0.2], damping: 0.3 });
```

For meshes, the target's size is measured from its geometry. If the shape changes (an animated skinned mesh, for example), call `recalculateSize()` to measure it again.

```tsx
<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
  <Aim.RotationComposer target={playerRef} deadZone={[0.2, 0.2]} damping={0.3} />
</VirtualCamera>
```

For meshes, the target's size is measured from its geometry. `ref` gives you the `RotationComposerAimThree`: if the shape changes (an animated skinned mesh, for example), call `recalculateSize()` to measure it again.
]]></page>
<page path="/aim/rotate-with-follow-target" title="RotateWithFollowTarget"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/aim/rotate-with-follow-target
Description: Copies the target's rotation.

# RotateWithFollowTarget

Copies the target's rotation.

Gives the camera the same rotation as the target, as if it were glued to it. It doesn't look at the target, it only copies how the target is turned.

## Settings

| Setting    | Description                                                                                                                       | Default    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `target`   | Whose rotation to copy. Must have one; a fixed point doesn't. See [Targets](/klipp/docs/getting-started/core-concepts#targets).   |            |
| `damping`  | Seconds to catch up with the target's rotation. `0` is instant. See [Damping](/klipp/docs/getting-started/core-concepts#damping). | `0`        |
| `maxSpeed` | Maximum turn speed, in degrees per second.                                                                                        | `Infinity` |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { HardLockToTargetBody, RotateWithFollowTargetAim, targetPose } from '@pmndrs/klipp';

const head = targetPose.create(); // keep head.position, head.rotation and hasRotation up to date

camera.body = new HardLockToTargetBody(head);
camera.aim = new RotateWithFollowTargetAim(head, { damping: 0.1 });
```

Only `head.rotation` is read, and only while `head.hasRotation` is set.

```ts
import { HardLockToTargetBodyThree, RotateWithFollowTargetAimThree } from '@pmndrs/klipp/three';

camera.body = new HardLockToTargetBodyThree(head);
camera.aim = new RotateWithFollowTargetAimThree(head, { damping: 0.1 });
```

```tsx
<VirtualCamera name="first-person" priority={10}>
  <Body.HardLockToTarget target={headRef} />
  <Aim.RotateWithFollowTarget target={headRef} damping={0.1} />
</VirtualCamera>
```

`ref` gives you the `RotateWithFollowTargetAimThree`.
]]></page>
<page path="/aim/pan-tilt" title="PanTilt"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/aim/pan-tilt
Description: Lets the user look around with the mouse or touch.

# PanTilt

Lets the user look around with the mouse or touch.

Free look-around. `pan` turns the camera left and right, `tilt` up and down, both in degrees. Each one is an [`InputAxis`](/klipp/docs/input/input-axis), so it can be driven by the mouse and touch through an [input controller](/klipp/docs/input/input-controller), or from code, for example in a cutscene.

To start facing a specific direction, pass a `quaternion` to the camera's [`initialState`](/klipp/docs/api/virtual-camera#initialstate).

## Settings

| Setting         | Description                                                                                                                  | Default           |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `target`        | Makes `pan` and `tilt` relative to this target's rotation, for example a vehicle's cockpit. Omit for world space.            |                   |
| `pan`, `tilt`   | Settings for each axis, like `range`, `wrap`, `damping` or `recentering`. Later on, change them on `aim.pan` and `aim.tilt`. | see [Axes](#axes) |
| `autoNormalize` | React only. Keep `pan` inside its range after each drag while it wraps. `autoNormalize` on the axis elsewhere.               | `false`           |

## Axes

| Axis   | Range         | Center              | Wraps |
| ------ | ------------- | ------------------- | ----- |
| `pan`  | `[-180, 180]` | `0`, facing forward | yes   |
| `tilt` | `[-90, 90]`   | `0`, level          | no    |

Every axis starts at its `center`.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { PanTiltAim } from '@pmndrs/klipp';
import { InputControllerDom } from '@pmndrs/klipp/dom';

const aim = new PanTiltAim(null, { tilt: { range: [-60, 60] } });
camera.aim = aim;

const look = { axes: { x: aim.pan, y: aim.tilt }, gain: 0.15 };
const controller = new InputControllerDom({
  mouseButtons: { left: look },
  touches: { one: look },
});
klipp.whileOnScreen(camera, () => {
  controller.connect(canvas);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update()); // reads input before the cameras run
```

Pass a target to make `pan` and `tilt` relative to its rotation: `new PanTiltAim(vehicle)`.

**From code**

```ts
aim.pan.applyDelta(5); // turn right by 5°
aim.pan.setValue(0);   // face forward at once
aim.tilt.value;        // current tilt
```

More in [Input from data](/klipp/docs/input/input-from-data).

```ts
import { PanTiltAimThree } from '@pmndrs/klipp/three';
import { InputControllerDom } from '@pmndrs/klipp/dom';

const aim = new PanTiltAimThree(null, { tilt: { range: [-60, 60] } });
camera.aim = aim;

const look = { axes: { x: aim.pan, y: aim.tilt }, gain: 0.15 };
const controller = new InputControllerDom({
  mouseButtons: { left: look },
  touches: { one: look },
});
klipp.whileOnScreen(camera, () => {
  controller.connect(renderer.domElement);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update()); // reads input before the cameras run
```

Pass a target to make `pan` and `tilt` relative to its rotation: `new PanTiltAimThree(vehicle)`.

**From code**

```ts
aim.pan.applyDelta(5); // turn right by 5°
aim.pan.setValue(0);   // face forward at once
aim.tilt.value;        // current tilt
```

More in [Input from data](/klipp/docs/input/input-from-data).

Add an [`<InputController>`](/klipp/docs/input/input-controller) inside it to drive it with the mouse or touch:

```tsx
import { Aim, Body, InputController } from '@pmndrs/klipp/react';

<VirtualCamera name="first-person" priority={10}>
  <Body.HardLockToTarget target={headRef} />
  <Aim.PanTilt tilt={{ range: [-60, 60] }}>
    <InputController
      mouseButtons={{ left: { axes: { x: 'pan', y: 'tilt' }, gain: 0.15 } }}
      touches={{ one: { axes: { x: 'pan', y: 'tilt' }, gain: 0.15 } }}
    />
  </Aim.PanTilt>
</VirtualCamera>
```

`ref` gives you the `PanTiltAimThree`.

**From code**

```tsx
const aim = useRef<PanTiltAimThree>(null);

aim.current.pan.applyDelta(5); // turn right by 5°
aim.current.pan.setValue(0);   // face forward at once
aim.current.tilt.value;        // current tilt
```

More in [Input from data](/klipp/docs/input/input-from-data).
]]></page>
<page path="/extension/introduction" title="Extension"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/introduction
Description: Adjusts the lens and the shot the Body and Aim build.

# Extension

Adjusts the lens and the shot the Body and Aim build.

Extensions tweak a shot once the Body and Aim are done. You can add as many as you like to one virtual camera, and they run in the order they were added. Three are the exception. `Lens` runs first, so the Body and Aim frame with its lens. `FollowZoom` and `Confiner` run right after the Body, so the Aim frames with their field of view and from where they let the camera go. `addExtension` returns a function that removes one.

## Which one?

| Extension                                             | Use it for                                                                                 |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`CameraOffset`](/klipp/docs/extension/camera-offset) | Moving the camera off center in its own space, like an over-the-shoulder view.             |
| [`Confiner`](/klipp/docs/extension/confiner)          | Keeping the camera inside a box or a sphere, slowing down near the edge.                   |
| [`FollowZoom`](/klipp/docs/extension/follow-zoom)     | Keeping a target the same size on screen by changing the field of view, like a dolly zoom. |
| [`GroupFraming`](/klipp/docs/extension/group-framing) | Keeping several targets in view by moving the camera closer or farther.                    |
| [`Lens`](/klipp/docs/extension/lens)                  | Changing `fov`, `near` and `far`, with damping.                                            |
| [`Recomposer`](/klipp/docs/extension/recomposer)      | A final turn, dutch roll or zoom on top of the finished shot.                              |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { GroupFramingExtension, LensExtension } from '@pmndrs/klipp';

camera.addExtension(new GroupFramingExtension(members, { padding: 1 }));
const removeLens = camera.addExtension(new LensExtension({ fov: 40, fovDamping: 0.5 }));
```

```ts
import { LensExtension } from '@pmndrs/klipp';
import { GroupFramingExtensionThree, TargetGroup } from '@pmndrs/klipp/three';

camera.addExtension(new GroupFramingExtensionThree(new TargetGroup([{ target: a }, { target: b }]), { padding: 1 }));
const removeLens = camera.addExtension(new LensExtension({ fov: 40, fovDamping: 0.5 }));
```

```tsx
import { Extension } from '@pmndrs/klipp/react';

<VirtualCamera name="party" priority={10}>
  <Body.Follow target={leaderRef} offset={[0, 4, 10]} />
  <Aim.HardLookAt target={leaderRef} />
  <Extension.GroupFraming members={[{ target: aRef }, { target: bRef }]} padding={1} />
  <Extension.Lens fov={40} fovDamping={0.5} />
</VirtualCamera>
```
]]></page>
<page path="/extension/camera-offset" title="CameraOffset"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/camera-offset
Description: Moves the camera in its own space after the Body and Aim.

# CameraOffset

Moves the camera in its own space after the Body and Aim.

Moves the camera by an offset in its own space once the Body and Aim are done: right, up or back. Use it to frame a shot off center, like an over-the-shoulder view, without changing the Body.

By default the view moves with the camera, so the target slides across the screen: with `HardLookAt`, a sideways offset puts the target to one side, which is the over-the-shoulder look. With `preserveComposition`, the camera turns so its look-at target stays where the Aim put it. That keeps a composition, like a `RotationComposer` with the target on the left of the frame, while the offset changes the point of view.

The offset sits on top of the shot. Damping in the Body and Aim never picks it up, so it stays the size you set.

## Settings

| Setting               | Description                                                                                                                                                    | Default     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `offset`              | How far to move, in the camera's own space: `x` right, `y` up, `z` back.                                                                                       | `[0, 0, 0]` |
| `preserveComposition` | Turn the camera so its look-at target keeps the place the Aim gave it on screen. Needs an Aim that looks at a target, like `RotationComposer` or `HardLookAt`. | `false`     |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { CameraOffsetExtension } from '@pmndrs/klipp';

const shoulder = new CameraOffsetExtension({ offset: [0.8, 0.2, 0] });
camera.addExtension(shoulder);

// any time later
shoulder.offset[0] = aiming ? 0.8 : 0;
```

```ts
import { Vector3 } from 'three';
import { CameraOffsetExtensionThree } from '@pmndrs/klipp/three';

const shoulder = new CameraOffsetExtensionThree({ offset: new Vector3(0.8, 0.2, 0) });
camera.addExtension(shoulder);
```

```tsx
<VirtualCamera name="shoulder" priority={10}>
  <Body.OrbitFollow target={playerRef} radius={4} />
  <Aim.HardLookAt target={playerRef} />
  <Extension.CameraOffset offset={[0.8, 0.2, 0]} />
</VirtualCamera>
```

To move the point of view and keep the framing, pair it with a composer:

```tsx
<Aim.RotationComposer target={playerRef} screenPosition={[-0.4, 0.1]} />
<Extension.CameraOffset offset={[1.2, 0.4, 0]} preserveComposition />
```

`ref` gives you the `CameraOffsetExtensionThree`.
]]></page>
<page path="/extension/confiner" title="Confiner"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/confiner
Description: Keeps the camera inside a box or a sphere.

# Confiner

Keeps the camera inside a box or a sphere.

Keeps the camera inside a box or a sphere, like a room it must not leave. Inside, nothing changes. When the Body puts the camera outside, it moves to the closest point on the edge. With `slowingDistance`, it eases into the edge instead: within that distance of it, the camera moves less the farther the Body pushes it, so it slides up to the wall without a bump.

It runs right after the Body, before the Aim, so the Aim looks from where the camera ends up. A Body with damping stays at the edge while its target is outside, and moves back in once the target returns.

## Settings

| Setting           | Description                                                                                                                                                                                                   | Default |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `bounds`          | The box, `[minX, minY, minZ, maxX, maxY, maxZ]`, or the sphere, `{ center, radius }`. In three.js and React also a `Box3` or a `Sphere`, read every frame. `null` or an empty box or sphere confines nothing. |         |
| `slowingDistance` | Width of the zone inside the edge where the camera slows down, in world units. `0` stops it at the edge.                                                                                                      | `0`     |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { ConfinerExtension } from '@pmndrs/klipp';

camera.addExtension(new ConfinerExtension([-10, 0.5, -10, 10, 6, 10], { slowingDistance: 1 }));
```

```ts
import { Box3, Vector3 } from 'three';
import { ConfinerExtensionThree } from '@pmndrs/klipp/three';

const room = new Box3(new Vector3(-10, 0.5, -10), new Vector3(10, 6, 10));
camera.addExtension(new ConfinerExtensionThree(room, { slowingDistance: 1 }));
```

```tsx
<VirtualCamera name="room" priority={10}>
  <Body.OrbitFollow target={playerRef} radius={8} />
  <Aim.HardLookAt target={playerRef} />
  <Extension.Confiner bounds={room} slowingDistance={1} />
</VirtualCamera>
```

`ref` gives you the `ConfinerExtensionThree`.
]]></page>
<page path="/extension/follow-zoom" title="FollowZoom"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/follow-zoom
Description: Keeps a target the same size on screen by changing the field of view.

# FollowZoom

Keeps a target the same size on screen by changing the field of view.

Changes the field of view so the shot stays `width` wide at the target's distance. As the target moves closer or farther, it keeps its size on screen. Move the camera toward the target at the same time for a dolly zoom: the target stays put while the background stretches.

It runs right after the Body, before the Aim, so the Aim, like `RotationComposer`, frames with its field of view. Its `target` is usually the one the Aim looks at.

With an [orthographic camera](/klipp/docs/api/klipp#orthographic-cameras), distance doesn't change how big the target looks, so it sets `orthographicSize` to show `width` across instead, and `fovRange` doesn't apply.

## Settings

| Setting    | Description                                                                                                                      | Default   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `target`   | What to keep the same size. See [Targets](/klipp/docs/getting-started/core-concepts#targets).                                    |           |
| `width`    | How wide the shot is at the target's distance, in world units.                                                                   | `2`       |
| `damping`  | Seconds to settle on a new field of view or orthographic size. See [Damping](/klipp/docs/getting-started/core-concepts#damping). | `1`       |
| `fovRange` | Lowest and highest field of view it sets, `[min, max]` in degrees, within `[1, 179]`.                                            | `[3, 60]` |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { FollowZoomExtension, HardLookAtAim } from '@pmndrs/klipp';

camera.aim = new HardLookAtAim(player);
camera.addExtension(new FollowZoomExtension(player, { width: 3, damping: 0.5 }));
```

```ts
import { FollowZoomExtensionThree, HardLookAtAimThree } from '@pmndrs/klipp/three';

camera.aim = new HardLookAtAimThree(player);
camera.addExtension(new FollowZoomExtensionThree(player, { width: 3, damping: 0.5 }));
```

```tsx
<VirtualCamera name="track" priority={10}>
  <Body.HardLockToTarget target={[0, 2, 20]} />
  <Aim.HardLookAt target={playerRef} />
  <Extension.FollowZoom target={playerRef} width={3} damping={0.5} />
</VirtualCamera>
```

`ref` gives you the `FollowZoomExtensionThree`.
]]></page>
<page path="/extension/group-framing" title="GroupFraming"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/group-framing
Description: Moves the camera closer or farther to keep several targets in view.

# GroupFraming

Moves the camera closer or farther to keep several targets in view.

Keeps every member on screen. It places the camera in line with the group's center, along the camera's current view direction, at the distance where every member fits. By default it never moves the camera closer than the Body placed it; with `fitMode: 'rigid'` it always sits at exactly that distance, so it also moves in as the group gets smaller.

With an [orthographic camera](/klipp/docs/api/klipp#orthographic-cameras), distance doesn't change what's in view, so it fits the group by `orthographicSize` instead. The camera keeps the distance the Body gave, and only backs away when a member would end up in front of the near plane. By default it never goes below the size from the lens, so give it one with [`Lens`](/klipp/docs/extension/lens); with `fitMode: 'rigid'` it always uses exactly the size that fits.

It doesn't rotate the camera, so pair it with an Aim that already looks at the group. `klipp.setSize` keeps the viewport size in sync.

## Settings

| Setting               | Description                                                                                                                                                                        | Default                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `members`             | The targets to keep in view. See below.                                                                                                                                            |                           |
| `positionMode`        | How the group's center, which the camera lines up with, is computed: `'groupCenter'` (center of the bounds) or `'groupAverage'` (weighted average of positions).                   | `'groupCenter'`           |
| `padding`             | Extra space around the members, in world units.                                                                                                                                    | `0`                       |
| `fitMode`             | `'ceiling'` never moves the camera closer than the Body placed it, or for an orthographic camera never goes below the size from the lens. `'rigid'` always fits the group exactly. | `'ceiling'`               |
| `framingMode`         | Which screen dimensions to fit: `'horizontal'`, `'vertical'` or `'horizontalAndVertical'`.                                                                                         | `'horizontalAndVertical'` |
| `minDistance`         | Closest the camera may get to the group, for a perspective camera.                                                                                                                 | `0`                       |
| `maxDistance`         | Farthest `GroupFraming` will move the camera away from the group, for a perspective camera.                                                                                        | `Infinity`                |
| `minOrthographicSize` | Smallest `orthographicSize` it fits the group with, for an orthographic camera.                                                                                                    | `0`                       |
| `maxOrthographicSize` | Largest `orthographicSize` it fits the group with, for an orthographic camera.                                                                                                     | `Infinity`                |
| `damping`             | Seconds to catch up with the right distance or size. See [Damping](/klipp/docs/getting-started/core-concepts#damping).                                                             | `0`                       |
| `maxSpeed`            | Maximum catch-up speed, in units per second.                                                                                                                                       | `Infinity`                |
| `screenPosition`      | Shifts the view without moving the camera, for example to leave room for UI. `[0, 0]` is centered.                                                                                 | `[0, 0]`                  |
| `debug`               | React only. Draws the padding on screen. See [Debugging](/klipp/docs/debugging/introduction).                                                                                      | `false`                   |

## Members

| Field                | Description                                                                                       | Default             |
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------- |
| `target`             | three.js and React. The member. See [Targets](/klipp/docs/getting-started/core-concepts#targets). |                     |
| `position`, `extent` | Core only. The member's position and size, which you keep up to date.                             |                     |
| `weight`             | Influence on the center in `'groupAverage'` mode.                                                 | `1`                 |
| `radius`             | three.js and React. The member's radius, so its edge stays in view instead of its center.         | `0`                 |
| `size`               | three.js and React. The member's box size, used instead of `radius`.                              | measured for meshes |
| `resolved`           | Core only. Set to `false` to skip the member, for example while it isn't loaded yet.              | `true`              |

## Usage

**Core**

**three.js**

**React Three Fiber**

Members are plain data you keep up to date:

```ts
import { vec3 } from 'math';
import { GroupFramingExtension, groupFraming } from '@pmndrs/klipp';

const a = groupFraming.createMember();
const b = groupFraming.createMember();
b.extent.radius = 2;
camera.addExtension(new GroupFramingExtension([a, b], { padding: 1, damping: 0.5 }));

// every frame, before klipp.update
vec3.copy(a.position, aPosition);
vec3.copy(b.position, bPosition);
```

Members are a `TargetGroup`:

```ts
import { GroupFramingExtensionThree, TargetGroup } from '@pmndrs/klipp/three';

const group = new TargetGroup([{ target: a }, { target: b, radius: 2 }], 'groupCenter');
camera.addExtension(new GroupFramingExtensionThree(group, { padding: 1, damping: 0.5 }));
```

For meshes, member sizes are measured from their geometry. If a member's shape changes, call `recalculateSize()` to measure it again.

```tsx
<VirtualCamera name="party" priority={10}>
  <Body.Follow target={leaderRef} offset={[0, 4, 10]} />
  <Aim.HardLookAt target={leaderRef} />
  <Extension.GroupFraming
    members={[{ target: aRef }, { target: bRef, radius: 2 }]}
    padding={1}
    damping={0.5}
  />
</VirtualCamera>
```

For meshes, member sizes are measured from their geometry. `ref` gives you the `GroupFramingExtensionThree`: if a member's shape changes, call `recalculateSize()` to measure it again.
]]></page>
<page path="/extension/lens" title="Lens"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/lens
Description: Changes fov, orthographic size, near and far, with damping.

# Lens

Changes fov, orthographic size, near and far, with damping.

Sets the camera's `fov`, `orthographicSize`, `near` and `far`. Leave one out to keep the current value. Each one can be damped separately, for effects like a speed zoom.

Set lens values through `Lens`, not on the real camera directly. Klipp writes the lens every time the shot changes, so direct changes get overwritten, for example by the next blend.

## Settings

| Setting                    | Description                                                                                                      | Default    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `fov`                      | Field of view, in degrees.                                                                                       |            |
| `orthographicSize`         | Half the view's height in world units, for an [orthographic camera](/klipp/docs/api/klipp#orthographic-cameras). |            |
| `near`                     | Near clipping plane.                                                                                             |            |
| `far`                      | Far clipping plane.                                                                                              |            |
| `fovDamping`               | Seconds to reach a new `fov`. See [Damping](/klipp/docs/getting-started/core-concepts#damping).                  | `0`        |
| `orthographicSizeDamping`  | Seconds to reach a new `orthographicSize`.                                                                       | `0`        |
| `nearDamping`              | Seconds to reach a new `near`.                                                                                   | `0`        |
| `farDamping`               | Seconds to reach a new `far`.                                                                                    | `0`        |
| `fovMaxSpeed`              | Maximum `fov` change, in degrees per second.                                                                     | `Infinity` |
| `orthographicSizeMaxSpeed` | Maximum `orthographicSize` change, in units per second.                                                          | `Infinity` |
| `nearMaxSpeed`             | Maximum `near` change, in units per second.                                                                      | `Infinity` |
| `farMaxSpeed`              | Maximum `far` change, in units per second.                                                                       | `Infinity` |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { LensExtension } from '@pmndrs/klipp';

const lens = new LensExtension({ fov: 50, fovDamping: 0.4 });
camera.addExtension(lens);

// any time later
lens.fov = boosting ? 75 : 50;
```

```ts
import { LensExtension } from '@pmndrs/klipp';

const lens = new LensExtension({ fov: 50, fovDamping: 0.4 });
camera.addExtension(lens);

// any time later
lens.fov = boosting ? 75 : 50;
```

```tsx
<VirtualCamera name="chase" priority={10}>
  <Body.Follow target={carRef} offset={[0, 2, 6]} />
  <Aim.HardLookAt target={carRef} />
  <Extension.Lens fov={boosting ? 75 : 50} fovDamping={0.4} />
</VirtualCamera>
```

`ref` gives you the `LensExtension`. To change the lens every frame without re-rendering, set its fields directly:

```tsx
const lens = useRef<LensExtension>(null);

useFrame(() => {
  lens.current.fov = 50 + speed * 0.5;
});
```
]]></page>
<page path="/extension/recomposer" title="Recomposer"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/extension/recomposer
Description: Turns, rolls and zooms the finished shot.

# Recomposer

Turns, rolls and zooms the finished shot.

A final touch on a shot the Body and Aim already built: turn it a little, roll it into a dutch angle, or zoom in. The Body and Aim keep working as they are, so the camera still follows and frames its targets, with the change on top. Animate the settings for effects like a slow dutch in a cutscene.

`zoomScale` scales the field of view, or the orthographic size, the shot has when it runs, for example from `Lens` or `FollowZoom`. With an orthographic camera, add it after `GroupFraming` to scale the size it fits too.

## Settings

| Setting     | Description                                                                                                                                                  | Default |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `tilt`      | Turns the camera around its own horizontal axis, in degrees. Positive looks down, like [`PanTilt`](/klipp/docs/aim/pan-tilt).                                | `0`     |
| `pan`       | Turns the camera around `referenceUp`, in degrees. Positive turns right, like `PanTilt`.                                                                     | `0`     |
| `dutch`     | Rolls the camera around its view direction, in degrees. Positive leans it to the right.                                                                      | `0`     |
| `zoomScale` | Multiplies the field of view and `orthographicSize`: below `1` zooms in, above `1` zooms out. Never below `0.01`, and the field of view stays at most `179`. | `1`     |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { RecomposerExtension } from '@pmndrs/klipp';

const recomposer = new RecomposerExtension({ dutch: 12, zoomScale: 0.9 });
camera.addExtension(recomposer);

// any time later
recomposer.dutch = 12 * Math.sin(time);
```

```ts
import { RecomposerExtension } from '@pmndrs/klipp';

const recomposer = new RecomposerExtension({ dutch: 12, zoomScale: 0.9 });
camera.addExtension(recomposer);
```

```tsx
<VirtualCamera name="villain" priority={10}>
  <Body.HardLockToTarget target={[0, 2, 6]} />
  <Aim.HardLookAt target={villainRef} />
  <Extension.Recomposer dutch={12} zoomScale={0.9} />
</VirtualCamera>
```

`ref` gives you the `RecomposerExtension`.
]]></page>
<page path="/noise/introduction" title="Noise"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/noise/introduction
Description: Adds camera shake on top of the shot.

# Noise

Adds camera shake on top of the shot.

Noise shakes the camera on top of everything else, so the shot stays framed correctly underneath. You can add as many as you like to one virtual camera. Noise runs after every Extension, and `addNoise` returns a function that removes one.

## Which one?

| Noise                                                                     | Use it for                                                |
| ------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`BasicMultiChannelPerlin`](/klipp/docs/noise/basic-multi-channel-perlin) | Continuous shake: handheld cameras, engines, earthquakes. |
| [`ImpulseListener`](/klipp/docs/impulse/introduction)                     | One-off shakes from events: explosions, hits, recoil.     |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { BasicMultiChannelPerlinNoise } from '@pmndrs/klipp';

camera.addNoise(new BasicMultiChannelPerlinNoise({ positionAmplitude: [0.1, 0.1, 0], rotationAmplitude: [0.5, 0.5, 0] }));
```

```ts
import { Vector3 } from 'three';
import { BasicMultiChannelPerlinNoiseThree } from '@pmndrs/klipp/three';

camera.addNoise(new BasicMultiChannelPerlinNoiseThree({ positionAmplitude: new Vector3(0.1, 0.1, 0), rotationAmplitude: new Vector3(0.5, 0.5, 0) }));
```

```tsx
import { Noise } from '@pmndrs/klipp/react';

<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} />
  <Aim.HardLookAt target={playerRef} />
  <Noise.BasicMultiChannelPerlin positionAmplitude={[0.1, 0.1, 0]} rotationAmplitude={[0.5, 0.5, 0]} />
</VirtualCamera>
```
]]></page>
<page path="/noise/basic-multi-channel-perlin" title="BasicMultiChannelPerlin"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/noise/basic-multi-channel-perlin
Description: Smooth, continuous camera shake.

# BasicMultiChannelPerlin

Smooth, continuous camera shake.

Smooth, random shake on each position and rotation axis, relative to the camera: X is left/right, Y is up/down, Z is forward/back. Nothing shakes until you set an amplitude.

## Settings

| Setting             | Description                                                               | Default     |
| ------------------- | ------------------------------------------------------------------------- | ----------- |
| `positionAmplitude` | How far the camera moves on each axis.                                    | `[0, 0, 0]` |
| `positionFrequency` | How fast the position shakes on each axis.                                | `[1, 1, 1]` |
| `rotationAmplitude` | How far the camera turns on each axis, in degrees.                        | `[0, 0, 0]` |
| `rotationFrequency` | How fast the rotation shakes on each axis.                                | `[1, 1, 1]` |
| `amplitudeGain`     | Multiplies all amplitudes. Set to `0` to turn the shake off.              | `1`         |
| `frequencyGain`     | Multiplies all frequencies.                                               | `1`         |
| `amplitudeDamping`  | Seconds to fade to a new `amplitudeGain`, instead of switching instantly. | `0`         |
| `seed`              | Same seed, same shake. Read once on creation.                             | random      |

## Fading in and out

Change `amplitudeGain` with `amplitudeDamping` set, and the shake fades smoothly instead of starting or stopping abruptly.

## Layering

For a slow sway plus a fast jitter, add two of them with different settings.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { BasicMultiChannelPerlinNoise } from '@pmndrs/klipp';

const shake = new BasicMultiChannelPerlinNoise({
  positionAmplitude: [0.05, 0.05, 0],
  rotationAmplitude: [0.3, 0.3, 0],
  frequencyGain: 2,
});
camera.addNoise(shake);
```

**Fading in and out**

```ts
shake.amplitudeDamping = 0.5;
shake.amplitudeGain = engineRunning ? 1 : 0;
```

**Layering**

```ts
camera.addNoise(new BasicMultiChannelPerlinNoise({ rotationAmplitude: [1, 1, 0], frequencyGain: 0.3 }));
camera.addNoise(new BasicMultiChannelPerlinNoise({ positionAmplitude: [0.02, 0.02, 0], frequencyGain: 8 }));
```

```ts
import { Vector3 } from 'three';
import { BasicMultiChannelPerlinNoiseThree } from '@pmndrs/klipp/three';

const shake = new BasicMultiChannelPerlinNoiseThree({
  positionAmplitude: new Vector3(0.05, 0.05, 0),
  rotationAmplitude: new Vector3(0.3, 0.3, 0),
  frequencyGain: 2,
});
camera.addNoise(shake);
```

**Fading in and out**

```ts
shake.amplitudeDamping = 0.5;
shake.amplitudeGain = engineRunning ? 1 : 0;
```

**Layering**

```ts
camera.addNoise(new BasicMultiChannelPerlinNoiseThree({ rotationAmplitude: new Vector3(1, 1, 0), frequencyGain: 0.3 }));
camera.addNoise(new BasicMultiChannelPerlinNoiseThree({ positionAmplitude: new Vector3(0.02, 0.02, 0), frequencyGain: 8 }));
```

```tsx
<Noise.BasicMultiChannelPerlin
  positionAmplitude={[0.05, 0.05, 0]}
  rotationAmplitude={[0.3, 0.3, 0]}
  frequencyGain={2}
/>
```

`ref` gives you the `BasicMultiChannelPerlinNoiseThree`.

**Fading in and out**

```tsx
<Noise.BasicMultiChannelPerlin
  positionAmplitude={[0.1, 0.1, 0]}
  amplitudeGain={engineRunning ? 1 : 0}
  amplitudeDamping={0.5}
/>
```

**Layering**

```tsx
<Noise.BasicMultiChannelPerlin rotationAmplitude={[1, 1, 0]} frequencyGain={0.3} />
<Noise.BasicMultiChannelPerlin positionAmplitude={[0.02, 0.02, 0]} frequencyGain={8} />
```
]]></page>
<page path="/impulse/introduction" title="Impulse"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/impulse/introduction
Description: One-off camera shakes from events like explosions and hits.

# Impulse

One-off camera shakes from events like explosions and hits.

Fire an impulse from anywhere in your game, and every camera listening to it reacts. Impulses live in an `ImpulseField`. The shared `impulseField` is enough unless you want separate event streams:

```ts
import { impulseField, ImpulseShapes } from '@pmndrs/klipp';

function onExplosion(position: [number, number, number]) {
  impulseField.generate({
    position,
    direction: [0, 0.5, 0],
    shape: ImpulseShapes.explosion,
    radius: 5,
    dissipationDistance: 15,
  });
}
```

A camera reacts once it has an `ImpulseListener`, a [Noise](/klipp/docs/noise/introduction).

## Generating an impulse

| Option                | Description                                                                                                             | Default              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `position`            | Where the impulse happens, in world space.                                                                              |                      |
| `direction`           | Which way, and how far, the camera gets pushed at the peak. A bigger vector is a stronger kick.                         | `[0, 0, 0]`          |
| `shape`               | How the strength changes over time: `ImpulseShapes.recoil`, `bump`, `explosion`, `rumble`, or your own `(t) => number`. | `ImpulseShapes.bump` |
| `duration`            | Length in seconds.                                                                                                      | `0.4`                |
| `radius`              | Distance from `position` where the impulse is felt at full strength.                                                    | `0`                  |
| `dissipationDistance` | Distance beyond `radius` over which it fades out. `0` means it's felt everywhere.                                       | `0`                  |
| `propagationSpeed`    | How fast it travels, in units per second, so faraway cameras feel it later.                                             | `Infinity`           |
| `channel`             | Bitmask to target specific listeners. See `channelMask` below.                                                          | `1`                  |

## Listener settings

| Setting       | Description                                                                  | Default        |
| ------------- | ---------------------------------------------------------------------------- | -------------- |
| `gain`        | Multiplies the impulse strength. `0` mutes this listener.                    | `1`            |
| `shake`       | Adds a rattle on top of the push. See below.                                 |                |
| `cameraSpace` | Treat `direction` relative to the camera instead of the world. See below.    | `false`        |
| `channelMask` | Only react to impulses where `channel & channelMask` is not `0`.             | `1`            |
| `field`       | A separate `ImpulseField` to listen to instead of the shared `impulseField`. | `impulseField` |

## Adding a rattle

An impulse on its own only pushes the camera. `shake` adds rotation and jitter that grows and fades with it. It's a [`BasicMultiChannelPerlin`](/klipp/docs/noise/basic-multi-channel-perlin) whose `amplitudeGain` follows the impulse strength.

## Camera-relative impulses

By default `direction` is in world space, which suits explosions: the camera gets pushed away from where it happened. For recoil or a landing thump, use `cameraSpace` so the same `direction` always kicks the same way on screen.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { ImpulseListenerNoise } from '@pmndrs/klipp';

camera.addNoise(new ImpulseListenerNoise());
```

**Adding a rattle**

```ts
import { BasicMultiChannelPerlinNoise } from '@pmndrs/klipp';

const shake = new BasicMultiChannelPerlinNoise({ positionAmplitude: [0.1, 0.1, 0.1], rotationAmplitude: [4, 4, 4] });
camera.addNoise(new ImpulseListenerNoise({ shake }));
```

**Camera-relative**

```ts
impulseField.generate({ position: [0, 0, 0], direction: [0, 0.3, 0.1], shape: ImpulseShapes.recoil });

camera.addNoise(new ImpulseListenerNoise({ cameraSpace: true }));
```

```ts
import { ImpulseListenerNoise } from '@pmndrs/klipp';

camera.addNoise(new ImpulseListenerNoise());
```

**Adding a rattle**

```ts
import { Vector3 } from 'three';
import { BasicMultiChannelPerlinNoiseThree } from '@pmndrs/klipp/three';

const shake = new BasicMultiChannelPerlinNoiseThree({ positionAmplitude: new Vector3(0.1, 0.1, 0.1), rotationAmplitude: new Vector3(4, 4, 4) });
camera.addNoise(new ImpulseListenerNoise({ shake }));
```

**Camera-relative**

```ts
impulseField.generate({ position: [0, 0, 0], direction: [0, 0.3, 0.1], shape: ImpulseShapes.recoil });

camera.addNoise(new ImpulseListenerNoise({ cameraSpace: true }));
```

```tsx
import { Noise } from '@pmndrs/klipp/react';

<VirtualCamera name="follow" priority={10}>
  <Body.Follow target={playerRef} offset={[0, 3, 8]} />
  <Aim.HardLookAt target={playerRef} />
  <Noise.ImpulseListener />
</VirtualCamera>
```

`ref` gives you the `ImpulseListenerNoise`.

> \[!NOTE] With `frameloop="demand"`, call `invalidate()` after `generate()`. See [On-demand rendering](/klipp/docs/advanced/on-demand-rendering).

**Adding a rattle**

`shake` takes the noise's settings instead of the noise itself:

```tsx
<Noise.ImpulseListener shake={{ positionAmplitude: [0.1, 0.1, 0.1], rotationAmplitude: [4, 4, 4] }} />
```

**Camera-relative**

```tsx
<Noise.ImpulseListener cameraSpace />
```
]]></page>
<page path="/input/introduction" title="Input"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/input/introduction
Description: Mouse, touch, wheel and pinch input for cameras, or your own data.

# Input

Mouse, touch, wheel and pinch input for cameras, or your own data.

Some pieces can be controlled by the user, like [`PanTilt`](/klipp/docs/aim/pan-tilt) or [`OrbitFollow`](/klipp/docs/body/orbit-follow). They expose **axes** (`pan` and `tilt`, or `horizontal`, `vertical` and `radial`), and an [input controller](/klipp/docs/input/input-controller) maps mouse and touch drags, the wheel and pinches onto those axes.

Each axis is an [`InputAxis`](/klipp/docs/input/input-axis), a value with limits, wrapping, damping and optional recentering. You can also drive an axis from your own code, for example in a cutscene, see [Input from data](/klipp/docs/input/input-from-data).

## Usage

**Core**

**three.js**

**React Three Fiber**

`InputControllerDom` from `@pmndrs/klipp/dom` reads the mouse, touch and wheel, and takes the axes themselves:

```ts
import { InputControllerDom } from '@pmndrs/klipp/dom';

const look = { axes: { x: aim.pan, y: aim.tilt } };
const controller = new InputControllerDom({
  mouseButtons: { right: look },
  touches: { one: look },
});
klipp.whileOnScreen(camera, () => {
  controller.connect(canvas);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update()); // reads input before the cameras run
```

Without a DOM, feed the axes from any source, see [Input from data](/klipp/docs/input/input-from-data).

`InputControllerDom` from `@pmndrs/klipp/dom` reads the mouse, touch and wheel, and takes the axes themselves:

```ts
import { InputControllerDom } from '@pmndrs/klipp/dom';

const look = { axes: { x: aim.pan, y: aim.tilt } };
const controller = new InputControllerDom({
  mouseButtons: { right: look },
  touches: { one: look },
});
klipp.whileOnScreen(camera, () => {
  controller.connect(renderer.domElement);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update()); // reads input before the cameras run
```

An `<InputController>` placed inside the piece finds its axes by name:

```tsx
import { Aim, InputController } from '@pmndrs/klipp/react';

<VirtualCamera name="look-around" priority={10}>
  <Aim.PanTilt>
    <InputController
      mouseButtons={{ right: { axes: { x: 'pan', y: 'tilt' } } }}
      touches={{ one: { axes: { x: 'pan', y: 'tilt' } } }}
    />
  </Aim.PanTilt>
</VirtualCamera>
```
]]></page>
<page path="/input/input-controller" title="InputController"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/input/input-controller
Description: Maps mouse, touch, wheel and pinch input onto a piece's axes.

# InputController

Maps mouse, touch, wheel and pinch input onto a piece's axes.

Maps mouse buttons, finger counts, the wheel and pinches onto axes. On the core and in three.js it's an `InputControllerDom` from `@pmndrs/klipp/dom` that takes the axes themselves. In React, `<InputController>` finds them by name in the piece it's placed in. Placed directly in a `<VirtualCamera>`, it finds them in any of the camera's pieces.

## Settings

| Setting               | Description                                                                                                                                                                                            | Default                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| `mouseButtons`        | What each mouse button drives: `{ left, right, middle }`.                                                                                                                                              |                             |
| `touches`             | What each finger count drives: `{ one, two, three }`.                                                                                                                                                  |                             |
| `wheel`               | What the mouse wheel drives. Scrolling up is positive, like spreading a pinch.                                                                                                                         |                             |
| `pinch`               | What a pinch drives, with two fingers or on a trackpad, as the change in `ln(scale)`. Spreading is positive.                                                                                           |                             |
| `enabled`             | Turns input on or off.                                                                                                                                                                                 | `true`                      |
| `suppressContextMenu` | Disable the right-click menu on the canvas. On `inputSystem` on the core and in three.js.                                                                                                              | `false`                     |
| `interactiveArea`     | Only take drags, scrolls and pinches that start inside part of the canvas: `{ x, y, width, height }` from `0` to `1`, measured from the top-left corner. On `inputSystem` on the core and in three.js. | whole canvas                |
| `lockTouchAxis`       | For two-finger gestures, pick either pinch or rotate instead of both. On `inputSystem` on the core and in three.js.                                                                                    | `false`                     |
| `waitForBlend`        | Ignore input until the blend into this camera has finished. An option of `klipp.whileOnScreen` on the core and in three.js.                                                                            | `true`                      |
| `target`              | React only. Something else with axes to control, or a ref to it (for example a `PanTiltAimThree`), instead of the piece it's placed in.                                                                | parent piece, or the camera |

## Mapping a source

List only the sources you use. Each button and finger count takes the same config:

```ts
{
  axes: { x: 'pan', y: 'tilt' }, // which axis receives the horizontal and vertical drag: names in React, the axes themselves elsewhere
  gain: 0.15,                    // multiplier from pixels to axis units
  invert: { y: true },           // flip one or both directions, or `true` for both
}
```

Leave `x` or `y` out to ignore that direction: `axes: { x: 'pan' }` turns only horizontal drags into input.

## Wheel and pinch

`wheel` and `pinch` each drive a single axis:

```ts
{
  axis: 'radial', // a name in React, the axis itself elsewhere
  gain: 0.002,
  invert: true,
}
```

A pinch feels the same on a touch screen and on a trackpad, and adds up to the same amount however far you are zoomed in. That suits a zoom stored as `ln` of its scale. The wheel moves in pixels, so it needs its own `gain`.

The page keeps scrolling over the canvas until `wheel` is mapped, and a trackpad pinch keeps zooming the page until `pinch` is mapped.

## Pointer lock

For mouse look without holding a button, request pointer lock on the controller's `inputSystem`. While locked, mouse movement goes to `mouseButtons.left`.

## Raw input

`input` holds this frame's raw deltas, for example `wheelDeltaY`, `pinchDelta` or `leftDx`, if you want to handle something yourself.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { InputControllerDom } from '@pmndrs/klipp/dom';

const look = { axes: { x: aim.pan, y: aim.tilt }, gain: 0.15 };
const controller = new InputControllerDom({
  mouseButtons: { right: look },
  touches: { one: look },
});
controller.inputSystem.suppressContextMenu = true;
klipp.whileOnScreen(camera, () => {
  controller.connect(canvas);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update());
```

`whileOnScreen` connects it only while its camera is on screen, so several cameras don't react to the same drag. `controller.enabled = false` keeps it connected but ignores input.

**Pointer lock**

```ts
// in a click handler
controller.inputSystem.requestPointerLock();
controller.inputSystem.exitPointerLock();
```

**Raw input**

```ts
klipp.registerUpdate(() => {
  controller.update();
  roll += controller.input.twistDelta;
});
```

```ts
import { InputControllerDom } from '@pmndrs/klipp/dom';

const look = { axes: { x: aim.pan, y: aim.tilt }, gain: 0.15 };
const controller = new InputControllerDom({
  mouseButtons: { right: look },
  touches: { one: look },
});
controller.inputSystem.suppressContextMenu = true;
klipp.whileOnScreen(camera, () => {
  controller.connect(renderer.domElement);
  return () => controller.disconnect();
});
klipp.registerUpdate(() => controller.update());
```

`whileOnScreen` connects it only while its camera is on screen, so several cameras don't react to the same drag. `controller.enabled = false` keeps it connected but ignores input.

**Pointer lock**

```ts
// in a click handler
controller.inputSystem.requestPointerLock();
controller.inputSystem.exitPointerLock();
```

**Raw input**

```ts
klipp.registerUpdate(() => {
  controller.update();
  roll += controller.input.twistDelta;
});
```

```tsx
<Aim.PanTilt>
  <InputController
    mouseButtons={{ right: { axes: { x: 'pan', y: 'tilt' }, gain: 0.15 } }}
    touches={{ one: { axes: { x: 'pan', y: 'tilt' }, gain: 0.15 } }}
    suppressContextMenu
  />
</Aim.PanTilt>
```

Input is only read while its camera is on screen. `enabled={false}` keeps it listening but ignores input; unmount it to stop listening, for example to let the page scroll over the canvas. `ref` gives you the `InputControllerDom`.

**Pointer lock**

```tsx
const controller = useRef<InputControllerDom>(null);

<InputController ref={controller} mouseButtons={{ left: { axes: { x: 'pan', y: 'tilt' } } }} />;

// in a click handler
controller.current.inputSystem.requestPointerLock();
controller.current.inputSystem.exitPointerLock();
```

**Raw input**

```tsx
useFrame(() => {
  roll += controller.current.input.twistDelta;
});
```
]]></page>
<page path="/input/input-axis" title="InputAxis"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/input/input-axis
Description: A single controllable value with limits, damping and recentering.

# InputAxis

A single controllable value with limits, damping and recentering.

An `InputAxis` is one value the user controls, like `pan` or `tilt` on [`PanTilt`](/klipp/docs/aim/pan-tilt). An [input controller](/klipp/docs/input/input-controller) feeds it drags, but you can drive it from code as well. It also works on its own: call `update(dt)` once per frame.

## Settings

| Setting         | Description                                                                                           | Default    |
| --------------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `value`         | The current value.                                                                                    | `0`        |
| `center`        | The value `recentering` returns to.                                                                   | `0`        |
| `range`         | `[min, max]` limits, or `null` for none.                                                              | `null`     |
| `wrap`          | Loop around at the edges of `range` instead of stopping.                                              | `false`    |
| `damping`       | Seconds to catch up with the input. See [Damping](/klipp/docs/getting-started/core-concepts#damping). | `0`        |
| `maxSpeed`      | Maximum change per second.                                                                            | `Infinity` |
| `recentering`   | Return to `center` after a while without input. See below.                                            | off        |
| `autoNormalize` | With `wrap` on, bring `value` back inside `range` after each drag.                                    | `false`    |

## Recentering

Once the user lets go and `wait` seconds pass without input, the value eases back to `center` over `time` seconds. Any new input cancels it.

```ts
axis.recentering = { enabled: true, wait: 1, time: 0.5 };
```

## Usage

**Core**

**three.js**

**React Three Fiber**

The axes are fields of the piece:

```ts
aim.pan.applyDelta(5); // turn by 5°
aim.pan.setValue(0);   // jump straight to 0°
aim.pan.value;         // read the current value
```

**On its own**

```ts
import { InputAxis } from '@pmndrs/klipp';

const zoom = new InputAxis({ value: 10, center: 10, range: [2, 20] });

zoom.applyDelta(-1);
zoom.update(dt);
zoom.value;
```

The axes are fields of the piece:

```ts
aim.pan.applyDelta(5); // turn by 5°
aim.pan.setValue(0);   // jump straight to 0°
aim.pan.value;         // read the current value
```

**On its own**

```ts
import { InputAxis } from '@pmndrs/klipp';

const zoom = new InputAxis({ value: 10, center: 10, range: [2, 20] });

zoom.applyDelta(-1);
zoom.update(dt);
zoom.value;
```

The axes are on the piece's `ref`:

```tsx
const aim = useRef<PanTiltAimThree>(null);

aim.current.pan.applyDelta(5); // turn by 5°
aim.current.pan.setValue(0);   // jump straight to 0°
aim.current.pan.value;         // read the current value
```
]]></page>
<page path="/input/input-from-data" title="Input from data"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/input/input-from-data
Description: Steer a camera from your own code, the network or a recording.

# Input from data

Steer a camera from your own code, the network or a recording.

An axis is plain data, so anything that produces numbers can steer a camera: your own code, an AI, another player over the network, or a recording of earlier input. None of it needs a mouse or a DOM.

## Changing an axis

| Call                | Use it for                                                                 | Recentering                      |
| ------------------- | -------------------------------------------------------------------------- | -------------------------------- |
| `applyDelta(delta)` | Moving by an amount, the way a drag does. Eases with the axis's `damping`. | Waits, since the axis is in use. |
| `held = true`       | Holding still, like a finger resting on the screen.                        | Waits while held.                |
| `setValue(value)`   | Jumping straight to a value, for a teleport or a reset.                    | Carries on. A jump isn't input.  |

Use `setValue` for jumps. Writing `value` directly doesn't last: the axis eases back to where its input left it.

## In the same frame

Feed the axes from a function passed to `registerUpdate`. It runs every frame before the cameras, so the camera answers in that same frame. While your data keeps changing on its own, return `true` from it, so on-demand rendering keeps asking for frames.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
const remote = { pan: 0, tilt: 0 }; // filled by your network code

klipp.registerUpdate(() => {
  aim.pan.applyDelta(remote.pan);
  aim.tilt.applyDelta(remote.tilt);
  remote.pan = 0;
  remote.tilt = 0;
});

aim.pan.setValue(0); // face forward again
```

**Recording and replay**

An `InputController` from `@pmndrs/klipp` reads its input from its `input` field. Copy what a live controller read each frame, then play it back into another controller with the same mapping. Here `live` is an `InputControllerDom` set up as usual, updated in the recording function:

```ts
import { InputController, type ConsumedInput } from '@pmndrs/klipp';

const frames: ConsumedInput[] = [];
klipp.registerUpdate(() => {
  live.update();
  frames.push({ ...live.input });
});

// later
const replay = new InputController(live.config);
let frame = 0;
klipp.registerUpdate(() => {
  if (frame >= frames.length) return false;
  Object.assign(replay.input, frames[frame++]);
  replay.update();
  return true;
});
```

The replay plays one recorded frame per frame.

```ts
const remote = { pan: 0, tilt: 0 }; // filled by your network code

klipp.registerUpdate(() => {
  aim.pan.applyDelta(remote.pan);
  aim.tilt.applyDelta(remote.tilt);
  remote.pan = 0;
  remote.tilt = 0;
});

aim.pan.setValue(0); // face forward again
```

**Recording and replay**

An `InputController` from `@pmndrs/klipp` reads its input from its `input` field. Copy what a live controller read each frame, then play it back into another controller with the same mapping. Here `live` is an `InputControllerDom` set up as usual, updated in the recording function:

```ts
import { InputController, type ConsumedInput } from '@pmndrs/klipp';

const frames: ConsumedInput[] = [];
klipp.registerUpdate(() => {
  live.update();
  frames.push({ ...live.input });
});

// later
const replay = new InputController(live.config);
let frame = 0;
klipp.registerUpdate(() => {
  if (frame >= frames.length) return false;
  Object.assign(replay.input, frames[frame++]);
  replay.update();
  return true;
});
```

The replay plays one recorded frame per frame.

Register the update from a component inside `<Klipp>`, and reach the axes through the piece's `ref`:

```tsx
function RemoteLook({ aim, remote }) {
  const klipp = useKlipp();

  useEffect(
    () =>
      klipp.registerUpdate(() => {
        aim.current?.pan.applyDelta(remote.pan);
        aim.current?.tilt.applyDelta(remote.tilt);
        remote.pan = 0;
        remote.tilt = 0;
      }),
    [klipp, aim, remote],
  );

  return null;
}
```

With `frameloop="demand"`, data that arrives between frames, for example in a WebSocket message, needs a nudge: call `invalidate()` after storing it.

```tsx
socket.onmessage = (message) => {
  remote.pan += message.pan;
  invalidate();
};
```

Jumps work the same way: `aim.current.pan.setValue(0)`.
]]></page>
<page path="/blending/introduction" title="Blending"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/blending/introduction
Description: Control how Klipp moves from one camera to the next.

# Blending

Control how Klipp moves from one camera to the next.

When a different camera wins, Klipp blends from the old shot to the new one. By default that takes 2 seconds with an ease-in-out curve. Set `defaultBlend` when creating Klipp, or change it later on `klipp.defaultBlend`.

## Curve or damping

A blend is one of two kinds:

```ts
{ curve: BlendCurves.easeInOut, time: 1 } // takes exactly `time` seconds
{ damping: 0.5, maxSpeed: 20 }           // eases in like a spring, see Damping
```

Use a curve for scripted, predictable transitions. Use [damping](/klipp/docs/getting-started/core-concepts#damping) for transitions that should feel physical, especially when the target camera is moving.

Set `time: 0` for an instant cut.

## Curves

| Curve                   | Feels like                                           |
| ----------------------- | ---------------------------------------------------- |
| `BlendCurves.linear`    | Constant speed.                                      |
| `BlendCurves.easeInOut` | Starts and ends gently.                              |
| `BlendCurves.easeIn`    | Leaves gently, arrives quickly.                      |
| `BlendCurves.easeOut`   | Leaves quickly, arrives gently.                      |
| `BlendCurves.cubicIn`   | Leaves gently, arrives abruptly.                     |
| `BlendCurves.cubicOut`  | Leaves abruptly, arrives gently.                     |
| `BlendCurves.cut`       | Holds the old shot, then jumps at the end of `time`. |

Any `(t) => number` function works as a curve too:

```ts
{ curve: (t) => t * t * t, time: 1 }
```

## Custom blends

`customBlends` gives specific camera pairs their own blend. `from` and `to` are camera `name`s; leave one out to match any camera.

When several entries match, the most specific one wins: `from` and `to` together, then `to` only, then `from` only, then `defaultBlend`. Change them later on `klipp.customBlends`.

## Blend hints

By default the camera moves in a straight line between the two shots. If both shots follow the same target from different sides, that line can pass right through it. Blend hints change the path:

| Hint                             | Effect                                                                                         |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `BlendHints.sphericalPosition`   | Arcs around the target instead of cutting through it.                                          |
| `BlendHints.cylindricalPosition` | Arcs around the target horizontally, moves straight vertically.                                |
| `BlendHints.ignoreTarget`        | Rotates directly between the two shots instead of keeping the target in view during the blend. |

A hint is a setting of the camera, and applies to every blend into or out of it. Combine hints with `|`.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { BlendCurves, BlendHints, Klipp, VirtualCamera } from '@pmndrs/klipp';

const klipp = new Klipp({
  defaultBlend: { curve: BlendCurves.easeInOut, time: 1 },
  customBlends: [
    { to: 'closeup', blend: { curve: BlendCurves.linear, time: 0 } },
    { from: 'intro', to: 'gameplay', blend: { damping: 0.8 } },
  ],
});
klipp.defaultBlend = { curve: BlendCurves.linear, time: 0.5 };
```

**Blend hints**

```ts
const orbit = new VirtualCamera('orbit', { priority: 10, hints: BlendHints.sphericalPosition });
klipp.add(orbit);
orbit.hints = BlendHints.sphericalPosition | BlendHints.ignoreTarget;
```

```ts
import { BlendCurves, BlendHints } from '@pmndrs/klipp';
import { KlippThree, VirtualCameraThree } from '@pmndrs/klipp/three';

const klipp = new KlippThree(camera, {
  defaultBlend: { curve: BlendCurves.easeInOut, time: 1 },
  customBlends: [
    { to: 'closeup', blend: { curve: BlendCurves.linear, time: 0 } },
    { from: 'intro', to: 'gameplay', blend: { damping: 0.8 } },
  ],
});
klipp.defaultBlend = { curve: BlendCurves.linear, time: 0.5 };
```

**Blend hints**

```ts
const orbit = new VirtualCameraThree('orbit', { priority: 10, hints: BlendHints.sphericalPosition });
klipp.add(orbit);
orbit.hints = BlendHints.sphericalPosition | BlendHints.ignoreTarget;
```

```tsx
import { BlendCurves, BlendHints } from '@pmndrs/klipp';

<Klipp
  defaultBlend={{ curve: BlendCurves.easeInOut, time: 1 }}
  customBlends={[
    { to: 'closeup', blend: { curve: BlendCurves.linear, time: 0 } },
    { from: 'intro', to: 'gameplay', blend: { damping: 0.8 } },
  ]}
>
```

**Blend hints**

```tsx
<VirtualCamera name="orbit" priority={10} hints={BlendHints.sphericalPosition | BlendHints.ignoreTarget}>
```
]]></page>
<page path="/groups/introduction" title="Camera groups"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/groups/introduction
Description: Cameras made of other cameras.

# Camera groups

Cameras made of other cameras.

A camera group is a virtual camera made of other virtual cameras. To Klipp it is one camera, with its own `name`, `priority` and `active`, and it blends in and out like any other. Inside, it decides which of its child cameras goes on screen: one at a time, with blends of its own, or a mix of several.

The child cameras belong to the group, not to Klipp: they don't take part in Klipp's priorities, and a child is on screen only while its group is. Each child is an ordinary virtual camera with a Body, an Aim and the rest.

## Which one?

| Group                                                    | Use it for                                                          |
| -------------------------------------------------------- | ------------------------------------------------------------------- |
| [`MixingCamera`](/klipp/docs/groups/mixing-camera)       | Mixing cameras by weights you drive, like a cross-fade on a slider. |
| [`SequencerCamera`](/klipp/docs/groups/sequencer-camera) | Showing cameras one after another, like a cutscene.                 |

## Usage

**Core**

**three.js**

**React Three Fiber**

Add the child cameras to the group's `children`, and the group to Klipp:

```ts
import { SequencerCamera, VirtualCamera } from '@pmndrs/klipp';

const cutscene = new SequencerCamera('cutscene', { priority: 20, instructions });
cutscene.children.add(new VirtualCamera('wide'));
klipp.add(cutscene);
```

`klipp.whileOnScreen` works for a child camera too: it is on screen only while its group is.

Add `VirtualCameraThree`s to the group's `children`, so they read their targets like the cameras in Klipp:

```ts
import { SequencerCamera } from '@pmndrs/klipp';
import { VirtualCameraThree } from '@pmndrs/klipp/three';

const cutscene = new SequencerCamera('cutscene', { priority: 20, instructions });
cutscene.children.add(new VirtualCameraThree('wide'));
klipp.add(cutscene);
```

Put the `<VirtualCamera>`s inside the group:

```tsx
import { SequencerCamera, VirtualCamera } from '@pmndrs/klipp/react';

<SequencerCamera name="cutscene" priority={20} instructions={instructions}>
  <VirtualCamera name="wide">...</VirtualCamera>
  <VirtualCamera name="close">...</VirtualCamera>
</SequencerCamera>
```

Inside a group, `useIsActiveVirtualCamera` and `useIsLiveVirtualCamera` are `true` only while the group is active or live too.

## Events

Transitions between the children are dispatched on `group.children`, with the same events as klipp. The group's own transitions, into and out of it, are dispatched on the group. Each child also gets its own, like any virtual camera.
]]></page>
<page path="/groups/sequencer-camera" title="SequencerCamera"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/groups/sequencer-camera
Description: Shows its cameras one after another, like a cutscene.

# SequencerCamera

Shows its cameras one after another, like a cutscene.

Shows its child cameras one after another. Each step of `instructions` names a child, how long to hold it and how to blend into it.

Every time the sequencer becomes the active camera, it starts over and cuts to the first step: entering the sequencer is blended by Klipp already. Until then, it waits.

`next()`, `previous()` and `goTo(index)` jump to another step while the sequencer runs, for example from prev/next buttons. The jump blends in with the new step's `blend` and holds it from the start. `next()` and `previous()` wrap around only with `loop`. `restart()` cuts back to the first step.

Without `loop`, the last step stays on screen. `isFinished` turns `true` once it has been held, so you can turn the sequencer off and go back to the other cameras. While the sequencer is not the active camera, `isFinished` is `false`.

## Settings

| Setting        | Description                                                                                          | Default         |
| -------------- | ---------------------------------------------------------------------------------------------------- | --------------- |
| `instructions` | The steps, in order.                                                                                 | `[]`            |
| `loop`         | Start over after the last step's `hold`. Without it, the last step stays on screen.                  | `false`         |
| `paused`       | Keep holding the current step instead of moving on.                                                  | `false`         |
| `defaultBlend` | Blend into a step that has no `blend` of its own. See [Blending](/klipp/docs/blending/introduction). | 2 s ease-in-out |

Each step:

| Field    | Description                                                                                   |
| -------- | --------------------------------------------------------------------------------------------- |
| `camera` | Name of the child camera to show.                                                             |
| `hold`   | Seconds to stay on it. Counts once the blend into it has finished, so damped blends work too. |
| `blend`  | Blend into this camera.                                                                       |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { BlendCurves, SequencerCamera } from '@pmndrs/klipp';

const cutscene = new SequencerCamera('cutscene', {
  priority: 20,
  instructions: [
    { camera: 'wide', hold: 2 },
    { camera: 'close', hold: 1.5, blend: { curve: BlendCurves.cut, time: 0 } },
  ],
});
cutscene.children.add(wide);
cutscene.children.add(close);
klipp.add(cutscene);

// start it: it wins over the gameplay camera and starts from the first step
cutscene.active = true;
```

`cutscene.sequence.index` is the current step, `-1` until it starts. To end the cutscene, turn it off once it is finished:

```ts
if (cutscene.isFinished) cutscene.active = false;
```

```ts
import { BlendCurves, SequencerCamera } from '@pmndrs/klipp';
import { VirtualCameraThree } from '@pmndrs/klipp/three';

const cutscene = new SequencerCamera('cutscene', {
  priority: 20,
  instructions: [
    { camera: 'wide', hold: 2 },
    { camera: 'close', hold: 1.5, blend: { curve: BlendCurves.cut, time: 0 } },
  ],
});
cutscene.children.add(new VirtualCameraThree('wide'));
cutscene.children.add(new VirtualCameraThree('close'));
klipp.add(cutscene);
```

```tsx
import { BlendCurves } from '@pmndrs/klipp';
import { SequencerCamera, VirtualCamera } from '@pmndrs/klipp/react';

const instructions = [
  { camera: 'wide', hold: 2 },
  { camera: 'close', hold: 1.5, blend: { curve: BlendCurves.cut, time: 0 } },
];

<SequencerCamera name="cutscene" priority={20} active={playing} instructions={instructions}>
  <VirtualCamera name="wide">...</VirtualCamera>
  <VirtualCamera name="close">...</VirtualCamera>
</SequencerCamera>;
```

`ref` gives you the `SequencerCamera`.
]]></page>
<page path="/groups/mixing-camera" title="MixingCamera"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/groups/mixing-camera
Description: Mixes its cameras into one shot by weight.

# MixingCamera

Mixes its cameras into one shot by weight.

Mixes its child cameras into one shot. Each child's share is its weight over the sum of all weights, and a weight of `0` or less leaves the child out. With one weighted child, the shot is that child's.

Unlike a blend, nothing here runs on a timer: you set the weights, every frame if you like, from a slider, a distance or a speed. Mixing works the same way as a blend at that point, so [blend hints](/klipp/docs/blending/introduction) on the children apply.

The child with the highest weight is the live one: transitions on `children` follow it. Every child with a weight runs every frame, the others as their `standbyUpdate` says.

## Settings

| Setting   | Description                           | Default |
| --------- | ------------------------------------- | ------- |
| `weights` | Weight of each child camera, by name. | `{}`    |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
import { MixingCamera } from '@pmndrs/klipp';

const chase = new MixingCamera('chase', { priority: 10, weights: { calm: 1, fast: 0 } });
chase.children.add(calm);
chase.children.add(fast);
klipp.add(chase);

// every frame
chase.weights.fast = speed / maxSpeed;
chase.weights.calm = 1 - chase.weights.fast;
```

```ts
import { MixingCamera } from '@pmndrs/klipp';
import { VirtualCameraThree } from '@pmndrs/klipp/three';

const chase = new MixingCamera('chase', { priority: 10, weights: { calm: 1, fast: 0 } });
chase.children.add(new VirtualCameraThree('calm'));
chase.children.add(new VirtualCameraThree('fast'));
klipp.add(chase);
```

```tsx
import { MixingCamera, VirtualCamera } from '@pmndrs/klipp/react';

<MixingCamera name="chase" priority={10} weights={{ calm: 1 - boost, fast: boost }}>
  <VirtualCamera name="calm">...</VirtualCamera>
  <VirtualCamera name="fast">...</VirtualCamera>
</MixingCamera>;
```

To change the weights every frame without re-rendering, pass an object that lives across renders and set them on it:

```tsx
const [weights] = useState(() => ({ calm: 1, fast: 0 }));

useFrame(() => {
  weights.fast = speed / maxSpeed;
  weights.calm = 1 - weights.fast;
});

<MixingCamera name="chase" priority={10} weights={weights}>
  ...
</MixingCamera>;
```

`ref` gives you the `MixingCamera`.
]]></page>
<page path="/debugging/introduction" title="Debugging"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/debugging/introduction
Description: Visualize framing zones, camera frustums and orbits.

# Debugging

Visualize framing zones, camera frustums and orbits.

## Framing zones

[`PositionComposer`](/klipp/docs/body/position-composer), [`RotationComposer`](/klipp/docs/aim/rotation-composer) and [`GroupFraming`](/klipp/docs/extension/group-framing) can draw their zones on top of the canvas.

| Piece                                  | Draws                                                                         |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| `PositionComposer`, `RotationComposer` | `deadZone` in green, `hardLimit` in red, and a crosshair at `screenPosition`. |
| `GroupFraming`                         | `padding` in blue.                                                            |

Each element has a CSS class you can restyle: `klipp-debug-deadzone`, `klipp-debug-hardlimit`, `klipp-debug-groupframing` and `klipp-debug-crosshair`.

```css
.klipp-debug-deadzone {
  border-color: lime;
}
```

## Camera frustums

A frustum helper draws a camera in the scene, so you can see where an inactive camera is and what it's looking at. Every camera's `state` holds what it needs: `position`, `quaternion`, `fov` or `orthographicSize`, `near` and `far`. Off screen, a camera updates only now and then by default, so its frustum moves in steps. Give it [`standbyUpdate: 'always'`](/klipp/docs/api/virtual-camera#standbyupdate) to see it move smoothly.

## Orbits

An orbit helper draws where an [`OrbitFollow`](/klipp/docs/body/orbit-follow) camera can move, around the point it tracks: the circle `horizontal` moves it along in orange, the arc `vertical` moves it along in blue, and the three rings of `'threeRing'` in gray.

## Usage

**Core**

**three.js**

**React Three Fiber**

**Framing zones**

Draw them with `DebugOverlay` from `@pmndrs/klipp/dom`:

```ts
import { debugZones } from '@pmndrs/klipp';
import { DebugOverlay } from '@pmndrs/klipp/dom';

const overlay = new DebugOverlay();
overlay.connect(canvas.parentElement!);
overlay.render(debugZones.composer(body.screenPosition, body.deadZone, body.hardLimit), body.screenPosition);
```

`debugZones.composer` turns a composer's settings into the same boxes the React components draw. Call `render` again whenever the zones change, and `disconnect()` to remove the overlay. For group framing, `debugZones.groupFramingPaddingBox` gives the size of the padding boundary.

**Orbits**

`orbitFollow.point(out, body.state, body, horizontal, vertical)` gives where the camera would be at any axis values, to draw with your own renderer.

**Framing zones**

Draw them with `DebugOverlay` from `@pmndrs/klipp/dom`:

```ts
import { debugZones } from '@pmndrs/klipp';
import { DebugOverlay } from '@pmndrs/klipp/dom';

const overlay = new DebugOverlay();
overlay.connect(renderer.domElement.parentElement!);
overlay.render(debugZones.composer(body.screenPosition, body.deadZone, body.hardLimit), body.screenPosition);
```

`debugZones.composer` turns a composer's settings into the same boxes the React components draw. Call `render` again whenever the zones change, and `disconnect()` to remove the overlay. For group framing, `debugZones.groupFramingPaddingBox` gives the size of the padding boundary.

**Camera frustums**

`CameraFrustumHelperThree` is a `CameraHelper` that follows a virtual camera's `state`. Its `maxDistance` sets how far the frustum is drawn, `1` by default. Pass `klipp.orthographic` as the third argument of `sync` to draw a box for an orthographic camera:

```ts
import { CameraFrustumHelperThree } from '@pmndrs/klipp/three';

const helper = new CameraFrustumHelperThree();
scene.add(helper);

// every frame, after klipp.update
helper.sync(securityCam.state, innerWidth / innerHeight, klipp.orthographic);
```

**Orbits**

```ts
import { OrbitFollowHelperThree } from '@pmndrs/klipp/three';

const helper = new OrbitFollowHelperThree();
scene.add(helper);

// every frame, after klipp.update
helper.sync(body);
```

`helper.colors` holds the `horizontal`, `vertical` and `rings` colors.

**Framing zones**

Add the `debug` prop. The zones show while their camera is the winner:

```tsx
<Body.PositionComposer target={playerRef} deadZone={[0.4, 0.4]} hardLimit={[0.7, 0.7]} debug />
```

**Camera frustums**

Place `<CameraFrustumHelper>` inside the `<VirtualCamera>` you want to see:

```tsx
import { CameraFrustumHelper } from '@pmndrs/klipp/react';

<VirtualCamera name="security-cam" priority={5}>
  <Body.HardLockToTarget target={[5, 4, 5]} />
  <Aim.HardLookAt target={doorRef} />
  <CameraFrustumHelper color="orange" />
</VirtualCamera>
```

| Prop           | Description                             | Default           |
| -------------- | --------------------------------------- | ----------------- |
| `color`        | Color of the helper.                    | three.js defaults |
| `maxDistance`  | How far the frustum is drawn.           | `1`               |
| `hideWhenLive` | Hide it while this camera is on screen. | `true`            |

`ref` gives you the `CameraFrustumHelperThree`.

**Orbits**

Add the `debug` prop:

```tsx
<Body.OrbitFollow target={playerRef} debug />
```
]]></page>
<page path="/advanced/on-demand-rendering" title="On-demand rendering"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/advanced/on-demand-rendering
Description: Render only while the camera is moving.

# On-demand rendering

Render only while the camera is moving.

`klipp.update` returns `true` while anything is still moving (a blend, damping catching up, a shake), or the shot changed this frame. Render only then, and skip frames while the camera has settled.

Keep calling `update` every frame, even while nothing renders. It notices on its own when a target moves or a setting changes. React Three Fiber's `frameloop="demand"` is different: it stops calling frames altogether, so it needs a nudge, see its tab.

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
function frame(dt: number) {
  if (klipp.update(dt) || sceneChanged) {
    engine.camera.setTransform(klipp.shot.position, klipp.shot.quaternion);
    engine.render();
  }
}
```

```ts
renderer.setAnimationLoop(() => {
  if (klipp.update(dt) || sceneChanged) renderer.render(scene, camera);
});
```

Klipp works with `<Canvas frameloop="demand">`. It keeps requesting frames on its own while anything is still moving.

Once the camera has settled, nothing renders until something asks for a frame. Mounting, changing or unmounting Klipp's components, `<Klipp mode>` and input read by `<InputController>` do that for you. For anything else, call `invalidate()` yourself, for example after:

- moving a target imperatively, for example `target.position.set(...)` in a click handler,
- firing an impulse with `impulseField.generate()`,
- changing a component's fields through its `ref`.

```tsx
const invalidate = useThree((state) => state.invalidate);

function onClick() {
  targetRef.current.position.set(0, 0, 5);
  invalidate();
}
```

Outside a component, import `invalidate` from `@react-three/fiber` directly.
]]></page>
<page path="/advanced/custom-components" title="Custom pieces"><![CDATA[URL: https://pmndrs.github.io/klipp/docs/advanced/custom-components
Description: Write your own Body, Aim, Extension or Noise.

# Custom pieces

Write your own Body, Aim, Extension or Noise.

A piece is any object with an `update` function that runs every frame. Add your own to a camera and it runs alongside the built-in ones:

```ts
camera.body = { update };        // replaces any other Body
camera.aim = { update };         // replaces any other Aim
camera.addExtension({ update }); // stacks
camera.addNoise({ update });     // stacks
```

`addExtension` and `addNoise` return a function that removes the piece. For a Body or Aim, `setBody` and `setAim` do the same, and warn if the camera already has one.

A class with an `update` field works just as well as an object.

## The update function

```ts
(out: CameraState, dt: number, justActivated: boolean) => boolean | void
```

- `out` is the camera's state. Change it in place. Each frame starts from the state the Body and Aim left the frame before, with the camera's own lens: what Extensions and Noise change doesn't carry over to the next frame.
- `dt` is the frame time in seconds.
- `justActivated` is `true` on the camera's first frame, and again when it turns back on. Reset any smoothing here so the camera starts from the right place.
- Return `true` while your piece is still moving, so [on-demand rendering](/klipp/docs/advanced/on-demand-rendering) keeps going.

## Optional members

| Member         | What it does                                                                                                                                                                                                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `primeFrom`    | Starts the piece from the camera's `initialState` on its first activation: `(position)` on a Body, `(rotation, referenceUp)` on an Aim, `(initialState)` on an Extension.                                                                                                                                                                                                      |
| `aspect`       | Kept up to date with the viewport's width divided by its height.                                                                                                                                                                                                                                                                                                               |
| `orthographic` | Kept up to date with whether the camera being driven is [orthographic](/klipp/docs/api/klipp#orthographic-cameras).                                                                                                                                                                                                                                                            |
| `inputAxes`    | Axes an [input controller](/klipp/docs/input/input-controller) can drive, by name.                                                                                                                                                                                                                                                                                             |
| `applyAfter`   | `'start'` runs an Extension before the Body, for the lens the Body and Aim frame with. `'body'` runs it right after the Body, before the Aim, for what depends on where the Body put the camera, like a limit on where it can go. In both, only set the lens or limit the position: an offset would carry over to the next frame. `'aim'`, the default, runs it after the Aim. |

## Example: drift toward the pointer

An Extension that turns the shot slightly toward the pointer, on top of any Body and Aim. It's plain core code, so it works with every integration. `pointer` is `{ x, y }` from `-1` to `1`:

```ts title="pointerDrift.ts"
import { quat, type Euler, type Quat } from 'math';
import { Damper, type CameraPiece } from '@pmndrs/klipp';

const euler: Euler = [0, 0, 0, 'xyz'];
const rotation: Quat = [0, 0, 0, 1];

export function pointerDrift(pointer: { x: number; y: number }, strength = 0.1, damping = 0.4): CameraPiece {
  const yawDamper = new Damper();
  const pitchDamper = new Damper();
  let yaw = 0;
  let pitch = 0;

  return {
    update: (out, dt, justActivated) => {
      if (justActivated) {
        yawDamper.reset();
        pitchDamper.reset();
      }

      const targetYaw = -pointer.x * strength;
      const targetPitch = pointer.y * strength;
      yaw = yawDamper.update(yaw, targetYaw, damping, dt);
      pitch = pitchDamper.update(pitch, targetPitch, damping, dt);

      euler[0] = pitch;
      euler[1] = yaw;
      quat.multiply(out.quaternion, out.quaternion, quat.fromEuler(rotation, euler));
      return yaw !== targetYaw || pitch !== targetPitch;
    },
  };
}
```

> \[!TIP] Avoid creating objects inside the update function. Allocate scratch objects once, like `euler` and `rotation` above.

## `CameraState`

| Field                             | Type               | Description                                                                                                                                             |
| --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `position`                        | `Vec3`             | Camera position.                                                                                                                                        |
| `quaternion`                      | `Quat`             | Camera rotation.                                                                                                                                        |
| `fov`, `near`, `far`              | `number`           | Lens settings.                                                                                                                                          |
| `orthographicSize`                | `number`           | Half the view's height in world units, used by an orthographic camera instead of `fov`.                                                                 |
| `viewOffset`                      | `[number, number]` | Shifts the view without moving the camera. `[0, 0]` is centered.                                                                                        |
| `target`, `hasTarget`             | `Vec3`, `boolean`  | The point the Body follows, if any. Used by [blend hints](/klipp/docs/blending/introduction#blend-hints).                                               |
| `lookAtTarget`, `hasLookAtTarget` | `Vec3`, `boolean`  | The point the Aim looks at, if any.                                                                                                                     |
| `referenceUp`                     | `Vec3`             | Which way is up for Aims. Defaults to `[0, 1, 0]`.                                                                                                      |
| `rotationDampingBypass`           | `Quat`             | How far a Body turned the camera this frame, for example around an orbit. Aims with damping follow this turn right away. Reset to identity every frame. |

Vectors are plain arrays (`[x, y, z]`, quaternions `[x, y, z, w]`) from [`math`](https://github.com/pmndrs/math), which Klipp depends on. Use its `vec3` and `quat` functions to work with them, or copy to three.js with `vector.fromArray(out.position)`.

## Helpers

These let your pieces behave like the built-in ones. From `@pmndrs/klipp`:

| Helper                                                          | What it does                                                                                                                                                                                                                  |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Damper`                                                        | Smooths a number with a `damping` value. Call `reset()` to snap on the next update.                                                                                                                                           |
| `damping.damp`, `damping.dampVector3`, `damping.dampQuaternion` | The same as functions over state you keep yourself (`damping.createState()`, ...).                                                                                                                                            |
| `BlendDriver`                                                   | Blends between camera states you look up by name, for a piece that switches between shots: `new BlendDriver((name) => states[name])`, then `setTarget(name, { curve, time })` to start a blend and `tick(dt)` for the result. |
| `blend.setTarget`, `blend.tick`                                 | The same as functions over state you keep yourself (`blend.create()`).                                                                                                                                                        |
| `predictor.addPosition`, `predictor.predictDelta`               | Track a target's velocity and predict how far it moves in the next `time` seconds, over state from `predictor.create()`.                                                                                                      |

From `@pmndrs/klipp/three`:

| Helper                                                                     | What it does                                                                                                                                                                   |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Vector3Damper`, `QuaternionDamper`                                        | `Damper` for a three.js `Vector3` or `Quaternion`.                                                                                                                             |
| `Predictor`                                                                | The `predictor` functions for a three.js `Vector3`: `addPosition(position, dt, smoothing)` every frame, then `predictDelta(out, time)`.                                        |
| `readTargetPose(out, target, withRotation)`                                | Reads the world position, and optionally rotation, of any [target](/klipp/docs/getting-started/core-concepts#targets) into a `TargetPose`. Returns `false` if there isn't one. |
| `resolveTargetPosition(out, target)`, `resolveTargetRotation(out, target)` | The same into a three.js `Vector3` or `Quaternion`.                                                                                                                            |
| `resolveVector3(out, value)`                                               | Turns `[x, y, z]`, a number or a `Vector3` into a `Vector3`.                                                                                                                   |

## Usage

**Core**

**three.js**

**React Three Fiber**

```ts
camera.addExtension(pointerDrift(pointer)); // keep pointer.x and pointer.y up to date
```

```ts
const pointer = { x: 0, y: 0 };
renderer.domElement.addEventListener('pointermove', (e) => {
  pointer.x = (e.offsetX / renderer.domElement.clientWidth) * 2 - 1;
  pointer.y = -(e.offsetY / renderer.domElement.clientHeight) * 2 + 1;
});

camera.addExtension(pointerDrift(pointer));
```

Get the camera with [`useVirtualCamera()`](/klipp/docs/api/hooks#usevirtualcamera) and add the piece in `useEffect`: the returned function is its cleanup. r3f's `state.pointer` already has the right shape:

```tsx title="PointerDrift.tsx"
import { useEffect } from 'react';
import { useThree } from '@react-three/fiber';
import { useVirtualCamera } from '@pmndrs/klipp/react';

export function PointerDrift({ strength = 0.1, damping = 0.4 }) {
  const camera = useVirtualCamera();
  const pointer = useThree((state) => state.pointer);

  useEffect(() => camera.addExtension(pointerDrift(pointer, strength, damping)), [camera, pointer, strength, damping]);

  return null;
}

<VirtualCamera name="menu" priority={10}>
  <Body.HardLockToTarget target={[0, 2, 8]} />
  <Aim.HardLookAt target={[0, 1, 0]} />
  <PointerDrift />
</VirtualCamera>;
```
]]></page>