> 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/about.md).

# About NPC Kit

**New NPCs from a Lua script, run by the game's own script interpreter.**

***

### The problem

FF12's NPCs live in each map's event script, the `.ebp`. Each NPC is an actor there, with an `init` that places it, a `main` that runs every frame, and a `talk` for when the player talks to it.

To add an NPC you had to edit that script and ship the file, or take over an actor the map already uses. And a map has one `.ebp`: two mods that each edit it to add their NPCs overwrite each other, and only one of them works.

***

### How NPC Kit solves it

The game runs its scripts through several script managers. One of them, manager 4, exists in the game and vanilla leaves it empty.

NPC Kit gives manager 4 a script of its own. Your mod declares an NPC with `npc.add`, writing its `init`, `main` and `talk` call by call, like an EBP. The kit records those calls into a script, and when the map loads the game builds the NPCs from it and runs them like any other actor.

No `.ebp` is edited or shipped, so mods that add NPCs don't conflict: any number of them can add NPCs to the same map.

Because they are real actors, the NPCs get from the game for free:

* every script call the game has, by its name
* the talk button, the name tag and the target ring
* models and motions
* the Lua Loader's `dialog.*` windows, opened from a talk

***

### Dialogs come from the Lua Loader

NPC Kit is used together with the Lua Loader's **dialog capability**. The kit makes the NPC, its talk button and its talk; what the NPC says is a `dialog.*` window you open from the talk with [`npc.lua`](https://fehdead.gitbook.io/npc-kit/api/lua-during-the-game.md). The windows, their speaker, choices and text are documented by the Lua Loader:

{% content-ref url="<https://gitlab.com/ff12-module-loader/modules/ff12-lua-loader-docs>" %}
<https://gitlab.com/ff12-module-loader/modules/ff12-lua-loader-docs>
{% endcontent-ref %}

{% hint style="info" %}
**NPC Kit adds nothing by itself.** Other mods declare NPCs through it. With only NPC Kit installed, the game plays as vanilla.
{% endhint %}

***

### Writing an NPC

Your Lua mod loads the kit's helper and declares the NPC. Each line in its functions is one call of the game's script VM.

{% content-ref url="/pages/rKHCzZ06okwAtZkZ4wOO" %}
[NPC Kit API](https://fehdead.gitbook.io/npc-kit/api.md)
{% endcontent-ref %}

***

### Shipping your mod

When your NPCs are done, players get two things:

* **your script**, in your mod
* **NPC Kit**, as a dependency your mod requires

{% hint style="danger" %}
**Never ship NPC Kit Editor with a mod.** It's only for you, the creator, to edit and test your NPCs. See [NPC Kit Editor](https://fehdead.gitbook.io/npc-kit/editor.md).
{% endhint %}

***

### Good to know

{% hint style="warning" %}
**An NPC appears the next time its map loads.** `npc.add` never rewrites the script of a map that is already running.
{% endhint %}

{% hint style="info" %}
**Cutscenes hide the NPCs.** During a scene the kit's NPCs are hidden, and their scripts keep running.
{% endhint %}

{% hint style="warning" %}
**Keep a map under 64 modelled actors.** The game crashes past that with no warning. See [Limits](https://fehdead.gitbook.io/npc-kit/api/limits.md).
{% endhint %}
