NPC Plugin - Speedgot

NPC Plugin -----

Customizable NPCs via GUI and API

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

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

While edit-mode is enabled:

Interact with an NPC to open its editor GUI.

If the NPC is not editable, you’ll get: This NPC is not editable!

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:

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.

Examples:

Code (Text):

warp spawn
server hub
msg @s Welcome!

Server (BungeeCord)
Sends the player to another BungeeCord server.
Example server name:

Code (Text):

hub

Wait

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:

plugins/NpcPlugin/paths.yml

Create a path from points

Add points at your current location:

Code (Text):

/npc path point add

Or add at a specific index:

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]

After creation you can visualize it:

Code (Text):

/npc path visualize <name>

Record a path by walking

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>

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

Code (Text):

/npc path list [page]
/npc path delete <name>
/npc path test <name> [speed]

Core

Code (Text):

/npc create
/npc copy <uuid>
/npc edit
/npc list
/npc tp <uuid>
/npc tphere <uuid>
/npc reload
/npc version
/npc update

Config

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

Exceptions (startup load failures)

Code (Text):

/npc exceptions [page]
/npc exceptions show <name>
/npc exceptions delete <name>

Paths
All path commands are under:

Code (Text):

/npc path ...

Main subcommands:

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>

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