> 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/configuration/npc-configuration.md).

# NPC Configuration

Configure appearance, behavior, interactions, sounds, and equipment per NPC.

Each NPC is stored as its own YAML file inside `plugins/MotionNPC/NPC/`. The file name should match the NPC id. `example.yml` is included as a commented reference and is not loaded.

### Basic example

```yml
id: guide

skin:
  type: player
  value: Notch

location:
  world: world
  x: 0.0
  y: 64.0
  z: 0.0
  yaw: 0.0
  pitch: 0.0

render:
  scale: 1.0
  view-distance: 32.0
  cull-behind-viewers: false
  hidden: false
  display-name:
    text: "<green>Guide <gray>%player_name%"
    visible: true
    y-offset: 2.35

look:
  enabled: true
  distance: 5.0

visible-permission: ""
default-animation: idle

hitbox:
  enabled: true
  width: 0.6
  height: 1.8

collision-push:
  enabled: false
  distance: 0.75
  strength: 0.18
```

`render.scale` changes the entire NPC size. `view-distance` controls who can see it. Enable `cull-behind-viewers` only when you want MotionNPC to stop animation packets for players looking clearly away from the NPC.

The display name supports MiniMessage, legacy color codes, built-in placeholders, and PlaceholderAPI when it is installed. Set `visible: false` to disable the hologram.

`visible-permission` is optional. Leave it empty to show the NPC to everyone.

### States and triggers

States select animations automatically. The state with the highest priority wins and transitions use `blend-ticks`.

```yml
states:
  idle:
    animation: idle
    priority: 10
    blend-ticks: 4
    cooldown-seconds: 0
  look:
    animation: look
    priority: 20
    blend-ticks: 4
    cooldown-seconds: 0
  near:
    animation: wave
    priority: 30
    blend-ticks: 4
    cooldown-seconds: 3
    distance: 5.0
  click:
    animation: click
    priority: 50
    blend-ticks: 2
    cooldown-seconds: 0
```

Every state can also contain a `sound` block with `enabled`, `value`, `volume`, `pitch`, and `cooldown-seconds`.

Use the proximity trigger for one-time enter or exit animations:

```yml
triggers:
  proximity:
    enabled: true
    distance: 5.0
    enter-animation: wave
    exit-animation: ""
    cooldown-seconds: 10
```

`walk` is reserved for future waypoint/path movement support.

### Sounds, equipment, and actions

```yml
sounds:
  proximity:
    enabled: true
    distance: 5.0
    cooldown-seconds: 10
    only-on-enter: true
    random: true
    volume: 1.0
    pitch: 1.0
    list:
      - "minecraft:entity.villager.ambient"
  hitbox:
    enabled: true
    sound: "minecraft:entity.player.attack.weak"
    volume: 1.0
    pitch: 1.0

equipment:
  main-hand:
    material: DIAMOND_SWORD
    custom-model-data: 0
  off-hand:
    material: SHIELD
    custom-model-data: 0

actions:
  right-click:
    - type: message
      value: "<green>Hello {player}!"
      cooldown-seconds: 2
  shift-right-click:
    - type: console
      value: "say {player} clicked {npc}"
      cooldown-seconds: 0
```

Supported action types are `message`, `console`, `player`, and `animation`. Actions are available for `left-click`, `right-click`, `shift-left-click`, and `shift-right-click`.

Supported built-in placeholders are `{npc}`, `{player}`, `{uuid}`, `%player_name%`, and `%player_uuid%`. PlaceholderAPI placeholders work when PlaceholderAPI is installed.

After manually editing an NPC YAML file, run `/mnpc reload`.


---

# 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/configuration/npc-configuration.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.