NPC 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:

my_npc:
  base: villager          # required - any spawnable entity (modded ids like mod:thing work too)
  model: steve            # optional - a regular model OR a player model (e.g. steve)
  skin: Notch             # optional - player-model NPCs only: whose skin to wear
  display: "&fShopkeeper" # optional - name above the NPC (& color codes)
  look: true              # optional - turn to face the nearest player
  glowing: true           # optional - glow outline
  gravity: false          # optional - float in place instead of falling (default: true)
  nametag: false          # optional - false hides the name above the head (kept for dialogs)
  effects:                # optional - named Effects/ ids run when a player right-clicks
  - greeting
  dialog: bob_talk        # optional - a Dialogs/ id; right-clicking starts the conversation
  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`. Hidden when a player model is worn.
`model`	❌	What the NPC looks like: a regular model from `models/`, or a player model from `players/` (like the shipped `steve`). The engine picks the right renderer automatically. Omit for the plain base entity look.
`skin`	❌	Player-model NPCs only: whose skin to wear, by player name. Fetched from Mojang in the background and cached, so a name used for the first time may show the default skin for a second before the real one swaps in. Omit for the default skin.
`display`	❌	The floating name. Supports `&` color codes.
`look`	❌	`true` = track the nearest player within 8 blocks. Turning it off freezes the current facing.
`glowing`	❌	Outline glow.
`gravity`	❌	`false` = float in place. Default `true`.
`nametag`	❌	`false` hides the name above the head. The display name is still kept (so dialogs show who’s talking); it just isn’t shown floating. Default shows it.
`effects`	❌	Named effect ids from `Effects/`, run when a player right-clicks the NPC. The NPC is the caster, the clicker is `@target`.
`dialog`	❌	A dialog id from `Dialogs/`. Right-clicking the NPC starts that conversation. Also settable with `/npc dialog`.
`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) and another copy appears there on the next reload or chunk load. Remove an entry and that copy is gone. The definition-level keys apply to every instance, with one wrinkle: /npc rename, /npc skin and /npc nametag run against a single selected copy write a per-copy override instead, so one placed instance can carry its own name, skin or nametag setting while the rest follow the definition.

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.

Getting Started

Mobs

Spawning

Commands

Effects

Models

Compatibility

NPCs

Configuration

API

Format

Field reference

One definition, many instances

Older files

​Format

​Field reference

​One definition, many instances

​Older files

Format

Field reference

One definition, many instances

Older files