ModeledNPCS

ModeledNPCS

Fully modeled, animated, talking NPCs for Paper β€” with routes, dialogs, quests and a complete in-game editor.
Paper 1.20 – 26.3 v9.5.1 ModelEngine BetterModel MythicMobs

ModeledNPCS turns ModelEngine, BetterModel and MythicMobs models into interactive NPCs. Each NPC can talk, walk a patrol route, run commands, play particles, glow, escort a player, and change behaviour by time of day β€” all configurable in game, without touching a file.

See it in action

0:00 Intro 0:12 Dialogs Β· SHADER 0:41 Dialogs Β· PAPER 0:58 Studio Β· CLASSIC 1:26 Studio Β· TEXTURED 1:41 Studio Β· DIALOG
Full feature tour (1:54) β€” talking to NPCs with the SHADER and PAPER dialog styles, and all three NPC Studio styles.
A modeled NPC standing in the world
A ModelEngine NPC (lr_acolyte) created with a single command.

What you get

🧍
Modeled NPCs
ModelEngine, BetterModel or MythicMobs models as NPCs.
πŸ’¬
3 Dialog Styles
Native windows, a parchment HUD box, or plain chat.
🎨
NPC Studio
Full in-game editor in 3 visual styles.
🧭
Routes & Patrol
Waypoints, patrol loops and arrival actions.
✨
Effects
Particles, potions and per-player glow.
πŸ“¦
Resource Pack
Auto-merged and shipped to your pack plugin.
🎯
Hover System
NPCs react when a player looks at them.
🧩
Developer API
Public API and events for your own plugins.
GETTING STARTED

Installation

Dependencies, supported versions and first launch.

Requirements

PluginRequiredNotes
Paper 1.20 – 26.3RequiredPaper 1.21.7+ is needed for PAPER dialogs and the DIALOG studio style.
PlaceholderAPIRequiredHard dependency β€” the plugin will not enable without it.
packeteventsRequiredHard dependency. Used for packet-based rotation and NPC visibility.
ModelEngineOptionalNeeded for modelengine NPCs.
BetterModelOptionalNeeded for bettermodel NPCs.
MythicMobsOptionalNeeded for mythicmobs NPCs.
ProtocolLibOptionalSmooth escort movement and PACKET auto-look mode.
WorldGuardOptionalRegion-aware NPC behaviour.
Quests / BetonQuestOptionalQuest integration from dialogs.

Install

1

Drop in the jar

Place ModeledNPCS-9.5.1.jar in plugins/ together with PlaceholderAPI and packetevents.

2

Start the server once

This generates plugins/ModeledNPCS/ with all configuration files and writes the dialog resource pack.

3

Add your models

Put your .bbmodel files in ModelEngine's blueprints/ (or BetterModel's models folder) and run /meg reload. The blueprint id is the model name you pass to /mnpc create.

4

Deliver the resource pack

Players need the model + dialog textures. See How the Pack Works β€” if you use CustomiZer, ItemsAdder or Nexo this is automatic.

Generated files

plugins/ModeledNPCS/
config.yml # main settings, GUI style, resource pack
dialog_config.yml # dialog renderer + glow/quest messages
lang.yml # translatable messages
commands.yml # command aliases
trader.yml # NPC shops
meganimation.yml # animation presets
npc-extras.yml # states, schedules, hologram animation
player_flags.yml # per-player interaction flags
dialogs/ # your dialog trees (one or more .yml)
resourcepack/ # generated packs
ModeledNPCS-Dialogs.zip
ModeledNPCS-Merged.zip # only when hosting is on
npcdata.json / npcs.db # NPC storage
GETTING STARTED

Quick Start

From an empty server to a talking, walking NPC.
1

Create the NPC

Stand where you want it and run:

/mnpc create modelengine lr_acolyte

The console confirms the new id, e.g. Created ModelEngine NPC (ID: 2).

2

Give it a name

/mnpc name 2 &e&lFather Lucius
3

Open the editor

/mnpc edit 2

Everything else β€” appearance, animations, behaviour, movement, interactions, effects and dialogue β€” is editable from here.

4

Make it walk

Stand at each waypoint and add it, then start patrolling:

/mnpcai 2 addpoint
/mnpcai 2 addpoint
/mnpcai 2 patrol
5

Give it a dialog

Create plugins/ModeledNPCS/dialogs/village.yml and point it at the NPC id β€” see Dialog Trees. Then /mnpc reload.

Every command that takes an <id> accepts the numeric NPC id shown by /mnpc list.
NPCS

Creating NPCs

Three model backends, one command.
/mnpc create <modelengine|bettermodel|mythicmobs> <name>
Type<name> isRequires
modelengineThe blueprint id (the .bbmodel file name without extension)ModelEngine
bettermodelThe BetterModel model nameBetterModel
mythicmobsThe MythicMobs mob idMythicMobs

The NPC spawns at your location and is assigned the next free id. Ids are capped by max_npc_ids in config.yml (default 1000).

The model must exist before you create the NPC. Add the .bbmodel to ModelEngine's blueprints/ folder, run /meg reload, then create the NPC.

Removing

/mnpc remove <id>     # deletes the NPC permanently
/mnpc list            # lists every NPC with its id, type and world
If players see a magenta/black model, they do not have the resource pack. See How the Pack Works.
NPCS

Managing NPCs

Moving, rotating, scaling, hiding and running commands.

Position & pose

CommandWhat it does
/mnpc move <id>Moves the NPC to where you are standing.
/mnpc tp <id>Teleports you to the NPC.
/mnpc rotate <id> <degrees> <left|right>Rotates the NPC by a number of degrees.
/mnpc look <id> [off]Turns the NPC to face you. off disables auto-look.
/mnpc scale <id> <scale>Sets the model render scale (e.g. 1.5).
/mnpc static <id>Toggles the NPC as static (never moves or is pushed).

Visibility

/mnpc hide <id> <permission>   # only players with this permission see the NPC
/mnpc hide <id> remove          # clear the restriction

Click commands

Commands run when a player interacts with the NPC.

/mnpc addcmd <id> <player|console|sudo|bungee> <command>
/mnpc removecmd <id> <command>
ExecutorRuns as
playerThe clicking player, with their own permissions.
consoleThe server console.
sudoThe player, but with elevated permission.
bungeeSent to the proxy (e.g. to switch server).
Command spam is limited by npc.cooldowns.command_ms (default 3000 ms).

Reloading

CommandReloads
/mnpc reloadAll configs, NPC data, dialogs and holograms. Applies renderer and GUI style changes live.
/mnpc reloadnameNametags only.
/mnpc reloadanimAnimations.
/mnpc reloadeffectsEffects.
/mnpc cleanholograms [radius]Removes stray hologram armor stands near you.
NPCS

Nametags & Holograms

Display names, height and animated hologram text.
/mnpc name <id> <custom name> [height]
/mnpc hidenametag <id>
/mnpc shownametag <id>
/mnpc resetnametag <id>

Names support & colour codes and MiniMessage, and PlaceholderAPI placeholders are resolved per viewer. The optional [height] is the vertical offset above the model.

NPC with a nametag walking its route
An NPC named &e&lFather Lucius, mid-patrol.

Animated holograms

Hologram text can cycle through frames. Enable hologram_animation.enabled in config.yml, then set frames through the Studio or the API (setNPCHologramFrames, setNPCHologramFrameInterval).

SettingDefaultMeaning
hologram-view-distance20Blocks at which hologram text is visible.
hologram_animation.enabledtrueEnables frame cycling.
holograms.debug_visibilityfalseVerbose visibility logging.
Stray holograms after a crash? Run /mnpc cleanholograms 5, or in vanilla: /minecraft:kill @e[type=armor_stand,distance=..1].
NPCS

Hover System

NPCs react when a player aims at them.

When a player's crosshair lands on an NPC within range, the model and hologram scale up, a sound plays, an action-bar hint appears, and right-click interaction works from that distance β€” the player does not have to walk up to it.

Hover hint shown while aiming at an NPC
The action-bar hint [Right-Click] Interact while hovering an NPC.
npc:
  hover:
    enabled: true
    range: 10.0              # how far away hover can trigger (blocks)
    angle_deg: 15.0          # cone half-angle β€” how precisely to aim
    scale: 1.2               # model scale while hovered
    sound: UI_BUTTON_CLICK   # any Bukkit Sound name
    sound_volume: 0.6
    sound_pitch: 1.4
    scale_hologram: true
    hologram_scale: 1.3
    check_interval_ticks: 2  # lower = more responsive
    hint_text: "&e[Right-Click] &fInteract"   # blank to disable
Per-NPC overrides are available through the API: setNPCHoverEnabled, setNPCHoverHint and setNPCHoverAnimation.
NPCS

States & Schedules

NPCs that change behaviour by time of day.

States

A state is a named mode an NPC is in. Dialogs, animations and effects can react to it. Enable with states.enabled: true; read and write with getNPCState / setNPCState.

Schedules

A schedule gives an NPC active hours. Outside them the NPC refuses interaction and shows the message from npc.schedule_inactive_message.

schedules:
  enabled: true

npc:
  schedule_inactive_message: "&cThis NPC is not available right now."

Set the window with setNPCSchedule(npcId, startHour, endHour), and check with isNPCActive(npcId). Hours are Minecraft world hours (0–23).

Greetings & player flags

SettingDefaultMeaning
greetings.enabledtrueNPCs greet players who approach.
player_flags.enabledtruePer-player interaction flags (e.g. "already talked").
player_flags.persistenttrueSaves flags to player_flags.yml across restarts.
NPCS

Admin Tool

A wand that opens the editor by right-clicking an NPC.
/mnpc admintool give    # gives you the tool
/mnpc admintool info    # shows the current tool settings
AdminTool:
  enabled: true
  debug: false
  item: BLAZE_ROD
  permission: ""            # empty = anyone with mnpc.admintool
  name: "&6&lNPC Admin Tool"
  lore:
    - "&7Right-click an NPC to open"
    - "&7the management GUI"
    - ""
    - "&eFor admins only"
Holding the tool and right-clicking any NPC opens its Studio page directly β€” no id needed.
NPC STUDIO

NPC Studio

The in-game editor, in three visual styles.
/mnpc edit <id>      # or /mnpc manage <id>, or /mnpcmanage <id>

The Studio is the single place to configure an NPC. From the dashboard you reach every category:

PageWhat you configure
AppearanceModel, scale, nametag, hologram text and height.
AnimationsIdle/walk/interact animations and ModelEngine states.
BehaviorAuto-look, static mode, states and schedules.
MovementRoutes, waypoints, patrol mode and speed.
InteractionsClick commands, cooldowns and view permission.
EffectsLooped and on-interact particles, potion effects, glow.
DialogueThe dialog tree bound to this NPC.
AdvancedInternal ids, respawn, raw data.
NPC libraryBrowse and jump to any other NPC.

Choosing a style

gui:
  style: CLASSIC     # CLASSIC | TEXTURED | DIALOG
  theme: arcane      # arcane, ember, forest
  border: full       # full, corners, none
  animations:
    enabled: true
    speed-ticks: 4   # 2..40 ticks between frames
    intensity: 1     # 0 = opening only; 1..3 = moving highlight
  sounds:
    enabled: true
The style is read each time a screen opens, so /mnpc reload applies a change immediately β€” no restart.
NPC STUDIO

CLASSIC style

Standard inventory menus with animated borders.
CLASSIC studio dashboard
gui.style: CLASSIC β€” the NPC Studio dashboard.

The default. Works on every client with no resource pack, and needs nothing from the player. Borders are animated glass panes; the theme and animation speed are configurable.

gui:
  style: CLASSIC
  theme: arcane        # arcane | ember | forest
  border: full         # full | corners | none
NPC STUDIO

TEXTURED style

The same menus, drawn on a parchment panel.
TEXTURED studio dashboard
gui.style: TEXTURED β€” identical layout and clicks, parchment panel.

Exactly the same menus and click behaviour as CLASSIC, but the chest background is replaced with a hand-drawn parchment panel with slot sockets, using a title glyph from the ModeledNPCS resource pack.

TEXTURED needs the ModeledNPCS resource pack. Players without it see a normal chest GUI with an odd title β€” nothing breaks, but it will not look right.
NPC STUDIO

DIALOG style

The whole editor as native dialog windows.
DIALOG studio editor
gui.style: DIALOG β€” native inputs, a live scale slider and a toggle.

Every Studio screen becomes a native Minecraft dialog window. Clickable items become buttons, lore hints such as "Left +0.1 / Right -0.1" become their own buttons, and display-only items become icon rows.

The dashboard adds real inputs you cannot get from an inventory:

  • Display name β€” a text field, edited in place
  • Scale β€” a slider
  • Auto-look at players β€” a checkbox
  • Apply quick edits β€” saves all three at once and reports Saved
Requires Paper 1.21.7+. On older servers the Studio automatically falls back to CLASSIC.
Chat prompts (like renaming) close the dialog and reopen it when you are done, so you never lose your place.
DIALOGS

Dialog System

Branching conversations with three ways to display them.

A dialog is a tree of nodes. Each node shows some lines and offers numbered options; each option can open another node, start a quest, run a command, start an escort, or end the conversation.

Dialog trees live in plugins/ModeledNPCS/dialogs/ β€” one or many .yml files, each holding one or more trees. Reload with /mnpc reload.

How display is chosen

  1. The tree's own renderer: key, if present.
  2. Otherwise renderer.mode in dialog_config.yml.
  3. If that renderer is unavailable (e.g. PAPER on an old server), it falls back to CHAT.
This means you can keep a server-wide default and still force one specific conversation into another style.
DIALOGS

Dialog Renderers

PAPER, SHADER and CHAT.
renderer:
  mode: PAPER      # PAPER | SHADER | CHAT

PAPER default

PAPER dialog window
A native dialog window: parchment text panel, one button per answer.

A native Minecraft dialog window with one button per answer plus a Goodbye exit button. It renders on every client, needs nothing from the player, and is the safest default.

  paper:
    use-pack-textures: true          # parchment panel (needs the pack)
    button-width: 220
    close-button: '<gray>Goodbye</gray>'
Needs Paper 1.21.7+. Older servers fall back to CHAT automatically.

SHADER

SHADER dialog box above the hotbar
The parchment HUD box, drawn above the hotbar by a core shader.

A parchment box above the hotbar, sent as action-bar text and positioned and inked by a core shader in the resource pack. The most immersive option β€” the player keeps full control of their character while talking.

  • Mouse wheel or 1–9 β€” highlight an answer (the held item never changes)
  • F β€” confirm, or turn the page on long text
  • Shift β€” leave the conversation
  • Typing the option number in chat also works
  shader:
    chat-fallback: false            # also print the dialog in chat
    hint-choose: '[F] Choose  [Shift] Leave'
    hint-next: '[F] Continue  [Shift] Leave'
SHADER does not work with Sodium, Iris or OptiFine.

The parchment box is drawn by patching the vanilla core-shader pipeline. Sodium, Iris and OptiFine (and most other rendering mods) replace that pipeline with their own, so the patched text shader never runs. Those players see nothing at all above the hotbar β€” no error, no fallback, just a missing dialog. It is a silent failure, and it is easy to mistake for a broken plugin.

There are two ways to avoid it:
  • Players use the vanilla (unmodded) client β€” the core shader then works normally.
  • Or the server uses the PAPER dialog style, which renders on every client, modded or not. This is the default for exactly this reason.

If you want to keep SHADER for vanilla players, turn on chat-fallback so modded players at least receive the dialog in chat.

CHAT

Plain chat lines; the player types the option number. No resource pack, no version requirement β€” the universal fallback.

Comparison

PAPERSHADERCHAT
Minimum serverPaper 1.21.7+AnyAny
Requires a vanilla (unmodded) clientNoYesNo
Needs resource packOptional (nicer with)YesNo
Works with Sodium / Iris / OptiFineβœ…βŒβœ…
Player can move while talkingβŒβœ…βœ…
InputButtonsWheel / 1–9 / FType a number
DIALOGS

Dialog Trees

The YAML format.
Village_Priest:                 # tree key β€” must be unique
  npc: 2                        # NPC id this tree belongs to
  questName: "LostBells"        # optional quest this dialog drives
  renderer: PAPER               # optional per-tree override
  displayName:
    - "&e&lFather Lucius"       # speaker name shown in the dialog
  dialog:
    Action: DIALOG
    Dialog:
      - "Hello my friend, how can I help you?"
      - "1) Show me the church."
      - "2) Tell me more."
    Options:
      "1":
        Action: CANCEL
      "2":
        Action: DIALOG
        Dialog:
          - "Long ago, pilgrims came from every corner of the realm..."
          - "1) I will help."
          - "2) Not today."
        Options:
          "1":
            Action: CANCEL
          "2":
            Action: CANCEL

Keys

KeyRequiredMeaning
npcYesThe NPC id this tree is attached to.
displayNameNoSpeaker name. Supports colour codes and placeholders.
questNameNoLinks the dialog to a quest for status tracking.
rendererNoPAPER, SHADER or CHAT β€” overrides the global mode.
dialogYesThe root node.
DialogYesThe lines shown. A line like 1) Text becomes option 1's label.
OptionsNoMap of option number β†’ action. No options = a notice.
LabelNoExplicit button label for an option, instead of the 1) ... line.

Actions

ActionEffect
DIALOGOpens a nested node (with its own Dialog and Options).
CANCELEnds the conversation.
COMMANDRuns a command.
QUESTAssigns or advances the linked quest.
ESCORTStarts an escort to a destination.
Long text is paginated automatically in SHADER mode, so you can write as much as you want in one node.
DIALOGS

Quests & Placeholders

Quest status, glow colours and PlaceholderAPI.

Quest status glow

NPCs can glow in a colour that reflects the player's progress on their quest. Configure in dialog_config.yml:

glow:
  enabled: true
  update-interval-ticks: 60

status:
  NOT_STARTED:
    chatColor: RED
    text: '&c&lNot Started'
  IN_PROGRESS:
    chatColor: YELLOW
    text: '&e&lIn Progress'
  COMPLETED:
    chatColor: GREEN
    text: '&a&lCOMPLETED'

Valid colours: BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, LIGHT_PURPLE, YELLOW, WHITE.

PlaceholderAPI

PlaceholderReturns
%dialogstatus_<QuestName>_status%The player's status text for that quest, using the status block above.

Placeholders are also resolved inside dialog lines, nametags and hologram text, per viewer.

Third-party quests

Quests and BetonQuest are supported as soft dependencies β€” a dialog option can start or advance a quest in either plugin.

AI & MOVEMENT

Routes & Patrol

Waypoints and walking NPCs.
NPC walking a patrol route
An NPC walking between its waypoints with patrol enabled.

Building a route

Stand at each waypoint in order and add it, then start the patrol:

/mnpcai <id> addpoint      # adds a waypoint where you stand
/mnpcai <id> patrol        # toggles patrolling on/off

Each NPC has a default route, and can have more named routes:

/mnpcai <id> <routeId> addpoint
/mnpcai <id> <routeId> setroute position <First|1|2|3|4|5|6|Last>

Modes

npcai:
  default-mode: PATROL    # PATROL = back and forth, LOOP = cycle
  default-speed: 0.25     # blocks per tick
ModeBehaviour
PATROLWalks to the last point, then back along the same path.
LOOPWalks the points in a cycle, returning to the first.
Enable pathfindingDebug in config.yml for verbose route logging while you build a path.
AI & MOVEMENT

Arrival Actions

What an NPC does when it reaches a waypoint.
/mnpcai <id> [routeId] arrival info
/mnpcai <id> [routeId] arrival wait <seconds>
/mnpcai <id> [routeId] arrival animation <name|clear>
/mnpcai <id> [routeId] arrival dialog <treeKey|clear>
/mnpcai <id> [routeId] arrival permission <perm|clear>
/mnpcai <id> [routeId] arrival addcommand <command>
/mnpcai <id> [routeId] arrival clearcommands
Sub-commandWhat it sets
infoShows everything configured for this arrival.
wait <seconds>How long the NPC pauses at the point.
animation <name>Animation played on arrival.
dialog <treeKey>Dialog opened to nearby players on arrival.
permission <perm>Only players with this permission see the arrival dialog/commands.
addcommand <command>Adds a command to run on arrival.
clearcommandsRemoves all arrival commands.
Omit [routeId] to act on the NPC's default route.
AI & MOVEMENT

Escort

An NPC that walks a player somewhere.

An escort is started from a dialog option (Action: ESCORT) or through the API with startEscort(npcId, player). The NPC leads the player to the destination and can play a dedicated animation on the way.

escort:
  smooth-clone-movement: true        # packet movement (needs ProtocolLib)
  move-hologram-during-escort: false
  hologram-refresh-interval: 2       # ticks
  force-hologram-refresh-on-end: true
  hologram-height-boost: 0.5
SettingMeaning
smooth-clone-movementtrue = smooth packet-based movement (ProtocolLib). false = teleport steps, choppier but dependency-free.
move-hologram-during-escortWhether the nametag follows the NPC while escorting.
hologram-height-boostExtra nametag height during an escort.

Escort speed is per NPC (getEscortSpeed / setEscortSpeed), and the animation is set with setEscortAnimation(npcId, name).

EFFECTS

Particles & Potions

Ambient and on-interact effects.
/mnpc addeffect <id> particle <looped|oninteract> <PARTICLE_NAME> [yOffset]
/mnpc addeffect <id> potion <POTION_NAME> <seconds> [amplifier]

A compact colon form is also accepted:

particle:looped|oninteract:PARTICLE[:yOffset]
potion:NAME:seconds[:amplifier]
TypeWhen it plays
loopedContinuously around the NPC.
oninteractOnce, when a player interacts.
potionApplied to the player who interacts.

Managing effects

/mnpc effect <clear|remove> <id>
/mnpc reloadeffects
/npceffects <npcId>                       # opens the effects editor GUI
/mnpceffects <id> <addeffect|removeeffect> ...
particles:
  enabled: true
The Studio's Effects page lists every particle with pagination β€” easier than typing names.
EFFECTS

Glow

Per-player outline colours.

NPCs can glow in any chat colour, globally or for one player β€” commonly driven by quest status.

/glowtest <id> <color>     # preview a glow colour

Through the API:

api.setNPCGlow(npcId, player, ChatColor.GREEN);   // one player
api.setNPCGlowForAll(npcId, ChatColor.GOLD);      // everyone
api.removeNPCGlow(npcId, player);
api.removeNPCGlowForAll(npcId);
api.toggleNPCGlow(npcId, player, true, ChatColor.AQUA);
Glow is driven through a single shared GlowingEntities instance. Do not create your own against the same entities β€” conflicting scoreboard team packets can crash clients.
RESOURCE PACK

How the Pack Works

What ModeledNPCS generates and who needs it.

ModeledNPCS always writes plugins/ModeledNPCS/resourcepack/ModeledNPCS-Dialogs.zip. It contains the dialog parchment textures, the fonts, and the core shader used by SHADER mode.

Players need a resource pack for two separate reasons:

  • Models β€” generated by ModelEngine / BetterModel. Without it, NPCs render as magenta/black blocks.
  • Dialog + GUI textures β€” generated by ModeledNPCS. Needed for SHADER dialogs, the parchment PAPER panel, and the TEXTURED studio style.
Your setupWhat to do
CustomiZer, ItemsAdder or NexoNothing β€” the pack is delivered automatically. See Pack Integrations.
No pack pluginTurn on hosting and ModeledNPCS will merge and serve everything.
Oraxen or your own server packLeave hosting off and add ModeledNPCS-Dialogs.zip to your pack yourself.
resource-pack:
  export: true      # always write ModeledNPCS-Dialogs.zip
RESOURCE PACK

Hosting & Merging

Let ModeledNPCS serve one merged pack.
resource-pack:
  hosting:
    enabled: true
    public-address: ''      # domain/IP players use; empty = server-ip
    port: 8163
    bind: 0.0.0.0
    required: false
    prompt: 'This server uses a resource pack for NPC models and dialogs.'
    resend-on-update: true
  merge:
    modelengine: true
    bettermodel: true
    extra: []               # extra zips/folders, relative to plugins/ModeledNPCS
    check-interval: 5       # seconds between checks for regenerated packs

With hosting on, ModeledNPCS:

  1. Merges the ModelEngine and BetterModel packs with its own into ModeledNPCS-Merged.zip.
  2. Serves it from a built-in web server and sends it to players on join.
  3. Watches the source packs β€” when they regenerate (new models, /meg reload, /bettermodel reload) the merged pack is rebuilt and re-sent.

Merge rules

  • pack.mcmeta β€” format ranges are widened and all overlays are kept
  • Fonts, atlases, lang files and sounds.json are combined
  • Any other conflicting file keeps the later pack, and a warning is logged
  • Zips use fixed timestamps, so unchanged content keeps its SHA-1 and is not re-downloaded
public-address must be reachable by your players. On a hosted machine this is your server's public domain or IP, and the port must be open.
Keep hosting.enabled: false when you use CustomiZer, ItemsAdder or Nexo β€” they already merge the model packs, and two systems sending packs will fight.
RESOURCE PACK

Pack Integrations

CustomiZer, ItemsAdder and Nexo.
resource-pack:
  integrations:
    customizer: true
    itemsadder: true
    nexo: true
    rebuild: true     # run their rebuild command when the pack changes
    shader: true      # include the dialog core shader (SHADER mode only)
PluginWhere the pack goesRebuild command
CustomiZerAdded to resourcepack.merge-packs (only when CustomiZer's resourcepack.enabled is true)/zpack zip
ItemsAdderplugins/ItemsAdder/contents/modelednpcs/resourcepack/iazip
Nexoplugins/Nexo/pack/external_packs/ModeledNPCS.zip/nexo reload pack

ModeledNPCS declares loadbefore for all three, so their own startup build already contains the pack β€” no extra rebuild on boot. When the pack changes later (for example after /mnpc reload), the rebuild command runs automatically.

Files are only rewritten when their content actually changed, so repeated reloads do not trigger pointless rebuilds.
Because these plugins build their own pack.mcmeta, overlays are flattened: the shader variant matching your server's Minecraft version is placed at the pack root.
CONFIGURATION

config.yml

Every option, grouped.

General

KeyDefaultMeaning
max_npc_ids1000Highest NPC id that can be allocated.
debugfalseGeneral debug logging.
pathfindingDebugfalseEscort/pathfinding debug (very verbose).
worldguard_debugfalseWorldGuard region debug.
pathhologramdebugfalsePath hologram debug.
serializeDebugfalseSerialization debug.
hologram-view-distance20Distance at which holograms are visible.
useJsonStoragefalseStore NPCs as JSON instead of SQLite.
useBackupFiletrueKeep a backup copy of NPC data.
limit.<mob>adventurerNPC: 3Per-mob spawn limits.
npc.autoRegisterOrphanedNPCsfalseRe-adopt NPC entities with no data entry.

Interaction

npc:
  interaction:
    left:  true
    right: true
    left_fallback:
      enabled: true
      range: 5.5        # blocks
      angle_deg: 30.0   # cone half-angle
    right_fallback:
      enabled: true
      range: 5.5
      angle_deg: 30.0
  cooldowns:
    command_ms: 3000      # between command runs
    interaction_ms: 500   # between interactions
    click_dedup_ms: 250   # ignores duplicate click packets

The fallback blocks catch clicks that hit air or a block near the NPC β€” useful because large models often have an offset hitbox.

Feature toggles

KeyDefaultMeaning
particles.enabledtrueNPC particle effects.
greetings.enabledtrueGreeting messages.
states.enabledtrueNPC state system.
schedules.enabledtrueTime-of-day schedules.
player_flags.enabledtruePer-player interaction flags.
player_flags.persistenttrueSave flags between restarts.
hologram_animation.enabledtrueAnimated hologram frames.
antiPiracy.enabledfalseAnti-piracy checks.

Auto-look

autolook:
  mode: PACKET             # PACKET (ProtocolLib, smooth) or BUKKIT (teleport)
  watchdog-enabled: false  # forces pitch back to 0 if another plugin rotates NPCs
  period-ticks: 2
  max-step-degrees: 25.0   # higher = turns faster
  max-distance: 100.0
  default-yaw-offset: 0.0
  modelengine-yaw-offsets:
    dummy_model: -90.0     # per-blueprint correction
If a model faces the wrong way, add a per-blueprint entry under modelengine-yaw-offsets instead of rotating every NPC by hand.

Other sections

hover, escort, AdminTool, npcai, gui and resource-pack are documented in their own pages: Hover, Escort, Admin Tool, Routes, Studio, Resource Pack.

CONFIGURATION

dialog_config.yml

Renderer, quest glow and messages.
glow:
  enabled: true
  update-interval-ticks: 60

status:
  NOT_STARTED: { chatColor: RED,    text: '&c&lNot Started' }
  IN_PROGRESS: { chatColor: YELLOW, text: '&e&lIn Progress' }
  COMPLETED:   { chatColor: GREEN,  text: '&a&lCOMPLETED' }

msg:
  ALREADY_STARTED_QUEST: '<red>You''ve already started this quest.</red>'
  ALREADY_COMPLETED: '<red>You''ve already completed this quest.</red>'

renderer:
  mode: PAPER
  paper:
    use-pack-textures: true
    button-width: 220
    close-button: '<gray>Goodbye</gray>'
  shader:
    refresh-ticks: 20        # deprecated / ignored
    chat-fallback: false
    hint-choose: '[F] Choose  [Shift] Leave'
    hint-next: '[F] Continue  [Shift] Leave'
KeyDefaultMeaning
renderer.modePAPERDefault dialog style for all trees.
paper.use-pack-texturestrueDraw the parchment panel (needs the pack).
paper.button-width220Button width in pixels.
paper.close-buttonGoodbyeLabel of the exit button.
shader.chat-fallbackfalseAlso print the dialog in chat β€” the fallback for Sodium / Iris / OptiFine players.
shader.hint-choose / hint-nextβ€”Key hints in the box corner.
shader.refresh-ticks20Ignored. The box is re-sent every tick so it never fades or flickers. Kept so old configs still load.
Before switching mode to SHADER, read the Sodium / Iris / OptiFine warning β€” those players will see no dialog at all.
REFERENCE

All Commands

Every command and sub-command.

/mnpc

CommandDescription
/mnpc create <modelengine|bettermodel|mythicmobs> <name>Creates an NPC at your location.
/mnpc remove <id>Deletes an NPC.
/mnpc listLists every NPC.
/mnpc edit <id>Opens the NPC Studio.
/mnpc manage <id>Alias of edit.
/mnpc move <id>Moves the NPC to you.
/mnpc tp <id>Teleports you to the NPC.
/mnpc look <id> [off]Faces you / disables auto-look.
/mnpc rotate <id> <degrees> <left|right>Rotates the NPC.
/mnpc scale <id> <scale>Sets the model scale.
/mnpc static <id>Toggles static mode.
/mnpc name <id> <custom name> [height]Sets the display name.
/mnpc hidenametag <id>Hides the nametag.
/mnpc shownametag <id>Shows the nametag.
/mnpc resetnametag <id>Resets the nametag to default.
/mnpc hide <id> <permission|remove>Restricts who can see the NPC.
/mnpc addcmd <id> <player|console|sudo|bungee> <command>Adds a click command.
/mnpc removecmd <id> <command>Removes a click command.
/mnpc addeffect <id> <particle|potion> ...Adds an effect.
/mnpc effect <clear|remove> <id>Clears or removes effects.
/mnpc admintool <give|info>Gives the admin wand / shows its settings.
/mnpc cleanholograms [radius]Removes stray holograms.
/mnpc reloadReloads configs, NPCs, dialogs and holograms.
/mnpc reloadnameReloads nametags.
/mnpc reloadanim Β· reloadanimationsReloads animations.
/mnpc reloadeffectsReloads effects.
/mnpc debugPrints debug information.

/mnpcai

CommandDescription
/mnpcai <id> addpointAdds a waypoint where you stand.
/mnpcai <id> patrolToggles patrolling.
/mnpcai <id> setroute position <First|1..6|Last>Sets a specific waypoint slot.
/mnpcai <id> [routeId] arrival infoShows arrival settings.
/mnpcai <id> [routeId] arrival wait <seconds>Pause length at the point.
/mnpcai <id> [routeId] arrival animation <name|clear>Arrival animation.
/mnpcai <id> [routeId] arrival dialog <treeKey|clear>Dialog opened on arrival.
/mnpcai <id> [routeId] arrival permission <perm|clear>Permission gate for the arrival.
/mnpcai <id> [routeId] arrival addcommand <command>Adds an arrival command.
/mnpcai <id> [routeId] arrival clearcommandsClears arrival commands.

Other commands

CommandDescriptionPermission
/mnpcmanage <id>Opens the manager menu for an NPC.modelednpcs.manage
/npceffects <npcId>Opens the effects editor.modelednpcs.effects
/mnpceffects <id> <addeffect|removeeffect> ...Triggers/edits NPC effects.mnpceffects.use
/meganimOpens the ModelEngine animation editor.modelednpcs.meganim
/glowtest <id> <color>Previews a glow colour.modelednpcs.admin
REFERENCE

Permissions

Every permission node.
NodeDefaultGrants
mnpc.useopUse of the /mnpc commands.
modelednpcs.adminopAdmin commands: /mnpcai, /glowtest.
modelednpcs.manageop/mnpcmanage β€” the NPC manager menu.
modelednpcs.effectsop/npceffects β€” the effects editor.
modelednpcs.meganimop/meganim β€” the animation editor.
mnpceffects.useop/mnpceffects.
mnpc.admintoolopUse of the NPC Admin Tool wand.
Per-NPC view permissions are separate and set with /mnpc hide <id> <permission>. Any node you like can be used there.
LuckPerms is recommended. Give builders mnpc.use and mnpc.admintool without full modelednpcs.admin so they can place and edit NPCs but not change routes.
DEVELOPER API

Developer API

Control NPCs from your own plugin, without depending on ModeledNPCS internals.
API artifactfr.elias:ModeledNPCs-API:8.1
Maven releaseshttps://maven.oreostudios.fr/releases
Java17 bytecode β€” compatible with Java 17 and newer
Server APIBukkit/Paper
SourceOreoStudios/ModeledNPCS-API

Install with Maven

<repositories>
    <repository>
        <id>oreostudios-releases</id>
        <url>https://maven.oreostudios.fr/releases</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>fr.elias</groupId>
        <artifactId>ModeledNPCs-API</artifactId>
        <version>8.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Install with Gradle

repositories {
    maven("https://maven.oreostudios.fr/releases")
}

dependencies {
    compileOnly("fr.elias:ModeledNPCs-API:8.1")
}
The API is supplied by ModeledNPCS at runtime. Compile against it as provided / compileOnly β€” never bundle or shade its classes into your plugin.

Declare the runtime dependency

Declare ModeledNPCS in your plugin.yml. Bukkit then loads it first, so the API is registered before your plugin enables.

name: ExampleIntegration
version: 1.0.0
main: com.example.integration.ExampleIntegrationPlugin
api-version: '1.21'
depend: [ModeledNPCS]

Get the API

ModeledNPCsAPI.get() returns the registered service, or null if ModeledNPCS has not enabled. With depend: [ModeledNPCS], check once in onEnable and keep the reference:

package com.example.integration;

import fr.elias.npcs.api.ModeledNPCsAPI;
import org.bukkit.plugin.java.JavaPlugin;

public final class ExampleIntegrationPlugin extends JavaPlugin {
    private ModeledNPCsAPI modeledNPCs;

    @Override
    public void onEnable() {
        modeledNPCs = ModeledNPCsAPI.get();
        if (modeledNPCs == null) {
            getLogger().severe("ModeledNPCS did not register its API");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        getLogger().info("Connected to ModeledNPCS API");
    }
}
The older ModeledNPCsProvider remains available for code using the legacy IModeledNPCsAPI. New integrations should use ModeledNPCsAPI.

Threading

Call API methods that read or change entities, NPC state, configuration or inventories on the server's main thread. Never from an async task. If work starts asynchronously, return to the server thread with your scheduler before touching the API.

Return values

MethodReturns when it fails / is unset
getNPCById and other lookupsnull when the id is unknown.
getEntityByNPCIdnull while the NPC has no spawned entity.
getRoutenull if that route does not exist.
createNPC-1 for an unsupported type or a failed creation.
isNPCActivetrue for NPCs with no configured schedule.
getQuestStatusnull when no installed quest adapter recognises the quest.
getTraderManagernull if the trader service is unavailable.
getNPCHoverHint / getNPCHoverAnimationEmpty string when no per-NPC value is configured.

Returned maps and lists are snapshots unless a method explicitly returns a live handle (see INPCRoute). INPCData is mutable β€” prefer the matching API operation, and after changing data directly call the relevant update or persistence operation.

Version compatibility

Compile against the API version your server's ModeledNPCS build provides. API 8.1 additions need a plugin build that includes 8.1. Older ModeledNPCS 9.4 builds bundle API 8.0 and cannot provide 8.1 methods, even if your integration compiles fine against the newer artifact.
DEVELOPER API

API Methods

The full surface of ModeledNPCsAPI, by area.

Reference by area

AreaMethods
LookupgetNPCById, getEntityByNPCId, getAllNPCIds, getAllNPCs
Display & nametaggetNPCDisplayName, getNPCDisplayNameRaw, getNPCDisplayNameFor, setNPCDisplayName, hideNPCNametag, showNPCNametag, isNPCNametagHidden, reapplyNPCName, reapplyAllNPCNames
Location & lifecyclegetNPCLocation, moveNPC, createNPC, deleteNPC, updateNPC, respawnNPC
Visibility & commandscanPlayerViewNPC, getNPCCommands, addCommandToNPC, runNPCCommands
Effects & auto-lookgetNPCEffects, playInteractEffects, restartLoopedEffect, enableAutoLook, disableAutoLook
RoutesaddRouteWaypoint, clearRoute, getOrCreateRoute, getRoute, setRouteMode, setRouteSpeed Β· handle: INPCRoute
EscortstartEscort, stopEscort, setEscortAnimation, getEscortAnimation Β· options: EscortOptions
Trader & questsopenTraderGUI, getTraderManager, assignQuest, getQuestStatus Β· types: TraderAPI, QuestStatus
DialogsopenDialog, isLuxDialoguesAvailable, triggerLuxDialogue, isPlayerInLuxDialogue, setNPCLuxDialogue, getNPCLuxDialogue, setNPCLuxFirstPage, getNPCLuxFirstPage
GlowsetNPCGlow, removeNPCGlow, setNPCGlowForAll, removeNPCGlowForAll, toggleNPCGlow
HovergetHoveredNPCId, isPlayerHoveringNPC, setNPCHoverEnabled, isNPCHoverEnabled, setNPCHoverHint, getNPCHoverHint, setNPCHoverAnimation, getNPCHoverAnimation
State & schedulesetNPCState, getNPCState, isNPCActive, setNPCSchedule, getNPCScheduleStart, getNPCScheduleEnd
Hologram animationsetNPCHologramFrames, getNPCHologramFrames, setNPCHologramFrameInterval, getNPCHologramFrameInterval
Model integrationsapplyModelEngineModel, respawnModelEngineNPC, spawnMythicMobsNPC, spawnMythicMobsNPCFull, updateMythicMobName, respawnMythicMobNPC

Data types live in fr.elias.npcs.data, events in fr.elias.npcs.events, and the legacy IModeledNPCsAPI in fr.elias.npcs.

Listing and inspecting

for (int id : modeledNPCs.getAllNPCIds()) {
    getLogger().info("NPC " + id + ": " + modeledNPCs.getNPCDisplayName(id));
}

var npc = modeledNPCs.getNPCById(42);
if (npc != null) {
    getLogger().info(npc.getName() + " uses model " + npc.getModelId());
}

Creating and moving

var target = player.getLocation().clone();
modeledNPCs.moveNPC(42, target);
modeledNPCs.respawnNPC(42);

int created = modeledNPCs.createNPC("modelengine", "merchant_blueprint", target);
if (created == -1) {
    player.sendMessage("NPC could not be created; check its type and integration.");
}
Creation types supported through the API are modelengine and mythicmobs. The matching plugin must be installed, and name is interpreted by that integration.

Names, commands and effects

modeledNPCs.setNPCDisplayName(42, "&6Town Guide", 2.2);
modeledNPCs.hideNPCNametag(42);
modeledNPCs.showNPCNametag(42);

modeledNPCs.addCommandToNPC(42, "player: warp town");
modeledNPCs.runNPCCommands(42, player);
modeledNPCs.playInteractEffects(42, player);
modeledNPCs.restartLoopedEffect(42);

getNPCDisplayNameRaw keeps the configured formatting, while getNPCDisplayNameFor(player, id) applies PlaceholderAPI when available and returns a legacy formatted string.

Routes

getOrCreateRoute returns a live handle β€” waypoint, mode and speed changes save through ModeledNPCS. getRoute only looks up and returns null when the route does not exist.

import fr.elias.npcs.data.INPCRoute;

INPCRoute route = modeledNPCs.getOrCreateRoute(42, "market-tour");
route.addWaypoint(player.getLocation().clone());
route.addWaypoint(secondStop);
route.setMode("LOOP");   // or "PATROL"
route.setSpeed(0.25);     // finite, positive blocks per tick

// Convenience setters for the default route:
modeledNPCs.setRouteMode(42, fr.elias.npcs.data.RouteMode.PATROL);
modeledNPCs.setRouteSpeed(42, 0.25);

INPCRoute existing = modeledNPCs.getRoute(42, "market-tour");
if (existing != null) {
    var waypoints = existing.getWaypoints();  // detached copies, unmodifiable list
    existing.clearWaypoints();
}
INPCRouteReturns / does
getNpcId() Β· getRouteId()Owning NPC and route id.
getWaypoints()Unmodifiable list of detached Location copies.
addWaypoint(Location)Appends a waypoint. The world must be loaded.
clearWaypoints()Removes them all.
getMode() Β· setMode(String)"PATROL" or "LOOP".
getSpeed() Β· setSpeed(double)Blocks per tick.
Route ids are normalised by the plugin β€” use a non-blank id for named routes. Route handles are for the server thread.

Escorts

modeledNPCs.startEscort(42, player);          // default route
modeledNPCs.stopEscort(player.getUniqueId());

For a named route and arrival behaviour, use the immutable EscortOptions record:

import fr.elias.npcs.data.EscortOptions;
import java.util.List;
import java.util.Map;

var options = new EscortOptions(
    "market-tour",                                  // route id; null = default route
    List.of("We made it!"),                          // arrival dialog lines
    "market_arrival",                               // arrival dialog tree key, or null
    10,                                              // arrival timeout in seconds
    "Are you still with me?",                        // timeout message, or null
    List.of("console:say {player} arrived"),         // arrival commands
    Map.of("first", new EscortOptions.WalkingDialogEntry(
        List.of("Follow me.", "The market is close."),
        8                                            // seconds between lines
    ))
);
modeledNPCs.startEscort(42, player, options);

Pass empty lists or a null route/tree/message to omit optional settings. Walking-dialog keys keep insertion order, timeouts must be β‰₯ 0, and walking-dialog intervals must be positive.

Traders and quests

import fr.elias.npcs.api.TraderAPI;
import fr.elias.npcs.data.QuestStatus;

TraderAPI traders = modeledNPCs.getTraderManager();
if (traders != null && traders.hasTrader(42)) {
    String displayName = traders.getTraderDisplayName(42);
    traders.openTrade(player, 42);
}
modeledNPCs.openTraderGUI(player, 42);   // convenience

modeledNPCs.assignQuest(player, "intro");
QuestStatus status = modeledNPCs.getQuestStatus(player, "intro");

TraderAPI also exposes reload, getTraderHologramOffset and getDefaultHologramOffset; an unconfigured offset or missing display name returns null. QuestStatus is NOT_STARTED, IN_PROGRESS or COMPLETED, and null when no adapter recognises the quest.

Dialogs and LuxDialogues

modeledNPCs.openDialog(player, 42);

if (modeledNPCs.isLuxDialoguesAvailable()) {
    modeledNPCs.setNPCLuxDialogue(42, "welcome");
    modeledNPCs.setNPCLuxFirstPage(42, "1");
    boolean opened = modeledNPCs.triggerLuxDialogue(player, 42);
    boolean busy   = modeledNPCs.isPlayerInLuxDialogue(player);
}

triggerLuxDialogue returns false if no matching dialogue is configured or the integration cannot start it.

Glow

modeledNPCs.setNPCGlow(42, player, org.bukkit.ChatColor.GOLD);
modeledNPCs.removeNPCGlow(42, player);
modeledNPCs.setNPCGlowForAll(42, org.bukkit.ChatColor.GREEN);
modeledNPCs.toggleNPCGlow(42, player, false, org.bukkit.ChatColor.WHITE);
These methods share ModeledNPCS' own glow manager so scoreboard-team packets do not conflict. Do not create a second glow manager for the same NPCs.

Hover, state, schedule and holograms

modeledNPCs.setNPCHoverEnabled(42, true);
modeledNPCs.setNPCHoverHint(42, "&eTalk to me");
modeledNPCs.setNPCHoverAnimation(42, "wave");
int hoveredId = modeledNPCs.getHoveredNPCId(player);   // -1 if none

modeledNPCs.setNPCState(42, "busy");
String state = modeledNPCs.getNPCState(42);

modeledNPCs.setNPCSchedule(42, 8, 18);   // in-game hours 0..23; (-1, -1) disables
boolean activeNow = modeledNPCs.isNPCActive(42);

modeledNPCs.setNPCHologramFrames(42, List.of("&aOpen", "&eWelcome"));
modeledNPCs.setNPCHologramFrameInterval(42, 20);   // ticks

INPCData

int getId();  String getName();  String getType();
String getCustomName();        void setCustomName(String n);
String getCustomDisplayName(); void setCustomDisplayName(String n);
Location getLocation();        void setLocation(Location l);
List<String> getCommands();    void setCommands(List<String> c);
void addCommand(String c);     void removeCommand(String c);
UUID getEntityUuid();          void setEntityUuid(UUID u);
UUID getInternalUUID();        void setInternalUUID(UUID u);
String getViewPermission();    void setViewPermission(String p);
boolean hasViewPermission(Player p);   boolean isHidden();
boolean isAutoLook();          void setAutoLook(boolean v);
double getHologramHeight();    void setHologramHeight(double h);
double getEscortSpeed();       void setEscortSpeed(double s);
String getLoopedAnimation();   void setLoopedAnimation(String a);
String getInteractAnimation(); void setInteractAnimation(String a);
String getEscortAnimation();   void setEscortAnimation(String a);
int getInteractCooldownSeconds();  void setInteractCooldownSeconds(int s);
String getModelId();           void setModelId(String id);
List<? extends INPCEffect> getEffects();
int getLoopedEffectTaskId();   void setLoopedEffectTaskId(int id);
DEVELOPER API

Events

Three cancellable Bukkit events under fr.elias.npcs.events.
EventFiresCancelling
NPCInteractEventA player interacts with an NPC.Cancels the interaction (dialog and commands).
NPCHoverEventA player's aim enters or leaves an NPC.On ENTER, suppresses that transition's scale, sound and hint. Later hover checks still run.
NPCStateChangeEventAn NPC's state is about to change.Prevents the new state being applied.
import fr.elias.npcs.events.NPCInteractEvent;
import fr.elias.npcs.events.NPCHoverEvent;
import fr.elias.npcs.events.NPCStateChangeEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class NpcListener implements Listener {

    @EventHandler
    public void onNpcInteract(NPCInteractEvent event) {
        var player = event.getPlayer();
        var npc    = event.getNPCData();

        if (npc.getId() == 7 && !player.hasPermission("myplugin.vip")) {
            player.sendMessage("The guard ignores you.");
            event.setCancelled(true);
            return;
        }

        switch (event.getInteractionType()) {
            case LEFT_CLICK        -> { }
            case RIGHT_CLICK       -> player.sendMessage("Hello!");
            case SHIFT_LEFT_CLICK  -> { }
            case SHIFT_RIGHT_CLICK -> player.sendMessage("Secret menu");
        }
    }

    @EventHandler
    public void onNpcHover(NPCHoverEvent event) {
        if (event.getAction() == NPCHoverEvent.HoverAction.ENTER) {
            // event.setCancelled(true) suppresses this hover presentation
        }
    }

    @EventHandler
    public void onNpcStateChange(NPCStateChangeEvent event) {
        if ("maintenance".equals(event.getNewState())) {
            event.setCancelled(true);
        }
    }
}

NPCInteractEvent

MemberReturns
getPlayer()The interacting Player.
getNPCData()INPCData of the NPC.
getInteractionType()LEFT_CLICK, RIGHT_CLICK, SHIFT_LEFT_CLICK or SHIFT_RIGHT_CLICK.
isCancelled() / setCancelled(boolean)Cancellation state.

NPCHoverEvent

Provides the player, the NPC and getAction() β€” HoverAction.ENTER or HoverAction.LEAVE.

NPCStateChangeEvent

Provides the old and new state. Cancelling keeps the NPC in its current state.

Register as usual: getServer().getPluginManager().registerEvents(new NpcListener(), this);