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

# Custom Motion

**Another model's motions on your NPC: for a model that ships none worth playing, or for moves it was never given.**

{% hint style="warning" %}
**Experimental.** The game's scripts cannot do this. Custom Motion and [Custom Camera](https://fehdead.gitbook.io/npc-kit/api/custom-camera.md) are NPC Kit's own features, built on top of the game to take your NPCs past what vanilla allows: cutscenes, more motions and movement, more complex NPCs. They may change between versions.
{% endhint %}

***

### What it is for

In the game a model plays only its own motion files, and some ship almost none: Ondore (`0x006E0054`) has a single file with no idle, so on his own he stands in a T-pose. No VM call makes one model play another's motions.

`motionFrom` does: your NPC keeps its model and plays the motions of another one. Ondore can idle, talk and turn with the Imperial Magus's motions; a model made for one scene can be given a whole set of everyday moves. With [Custom Camera](https://fehdead.gitbook.io/npc-kit/api/custom-camera.md) it is what a scene of your own is made of.

***

### How to use it

1. **Add `motionFrom = { model, set }`** to the NPC's `npc.add`: the model whose motions it plays, and which of that model's motion sets, the `n` you would give `stdmotionread(n)` on that model.
2. **Write the NPC as usual.** Its `init` keeps its own `bindp2_d4`, `stdmotionread` and `stdmotionreadsync`.
3. **Play motions as usual.** Every `stdmotionplay` of the NPC, in `init`, `main` or a talk, now picks from the other model's set.

```lua
npc.add {
    id = "npckit_0062",
    map = 810,
    name = "NPCKit 0062",

    motionFrom = { 0x006E0003, 10 },    -- the Imperial Magus's motion set 10

    init = function()
        npc.setautorelax(1);
        npc.usecharhit(0);
        npc.bindp2_d4(0x006E0054, 1, 0);    -- Ondore
        npc.stdmotionread(0);               -- his own set, as always
        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(270.2, -3.0, 245.3);
        npc.dir(-0.8);
        npc.fetchambient();
        npc.bonecalcforce(-1);
        npc.clearhidecomplete();
        npc.show();
        npc.showshadow();
    end,

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

{% hint style="info" %}
**Try it with the editor first.** In the [NPC Kit Editor](https://fehdead.gitbook.io/npc-kit/editor.md#postures-and-motions), **replace motion** in the **Model** group puts another model's motion set on the NPC while you watch, and the **Code** section gives the `motionFrom` line.
{% endhint %}

***

### What to know

* **The two models must be built alike.** A motion moves the bones the two models share. Two people of the same build play whole; a model with other bones plays only part of the motion, or nothing.
* **A hidden NPC loads the motions.** The game keeps a motion set in memory only while a model on the map asks for it, so NPC Kit adds a hidden NPC of the other model to the map. It counts as one of the map's NPCs and one of its modelled actors (see [Limits](https://fehdead.gitbook.io/npc-kit/api/limits.md)). NPCs of one script that share a model and set on a map share one.
* **The first motion comes half a second late.** The other model's motions load alongside the NPC, so NPC Kit plays the last `stdmotionplay` of the `init` again half a second after it. `init` ends that much later.
* **A set the other model lacks does nothing.** The NPC keeps its own motions, with no message. The editor lists the sets each model ships; the ✓ means the file ships, and the editor loads it when you pick it.
* **One set at a time per reader.** A model keeps in memory only the sets its actors read: a townsperson of that model on set 16 doesn't load set 17. The hidden NPC reads exactly your `motionFrom` set, so any set the model ships works.
* **Variations carry over.** `stdmotionvariation(v)` picks a variation inside the other model's set, as it does on the model's own. A motion the set lacks in that variation plays nothing.
* **The motions bring their own commands.** A motion can show or hide parts of the model, and may run other commands of its own. Parts and sway bones your NPC's model doesn't have are skipped (without that the game would crash); the other commands are safe on any model. Try the NPC's talk and every motion it plays in the game before you ship it: a motion made for another skeleton can still look wrong.
* **`set` is 0 to 31.** Anything else fails at `npc.add`.
