Creating NPCs

Configuration settings

isEnabled

Sets if an NPC is enabled.

Key	Values	Default
isEnabled	Boolean	true

Example

isEnabled: true

---

name

Sets the display name of an NPC. Supports Color Codes and translation keys for multi-language servers.

Key	Values	Default
name	String	none

Example

name: "&aEnn Peecee"

---

scale

Sets the scale (size) of the NPC. This is applied through the vanilla generic_scale attribute on the underlying entity.

Key	Values	Default
scale	Multiplier	1.0

When scaling, 1.0 represents the default size. To make the entity larger, increase the value (e.g., 1.2). To make the entity smaller, decrease the value (e.g., 0.8).

Example

scale: 1.2

---

role

Sets the role of the NPC, under the name. Only visual. Supports Color Codes and translation keys for multi-language servers.

Key	Values	Default
role	String	none

Example

role: "&c<Red Fellow>"

---

profession

Sets the profession of the NPC, which sets its skin when not using a disguise.

Key	Values	Default
profession	Profession	NITWIT

Example

profession: NITWIT

---

greetings

Sets the list of greetings the NPC can say when a player first enters its activationRadius. One entry is picked at random and shown as a floating chat bubble above the NPC (visible only to that player, for about 5 seconds). Supports translation keys for multi-language servers.

Key	Values	Default
greetings	String List	none

A greeting fires only on entering the radius, not repeatedly while the player stays inside it.

Example

greetings:
- Hi there!
- Good day. 

---

dialog

Sets the lines the NPC can say as a floating chat bubble. One entry is picked at random each time (the list is not read in order). Supports translation keys for multi-language servers.

When it fires depends on the interactionType:

• CHAT NPCs say a dialog line when a player right-clicks them.
• Every other interactionType says a dialog line on each proximity scan while a player stays inside the activationRadius.

A literal \n inside a line splits it into stacked bubble lines.

Key	Values	Default
dialog	String List	none

Example

dialog:
- I like apples!
- Sure is hot.

---

farewell

Sets the farewell messages of the NPC. One entry is picked at random and shown as a floating chat bubble. Supports translation keys for multi-language servers.

Key	Values	Default
farewell	String List	none

Farewells fire when a player closes an inventory menu while standing within 5 blocks of the NPC - typically right after closing a shop, quest, or arena menu. They do not fire when a player simply walks out of the activationRadius.

Example

farewell: 
- Until next time!
- Bye!

---

canTalk

Sets if the NPC can talk. When set to false, the NPC never shows a chat bubble, so greetings, dialog and farewell are all suppressed.

Key	Values	Default
canTalk	Boolean	true

Example

canTalk: true

---

activationRadius

Sets the radius, in blocks, at which an NPC can detect a player approaching.

Key	Values	Default
activationRadius	Double	3.0

Proximity is scanned every 5 seconds. While a player is inside the radius, the NPC rotates to face them, quest indicators are shown (for QUEST_GIVER / CUSTOM_QUEST_GIVER NPCs) and greetings / dialog are triggered. Setting this to 0 (or lower) disables proximity detection entirely for that NPC.

Example

activationRadius: 3.0

---

scripts

Sets the Lua scripts attached to this NPC. Script files are loaded from plugins/EliteMobs/npc_scripts/. The .lua extension is optional - it is appended automatically if you leave it out.

Key	Values	Default
scripts	String List	none

NPC scripts run on the shared MagmaCore Lua engine and support the following hooks: on_spawn, on_tick, on_remove, on_npc_interact, on_npc_proximity_enter, on_npc_proximity_leave, on_zone_enter and on_zone_leave. See Lua NPC Scripts for the full API and examples.

A script filename that does not resolve to a file in npc_scripts/ is skipped with a warning; the NPC still spawns.

Example

scripts:
- wave.lua

---

interactionType

Sets the type of interaction the NPC will do.

Key	Values	Default
interactionType	Special [1]	NONE

Example

interactionType: TELEPORT_BACK

---

noPreviousLocationMessage

When a Teleporter NPC has no previous location it can teleport a player to, it will display this message. Accepts Color Codes and translation keys for multi-language servers.

Key	Values	Default
noPreviousLocationMessage	String	none

Example

noPreviousLocationMessage: '&8[EliteMobs] &cCouldn''t send you back to your previous location - no previous location found!'

---

timeout

Sets the amount of time, in minutes, before an NPC vanishes permanently.

Key	Values	Default
timeout	Double	0 (never)

Example

timeout: 0

---

questFileName

Sets the custom quests the NPC gives. Requires the CUSTOM_QUEST_GIVER interactionType. Note that the key is singular (questFileName) even though it takes a list.

Key	Values	Default
questFileName	String List	none

Example

questFileName:
- my_quest_one.yml
- my_quest_two.yml

---

disguise

Sets the LibsDisguises disguise the NPC has.

Key	Values	Default
disguise	LibsDisguises format	none

Example

disguise: SKELETON

---

customDisguiseData

Sets the data for a custom LibsDisguises disguise.

Key	Values	Default
customDisguiseData	LibsDisguises format	none

Example

disguise: custom:my_cool_disguise_name
customDisguiseData: player my_cool_disguise_name setskin {"id":"364acb6d-9050-46f7-b5fb-f8c3fd83a6fc","name":"Unknown","properties":[{"name":"textures","value":"ewogICJ0aW1lc3RhbXAiIDogMTYxMTk4ODA4Nzc1NSwKICAicHJvZmlsZUlkIiA6ICJkZGVkNTZlMWVmOGI0MGZlOGFkMTYyOTIwZjdhZWNkYSIsCiAgInByb2ZpbGVOYW1lIiA6ICJEaXNjb3JkQXBwIiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzliYmVkODQzNWY4YmYyNzhhZmUyNmU2NGZkOTI2YjhiMzc3MzJkODhlMzM0ODk3ZGJkNTI3ZDU2ZmY5MTk5MGUiCiAgICB9CiAgfQp9","signature":"ujLq1joYVktuQAp1xpFKlxQFUVinSePiDBiVCAxxix/mA5vP86i/eAOfb1mtGjaAZ6sO0l2olbzvycnGXNBtbAxgqprguROXY4tpWiePVTDmy3iD4GdOCxHAkYLoyMV5qTT4SNsldUFFuND8GSEgbNMltKDLmhNKwzm08iCigPfpeuYpwljgJPxu6ka54PKNaQu4doI0ZDZXKqq4hPhR3Bs2Sz9MI0SmdmQWwcCzUz3DFdVno27fmQ6LwqmT+eSoOv0EttVG/XMaTYQ5lhBY61mqf6WlJyYVUSfjJk1AbYsctu7dWM+sbY8jFq5ljvXJGGr5TyKi+fs8vHy06Z2go20QgTYOw+caFxFijAS6fgm3oY57VEO/+/9OLHdD+Z9BrWqQWcIIrVeIfxjue/yt4pyeVv9jX59hjNFjhcPEwotkxJ+vZ96WlTLWDG4BiqauDr2VeGyLlVaygO9ZU0wwsN65iSh91GI3tMIA5wbDR0Hts/9ABvt9eafHbowS+4SZXN0i9mYnKg7op1eiB8nMEAGsPJg3DwsmUrh3ACAapQ6eYHiJpo59RXDqKlRcXwo7wsEFp//5LgQWbPj0NP3nxnywdpozqSAeq6236qlhE9BT9eiyJ41V9sMelYFEWMlUAltR40NdbIrHB0J3nmfuLJz44/sTwWf6P1khOy//XX0="}],"legacy":false}

---

customModel

Sets the ModelEngine custom model the NPC will use.

Key	Values	Default
customModel	String	none

Example

customModel: MY_MODEL_ONE

---

arena

Sets the filename of the arena the NPC will open a menu for (requires the ARENA_MASTER interactionType).

Key	Values	Default
arena	Filename	none

Example

arena: my_arena.yml

---

command

Sets the command the NPC will run (requires COMMAND interactionType). Commands are executed as the player, not as the console. Do not include the leading slash (/).

Key	Values	Default
command	String	none

Example

command: say Look at me running a command, how cool!

---

spawnLocation

Sets a single spawn location for the NPC. This is the legacy single-location key: it is only read when spawnLocations is absent or empty. New locations placed in-game are written to spawnLocations instead, so prefer that key.

The format is world,x,y,z,yaw,pitch.

Key	Values	Default
spawnLocation	String	none

Example

spawnLocation: my_world,10,50,10,0,0

---

spawnLocations

Sets the spawn locations of the NPC. The same NPC file can be placed in several spots; one NPC is spawned per entry. You should set this through the /em place npc <npcfilename.yml> command, which appends your current location (including the direction you are facing) to this list and also sets isEnabled: true.

The format of each entry is world,x,y,z,yaw,pitch.

Key	Values	Default
spawnLocations	String List	none

Example

spawnLocations: 
- my_world,10,50,10,0,0
- my_world,-10,50,-10,0,0

instanced

Sets if the NPC should be instanced (for use in instanced dungeons). When set to true, the NPC is not spawned in the blueprint world; instead it is registered as a template and cloned for each dungeon instance, with each clone existing in the corresponding instance world.

Key	Values	Default
instanced	Boolean	false

Example

instanced: false

---

syncMovement

Sets if the NPC's custom model should have its movement synchronized with the underlying entity. This only has an effect when customModel is set and the model is loaded - it is ignored for plain and LibsDisguises NPCs.

Key	Values	Default
syncMovement	Boolean	true

Example

syncMovement: true

---

NPC Config Example

isEnabled: true
name: "&cRed Rubin"
role: "&a<Generic NPC>"
profession: NITWIT
greetings:
- Hiya!
- Hello!
dialog:
- Great conversation!
- Pleasure talking with you!
farewell:
- Goodbye!
- Laters!
canTalk: true
activationRadius: 4
interactionType: CHAT
timeout: 0
questFileName: 
- my_quest.yml #npc interactionType must be set to CUSTOM_QUEST_GIVER
disguise: SKELETON
customDisguiseData: #used when a custom libsdisguise is being set
customModel: MODEL_ONE
arena: my_arena.yml #npc interactionType must be set to ARENA_MASTER
command: say Hello World! #npc interactionType must be set to COMMAND (do not include the leading slash)
spawnLocation: my_world,584,55,127,90,10 #remember that NPCs use pitch and yaw to set where they are looking at. this is also automatically set when running the /em place npc <npcfilename.yml> command, so make sure you pose where you want the NPC to be facing when running the command.

---

Special [1]

The following is the list of valid NPC interaction types:

Type	Description
GUILD_GREETER	Opens the weapon skill bonus selection menu
CHAT	Right-clicking says a random line from dialog
CUSTOM_SHOP	Opens the custom shop menu
PROCEDURALLY_GENERATED_SHOP	Opens the procedurally generated shop
BAR	Unimplemented. Tells the player the feature is coming soon.
ARENA	Does nothing. Use ARENA_MASTER instead.
QUEST_GIVER	Opens the procedurally generated quests menu
CUSTOM_QUEST_GIVER	Opens the quest menu for a specific quest set in questFileName
NONE	No interactions
SELL	Opens the sell menu
TELEPORT_BACK	Teleports players back to the last non-elitemobs world location they were
SCRAPPER	Opens the scrap menu
REPAIRMAN	Opens the repair menu
ENCHANTER	Opens the enchant menu
REFINER	REPLACED - Tells the player the feature was replaced; admins are told to remove the NPC
SMELTER	REPLACED - Tells the player the feature was replaced; admins are told to remove the NPC
ENHANCER	REPLACED - Tells the player the feature was replaced; admins are told to remove the NPC
UNBINDER	Opens the unbind menu
ARENA_MASTER	Opens the arena menu for the arena set in arena
COMMAND	Runs the command set in command
SCROLL_APPLIER	Opens the elite item scroll menu. The NPC does not spawn at all while useEliteItemScrolls is disabled
ARROW_SHOP	Opens the arrow shop menu
GAMBLING_BLACKJACK	Opens the blackjack gambling game
GAMBLING_COINFLIP	Opens the coin flip gambling game
GAMBLING_SLOTS	Opens the slots gambling game
GAMBLING_HIGHERLOWER	Opens the higher/lower gambling game

For more information on what the SCRAPPER and similar interaction types do click here.

NPC Behavior Notes

NPCs have several hardcoded behaviors that cannot be configured:

• AI Disabled: NPCs cannot move or pathfind. They remain at their spawn location. They do rotate on the spot to face a player who is inside the activationRadius.
• Role Display: The role text is rendered on a floating text display entity above the NPC. The vertical offset depends on how the NPC is rendered - 2.52 for a plain NPC, 2.30 for a LibsDisguises NPC, and 2.3 for one using a customModel.
• Bedrock Role Tag: Bedrock clients cannot render text displays, so a disguised NPC additionally gets an invisible marker armor stand carrying the role text, shown only to Bedrock players and hidden from Java players. Its height is set by bedrockNPCRoleYOffset in config.yml (default 2.2). This fallback requires Geyser or Floodgate on the backend server; a proxy-only Geyser setup disables it.
• Dialogue Cooldown: NPCs wait 3 seconds between speech events to prevent overlapping messages. Chat bubbles are per-player floating text that disappears after about 5 seconds, not chat messages.
• Invisibility: An NPC under the invisibility potion effect will not show chat bubbles.
• Chunk Lifecycle: NPCs despawn when their chunk unloads and respawn when it reloads. NPC entities are never saved to the world - they are recreated from their configuration file.
• Renaming Blocked: Right-clicking an NPC while holding a name tag is cancelled and the player is told the NPC cannot be renamed.