> For the complete documentation index, see [llms.txt](https://fehdead.gitbook.io/npc-kit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fehdead.gitbook.io/npc-kit/api/custom-camera.md).

# Custom Camera

**Fixed camera shots for your NPC's talks: dialogue scenes framed the way vanilla frames them.**

{% hint style="warning" %}
**Experimental.** The game's scripts cannot do this. Custom Camera and [Custom Motion](https://fehdead.gitbook.io/npc-kit/api/custom-motion.md) are NPC Kit's own features, built on top of the game to take your NPCs past what vanilla allows: cutscenes, more motions and movement, more complex NPCs. They may change between versions.
{% endhint %}

***

### What it is for

Custom camera was made to make **dialogue scenes** easy to build: a close shot on the face of whoever speaks, a cut to the other NPC when the line changes, a framing of two NPCs talking, a shot that shows what an NPC points at. It is how vanilla talks frame faces, now available to your own NPCs.

In the game, these shots come from the map file: every vanilla talk that frames a face plays a shot of the map's camera bank with `camerastart_7e`. No VM call creates such a shot, so NPC Kit does it for you: you give each shot as a few numbers in `cameras`, and NPC Kit builds the bank and binds it when the talk starts, with the game's own functions. Playing a shot is still yours, call by call, as in an EBP.

***

### How to use it

1. **List the shots** in the NPC's `npc.add`, under `cameras`, each by a name: the id of the NPC it frames.
2. **Play one** in `talk`, or a function it runs, with `npc.camerastart_7e(0, npc.camera("name"))`. Each new `camerastart_7e` cuts to that shot.
3. **Give the camera back** with `npc.cameraclear()` before the talk ends.

```lua
npc.add {
    id = "npckit_0012",
    map = 290,
    name = "NPCKit 0012",

    cameras = {
        ["npckit_0012"] = { eye = { 38.0, -7.5, 63.0 }, target = { 39.0, -7.57, 62.65 }, fov = 33 },
        ["npckit_0013"] = { eye = { 39.4, -7.5, 63.0 }, target = { 37.5, -7.57, 62.56 }, fov = 33 },
    },

    init = function()
        ...
    end,

    main = function()
        npc.wait(60);
    end,

    talk = function()
        npc.camerastart_7e(0, npc.camera("npckit_0012"));   -- on 0012's face
        ...
        npc.camerastart_7e(0, npc.camera("npckit_0013"));   -- cut to 0013
        ...
        npc.cameraclear();                                   -- the camera back to the player
    end,
}
```

[Two NPCs in a Scene](https://fehdead.gitbook.io/npc-kit/examples/two-npcs-in-a-scene.md) is a whole dialogue built this way.

{% hint style="info" %}
**Find the numbers with the editor.** The [NPC Kit Editor](https://fehdead.gitbook.io/npc-kit/editor.md#custom-camera-making-your-shots) frames a shot on the NPC or takes the Free Camera's view, lets you adjust every value while the shot plays, and copies the `cameras` table for you.
{% endhint %}

***

### A shot

| field    | what it is                                                              |
| -------- | ----------------------------------------------------------------------- |
| `eye`    | where the camera is: `{ x, y, z }`, map coordinates                     |
| `target` | the point it looks at: `{ x, y, z }`, map coordinates                   |
| `fov`    | the field of view, in degrees: 32 frames a face from 1.2 away           |
| `roll`   | optional: the camera turned about its view, in degrees; 0 when left out |

* **The name** is text of 1 to 23 characters. By convention it is the id of the NPC the shot frames; when one NPC has more shots, add something after it: `["npckit_0012 wide"]`. It is only a label: `npc.camera` does not look an NPC up.
* **`npc.camera("name")`** works only inside a function of `npc.add`, and only with a name of that NPC's `cameras`.
* **A shot by angle and distance:** `npc.customCamera.orbit { target = { x, y, z }, yaw = 1.5708, pitch = 0.05, distance = 1.2, fov = 33 }` goes in `cameras` as any shot. The camera sits `distance` away from `target`, on the side `yaw` names (a heading, as `npc.dir` takes it: an NPC's own heading puts the camera in front of its face), `pitch` above it.

{% hint style="warning" %}
A `behindcamerafovyroll` still in effect from earlier in the talk narrows the shot's `fov` too.
{% endhint %}
