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

# NPC Kit API

**A Lua module that lets any FF12 Lua Loader mod declare NPCs, written call by call as in an EBP.**

### What it does

With it, a mod can:

* **Declare an NPC** on a map, with its `init`, `main` and `talk`.
* **Use any call of the game's script VM**, by its name, as `npc.<name>(...)`.
* **Run Lua during the game** from the NPC's script, and wait for it in a talk.
* **Run a call on another NPC** of the same script, in a talk.
* **Play fixed camera shots** and move the field camera.
* **Play another model's motions** on an NPC.
* **Turn a model on three axes, and give it a character effect** in any colour.

NPC Kit adds no call of the game. You write the NPC's script yourself, call by call. Fixed camera shots, another model's motions, and turning a model or giving it an effect are the things it adds of its own, all experimental.

***

### Getting started

Load the module at the top of your script, and stop if NPC Kit is missing:

```lua
local ok, npc = pcall(require, "scripts.NPCKit.Helper")
if not ok then
    print("Couldn't install, NPC Kit is missing.")
    return
end
```

Then declare an NPC:

```lua
local function myMod()
    npc.add {
        id = "npckit_0001",
        map = 290,
        name = "NPCKit 0001",

        init = function()
            npc.setautorelax(1);
            npc.usecharhit(0);
            npc.bindp2_d4(0x006E0019, 4, 3);
            npc.stdmotionread(16);
            npc.stdmotionreadsync();
            npc.stdmotionplay_2c2(0x01000000, 0);
            npc.setoverheadicontype(0);
            npc.usemapid(1);
            npc.usecharhit(1);
            npc.setweight(-1);
            npc.set_ignore_hitgroup(1);
            npc.motionloop(1);
            npc.setpos2(29.36, -9.0, 68.65);
            npc.dir(1.676);
            npc.fetchambient();
            npc.bonecalcforce(-1);
            npc.clearhidecomplete();
            npc.show();
            npc.showshadow();
        end,

        main = function()
            npc.wait(90);
        end,
    }
end

event.registerEventAsync("onInitDone", myMod)
```

`myMod` runs on `onInitDone`, once every script has started, so NPC Kit is always installed when your NPCs are declared. The NPC appears the next time map 290 loads.

***

### The pages

| page                                                                                 | what                                                                           |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [Starting Template](https://fehdead.gitbook.io/npc-kit/api/starting-template.md)     | a whole NPC that talks, in one file                                            |
| [Declaring an NPC](https://fehdead.gitbook.io/npc-kit/api/declaring-an-npc.md)       | the table `npc.add` takes                                                      |
| [Script Calls](https://fehdead.gitbook.io/npc-kit/api/script-calls.md)               | `npc.<name>`: any call of the game's VM                                        |
| [Lua During the Game](https://fehdead.gitbook.io/npc-kit/api/lua-during-the-game.md) | `npc.lua` and its handle                                                       |
| [Other NPCs](https://fehdead.gitbook.io/npc-kit/api/other-npcs.md)                   | `npc.on` and `npc.actor`: a call on another NPC, or another NPC as an argument |
| [Custom Camera](https://fehdead.gitbook.io/npc-kit/api/custom-camera.md)             | experimental: fixed shots for dialogue scenes                                  |
| [Custom Motion](https://fehdead.gitbook.io/npc-kit/api/custom-motion.md)             | experimental: another model's motions on an NPC                                |
| [Turning and Effects](https://fehdead.gitbook.io/npc-kit/api/model-effects.md)       | experimental: a model turned on three axes, a character effect and its colour  |
| [What Vanilla Does](https://fehdead.gitbook.io/npc-kit/api/what-vanilla-does.md)     | the calls vanilla NPCs use, and their traps                                    |
| [Limits](https://fehdead.gitbook.io/npc-kit/api/limits.md)                           | what the kit can't do                                                          |
| [References](https://fehdead.gitbook.io/npc-kit/references.md)                       | VM calls, models, text tags, items, dialogs                                    |
