NPC Plugin
SpigotMCModrinthCustomizable NPCs via GUI and API
25.6k downloads 3.3 rating
latest v2.4.0-SNAPSHOT SpigotMC
NpcPlugin
Create, customize, and manage player-like NPCs with an in-game editor GUI, click actions, and a built-in path system.
If you have any suggestions or encounter any issues, you can use the discussion page or via Discord @Eisi05
If you want to make a tutorial video about it, feel free to do so
Supported Versions
Spigot: 1.20.6 - 26.1.2
Paper: 1.21 - 26.1.2
⚠️ Notice
Version 2.3.3 is the last version compatible with Minecraft 1.17.1 - 1.20.5.
Future releases will require Java 21 and will no longer support these Minecraft versions.
Highlights
- In-game NPC editor
- Toggle edit-mode and configure NPCs directly by interacting with them.
- Edit common properties like name, skin, equipment, glow, visibility, tab-list, pose, and more.
- Click Actions (Left / Right / Both)
- Build action chains that run when players click an NPC.
- Built-in action types include:
- Command (run commands; supports @s as player placeholder)
- Server (send players to a BungeeCord server)
- Wait (delay before running the next action)
- Animation (play an animation)
- Path (make the NPC walk along a saved path)
- Path system
- Create paths using points, visualize them, test them with a temporary NPC, and reuse them in NPC actions.
- Localization + PlaceholderAPI
- Ships with language files (default en).
- PlaceholderAPI is supported (soft-depend).
API / Developer Documentation
- Spigot: https://github.com/Eisi05/NpcApi-Spigot/wiki
- Paper: https://github.com/Eisi05/NpcApi-Paper/wiki
Permissions
- npc.admin
- Default: OP
- Grants access to all NPC commands and the in-game editor.
Guides
Installation
Quick Start
1) Create an NPC
2) Enable edit-mode
3) Configure NPC options in the GUI
- Download the jar and place it into your server’s plugins/ folder.
- Start the server once.
- Configure (optional):
- plugins/NpcPlugin/config.yml
- plugins/NpcPlugin/lang/<language>/*.yml
- Restart or run /npc reload.
Quick Start
1) Create an NPC
- /npc create
2) Enable edit-mode
- /npc edit
- Interact with an NPC to open its editor GUI.
3) Configure NPC options in the GUI
- Name
- Skin (player name / UUID / local .png file)
- Use Player Skin (per-player skin)
- Equipment slots
- Visibility / enabled state
- Tab list visibility
- Hide nametag
- Pose
- Skin parts
- Glowing + color
- Look-at-player radius / interval
- Scale
- Teleport to NPC / teleport NPC to you
- Delete NPC
Click Actions (Left / Right / Both)
In the NPC GUI go to Click Action.
You can configure actions separately for:
Action editing tips
Common action types
Command
Server (BungeeCord)
Sends the player to another BungeeCord server.
Example server name:
Wait
Path
In the NPC GUI go to Click Action.
You can configure actions separately for:
- Left click
- Right click
- Both (combined)
Action editing tips
- Remove an action: middle-click an existing action.
- Add actions quickly: shift-click an action type to append it.
- Reorder / insert: pick up an action type onto your cursor and click a slot.
Common action types
Command
- Input is requested without leading / (the plugin stores it as /<command>).
- You can use @s to refer to the clicking player.
- There is optional syntax validation.
Code (Text):
warp spawn
server hub
msg @s Welcome!
server hub
msg @s Welcome!
Sends the player to another BungeeCord server.
Example server name:
Code (Text):
hub
- L/R click adjusts by ±0.1s
- Shift+L/R adjusts by ±1.0s
Path
- Pick a path name + a speed (0.1–1.0).
- If needed, the plugin can create a short path from the NPC’s current location to the start of the saved path.
Paths are shared and stored in:
Create a path from points
Record a path by walking
Edit an existing path
This loads the saved path’s waypoints into the point list so you can remove/add points and re-create it.
List / delete / test paths
- plugins/NpcPlugin/paths.yml
Create a path from points
- Add points at your current location:
Or add at a specific index:Code (Text):/npc path point add
Code (Text):/npc path point add <index> - List points:
Code (Text):/npc path point list [page] - Visualize / toggle visualization of current points:
Code (Text):/npc path visualize points - Create the path:
Code (Text):/npc path create <name> [maxIterations] [allowDiagonalMovement]
Code (Text):
/npc path visualize <name>
- Start recording:
Code (Text):/npc path record start - Walk the route.
- Stop recording:
Code (Text):/npc path record stop - Create the path:
Code (Text):/npc path create <name>
Edit an existing path
Code (Text):
/npc path edit <name>
List / delete / test paths
Code (Text):
/npc path list [page]
/npc path delete <name>
/npc path test <name> [speed]
/npc path delete <name>
/npc path test <name> [speed]
Core
Config
Exceptions (startup load failures)
Paths
All path commands are under:
Main subcommands:
Code (Text):
/npc create
/npc copy <uuid>
/npc edit
/npc list
/npc tp <uuid>
/npc tphere <uuid>
/npc reload
/npc version
/npc update
/npc copy <uuid>
/npc edit
/npc list
/npc tp <uuid>
/npc tphere <uuid>
/npc reload
/npc version
/npc update
Code (Text):
/npc config reload
/npc config debug [true|false]
/npc config avoid-command-check [true|false]
/npc config look-at-update-interval [ticks]
/npc config input-time [seconds]
/npc config auto-update [true|false]
/npc config placeholder-timer [ticks]
/npc config list
/npc config debug [true|false]
/npc config avoid-command-check [true|false]
/npc config look-at-update-interval [ticks]
/npc config input-time [seconds]
/npc config auto-update [true|false]
/npc config placeholder-timer [ticks]
/npc config list
Code (Text):
/npc exceptions [page]
/npc exceptions show <name>
/npc exceptions delete <name>
/npc exceptions show <name>
/npc exceptions delete <name>
All path commands are under:
Code (Text):
/npc path ...
Code (Text):
point add [index] [location] [rotation]
point remove [index|location]
point list [page]
point clear
create [name] [maxIterations] [allowDiagonalMovement]
delete <name>
list [page]
visualize [name]
visualize points
record start|stop
test <name> [speed]
edit <name>
point remove [index|location]
point list [page]
point clear
create [name] [maxIterations] [allowDiagonalMovement]
delete <name>
list [page]
visualize [name]
visualize points
record start|stop
test <name> [speed]
edit <name>
Config file:
- plugins/NpcPlugin/config.yml
- look-at-update-interval: time in ticks between “look at player” updates
- avoid-command-check: if true, commands added to NPC actions will not be strictly validated
- debug: enables extra debug logging
- input-time: conversation timeout in seconds (if < 0, no timeout)
- auto-update: automatically updates NPCs after option changes
- placeholderTimer: time in ticks between placeholder refreshes
“This plugin does not support Paper servers!”
Server action does nothing
Can’t open the editor GUI
- You are running the Spigot build on a Paper server. Install the Paper build instead.
Server action does nothing
- Ensure BungeeCord is set up and the server names match your proxy configuration.
Can’t open the editor GUI
- Make sure you:
- Have npc.admin
- Enabled edit-mode via /npc edit
- The NPC is marked as editable
Comments 0
No comments yet. Be the first to share your thoughts.