> 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/vm-reference/calls/attach.md).

# npc.attach

```lua
npc.attach(actor, point)
```

|                         |                                  |
| ----------------------- | -------------------------------- |
| id                      | `0x00D9`                         |
| arguments               | 2: Int, Int                      |
| in NPC Kit              | yes                              |
| measured from a kit NPC | returns                          |
| vanilla scripts         | 338 calls in 109 of 1114 scripts |

## What it does

Ties this NPC's model to an attach point of another actor's model, so it moves with that part: a prop NPC held in a character's hand, a rider on a mount.

## Arguments

### `actor` (Int)

The actor to tie to: in the kit, another NPC of the script with `npc.actor("id")` (in a talk).

### `point` (Int)

The attach point on that actor's model. Slot `2` is the right hand on the models vanilla uses it with; vanilla also passes `3` and others.

## Timing

Returns at once; the tie takes effect on the next frame.

## In NPC Kit

Tested: a kit NPC bound to a weapon model (`0x0077....`, its origin is its grip) tied to slot 2 of an Imperial soldier NPC sits in the right hand, blade forward. While tied, the prop's own `setpos`/`dir` do nothing. Rebinding the parent's model drops the prop: tie it after the parent's last `bindp2_d4`.

## Used with

* [attachoff](https://fehdead.gitbook.io/npc-kit/vm-reference/calls/attachoff.md): untie, back where the prop's actor stands.
* [bindp2\_d4](https://fehdead.gitbook.io/npc-kit/vm-reference/calls/bindp2_d4.md): the prop's model.

## Example

A soldier who draws a sword in the talk: the sword is a kit NPC tied to the soldier's right hand (slot 2), and untied when the talk ends.

```lua
local warning = [[
Not one step further, or you will regret it, boy.
This street is closed until the guards say so.
]]

npc.add {
    id = "npckit_0031", map = 290, name = "NPCKit 0031",
    init = function()
        npc.usecharhit(0);
        npc.bindp2_d4(0x00770016, 1, 0);   -- Broadsword: its origin is the grip
        npc.setpos2(29.36, -9.0, 68.65);
        npc.hide();
    end,
    main = function() npc.wait(90); end,
}

-- the soldier, npckit_0030
talk = function()
    local sword = npc.on("npckit_0031")
    sword.attach(npc.actor("npckit_0030"), 2);
    sword.show();
    talkOpen();
    npc.lua(function(handle) say(handle, warning) end);
    talkClose();
    sword.attachoff();
    sword.hide();
end,
```

## Pitfalls

* A `bindp2_d4` on the holder after the `attach` drops the prop: tie it after the holder's last bind.
* While tied, the prop's own `setpos` / `dir` do nothing.
