> 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/lua-during-the-game.md).

# Lua During the Game

**`npc.lua(fn)` runs your Lua while the game runs the NPC's script.**

```lua
npc.lua(fn)
npc.lua(npc.call(), fn)
```

`fn(handle, value)` runs on the script thread, so `dialog.*` opens from there. `value` is the result of the call just before it, an integer (a float arrives cut). With none it is 0.

```lua
talk = function()
    npc.lua(npc.havegill(), function(handle, gil)
        print(gil)
        handle.finish()
    end)
end,
```

***

### In a talk, the script waits

**In `talk`, the script waits at `npc.lua` until `handle.finish()`.** So every way out of a dialog calls it, `onError` and a refused `open` included.

An error thrown in `fn` is caught and finishes.

### In init, the script waits for `fn`

**In `init`, the script waits at `npc.lua` until `fn` returns, or until the function it ran with `handle.run` ends.** No `handle.finish()`. It is how vanilla sets an NPC up by the story: a map's script reads the story and runs one of the NPC's functions, and the NPC is bound and placed in there.

```lua
npc.add {
    id = "npckit_0066",
    map = 290,
    name = "NPCKit 0066",

    init = function()
        npc.lua(npc.ismapjumpgroupflag(47), function(handle, passed)
            if passed == 0 then return end           -- not yet: no model, no talk
            handle.run("market")
        end);
    end,

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

    market = function()
        npc.bindp2_d4(0x006E0019, 4, 3);
        npc.usemapid(1);
        npc.setpos2(29.36, -9.0, 68.65);
        npc.fetchambient();
        npc.show();
    end,
}
```

`main` starts once `init` has ended. An NPC whose `init` returns with no `bindp2_d4` has no model and can't be talked to.

{% hint style="info" %}
A function that uses `npc.on` or `npc.actor` runs only from a talk: from `init`, `handle.run` logs and `init` goes on.
{% endhint %}

In `main` it doesn't wait: `handle.finish` does nothing, and `handle.run` logs.

***

### The handle

| field                    | what it does                                                                  |
| ------------------------ | ----------------------------------------------------------------------------- |
| `handle.id`              | the NPC's id                                                                  |
| `handle.finish()`        | ends the wait, and the talk goes on                                           |
| `handle.run("name", fn)` | runs the actor's function `name`, waits included, and calls `fn` when it ends |

`handle.run` runs one at a time: start the next from `fn`. With a wrong name, or with another one running, the log says so and the wait ends.

```lua
pay = function()
    npc.gillwinstart(-100);
    npc.gillwinsync();
    npc.subgill(100);
    npc.gillwinclose();
end,

talk = function()
    npc.lua(function(handle)
        handle.run("pay", function()
            handle.finish()
        end)
    end)
end,
```

{% hint style="warning" %}
A function that `handle.run` runs can't hold an `npc.lua`.
{% endhint %}
