> For the complete documentation index, see [llms.txt](https://motionnpc.nemesismc.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://motionnpc.nemesismc.net/reference/models-and-animations.md).

# Models & Animations

Load compatible Blockbench models and use their animations in MotionNPC.

MotionNPC uses Blockbench `.bbmodel` files built around player-style limbs. It is designed for head, torso, waist/hip, arms, forearms, legs, and lower-leg bones rather than arbitrary resource-pack object models.

### Loading models

Place compatible `.bbmodel` files in:

```
plugins/MotionNPC/models/
```

Then run:

```
/mnpc reload
/mnpc model list
/mnpc animation list
```

The bundled `default.bbmodel` is the base player model used when creating an NPC. Additional compatible models can provide animations that MotionNPC loads globally.

### Playing animations

```
/mnpc animation guide play wave once
/mnpc animation guide play idle loop
```

`once` returns to the normal/default behavior after the animation ends. `loop` repeats until another animation or state replaces it.

### Automatic states

Use `states` in the NPC YAML when an animation should play automatically:

```yml
states:
  idle:
    animation: idle
    priority: 10
    blend-ticks: 4
    cooldown-seconds: 0
  near:
    animation: wave
    priority: 30
    blend-ticks: 4
    cooldown-seconds: 5
    distance: 5.0
```

The highest active priority wins. `blend-ticks` smooths the transition from the previous pose. The `click` state plays after a valid NPC click.

### Performance notes

MotionNPC keeps the visual animation rate smooth while avoiding unnecessary work:

* Static limbs do not receive transform updates.
* NPCs without active viewers do not send animation frames.
* `render.cull-behind-viewers: true` stops animation packets for players looking clearly away from the NPC.
* `render.view-distance` should match the intended viewing area. Do not use a large distance for NPCs that only need to be seen nearby.

For large NPC hubs, use sensible view distances and enable behind-camera culling on decorative animated NPCs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://motionnpc.nemesismc.net/reference/models-and-animations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.