> 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/declaring-an-npc.md).

# Declaring an NPC

**`npc.add { ... }` declares an NPC. It takes effect the next time its map loads.**

### The table

| field              | what it is                                                                                                                                                  |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`, `map`        | required; `id` is a string, unique in the script                                                                                                            |
| `name`             | optional; left out, the NPC has no name                                                                                                                     |
| `init`, `main`     | required: the EBP's `init` and `main(1)`                                                                                                                    |
| `talk`, `talkterm` | optional: the EBP's `talk(2)` and the talk's closing function                                                                                               |
| any other name     | a function of the actor that Lua runs with `handle.run`, from `talk` or `init`                                                                              |
| `cameras`          | optional, experimental: fixed camera shots by name, see [Custom Camera](https://fehdead.gitbook.io/npc-kit/api/custom-camera.md)                            |
| `motionFrom`       | optional, experimental: `{ model, set }`, another model's motions on this NPC, see [Custom Motion](https://fehdead.gitbook.io/npc-kit/api/custom-motion.md) |

***

### The functions record, they don't run

The functions in the table run **once, at `npc.add`**. They record the game script, they are not it.

* A plain Lua function of yours called from one of them just adds its calls there.
* An `if` in them decides at load, not in the game.

To branch, loop or keep state during the game, use [`npc.lua`](https://fehdead.gitbook.io/npc-kit/api/lua-during-the-game.md).

{% hint style="danger" %}
**`main` repeats.** A `main` that gives no frame back, with no `wait`, freezes the game.
{% endhint %}

A `return` is added at the end of the other functions. Nothing else is added.

***

### The name

`name` is the NPC's name tag, also shown on its talk labels; left out, it has none. It goes through the game's text encoding (`message.convert`), so:

* it is at most 31 bytes in that encoding; longer fails at `npc.add`
* a character the game lacks fails at `npc.add` with the Lua Loader's message
* a Latin name is wrong with the game in Japanese, Korean or Chinese
