> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmentities.net/llms.txt
> Use this file to discover all available pages before exploring further.

# NPC Files

> The NPCs/ folder and YAML format: fields, instances and legacy files.

NPCs live in `plugins/NMEntities/NPCs/`, created on startup alongside `Mobs/` and `Effects/`. The `/npc` commands manage these files for you, but they're plain YAML and safe to hand-edit. `/nme reload` applies changes and respawns everything.

## Format

Every `.yml` or `.yaml` file in the folder can hold multiple NPCs. Each top-level key is an NPC id:

```yaml theme={null}
my_npc:
  base: villager          # required - any spawnable entity (modded ids like mod:thing work too)
  model: my_model_name    # optional - any loaded model; omit for a vanilla look
  display: "&fShopkeeper" # optional - name above the NPC (& color codes)
  look: true              # optional - turn to face the nearest player
  locations:              # one entry per placed instance
  - {world: world, x: 12.5, y: 64.0, z: -3.5, yaw: 180.0, pitch: 0.0}
  - {world: world, x: 40.5, y: 70.0, z: 8.5, yaw: 90.0, pitch: 0.0}
```

## Field reference

| Key         | Required | Description                                                                                                                   |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `base`      | ✅        | The entity underneath: any spawnable entity id, including modded ids like `mod:thing`.                                        |
| `model`     | ❌        | A loaded [model](models) to wear. Omit for the plain vanilla entity look.                                                     |
| `display`   | ❌        | The floating name. Supports `&` color codes.                                                                                  |
| `look`      | ❌        | `true` = track the nearest player within 8 blocks. Default is a fixed gaze.                                                   |
| `locations` |          | One entry per placed **instance**: `world`, `x`, `y`, `z`, `yaw`, `pitch`. Managed by the `/npc` commands, safe to hand-edit. |

## One definition, many instances

Each `locations:` entry is an instance of the same NPC standing somewhere in the world. Add an entry by hand (or with [`/npc spawn`](npc-commands)) and another copy appears there on the next reload or chunk load. Remove an entry and that copy is gone. The definition-level keys (`base`, `model`, `display`, `look`) always apply to every instance.

## Older files

NPC files from before multi-instance support used a single `location:` key. They still load, treated as one instance, and are upgraded to the `locations:` list automatically the next time a command touches them.