NPCS
A lightweight NPC plugin for Paper servers. NPCS lets you create and configure interactive NPCs no dependencies required with SQLite persistence, click actions, and a builtin migration system for importing NPCs from Citizens and FancyNpcs.
Requirements
- Paper 1.21.9 or newer
- Java 25+
NPCS is built against Paper's Mannequin API, introduced in 1.21.9. Mannequin is a stable, first-party Paper API for player-look NPCs, so NPCS does not rely on packet hacks or fake-player tricks to render its NPCs. Because of this, NPCS is expected to keep working on newer Paper versions without needing an update for every release though as always, check the releases page if you're jumping to a major new Minecraft version.
NPCS works standalone. Citizens and FancyNpcs are optional and only used if you want to migrate existing NPCs from one of them see Migration below.
Features
- SQLite-backed persistence NPCs survive restarts and chunk unloads despite entity.isPersistent being false
- Custom skins by Minecraft player name (online or offline, resolved via Mojang profile lookup)
- Click-triggered actions: run commands as the player or console, or send chat messages
- Support for MiniMessage tags, legacy
&/§color codes, and JSON text components in names and messages - Gravity, immovability, invulnerability, and look-at-player toggles per NPC
- Folia support
- Migration system for importing NPCs from Citizens and FancyNpcs
- bStats metrics
Installation
- Download
NPCS-<version>.jarfrom the releases page or Modrinth. - Drop it into your server's
plugins/folder. - Restart the server.
No further setup is required.
Commands
All commands are under /npcs (alias /npc).
| Command | Description |
|---|---|
/npcs help |
Show the help dialog |
/npcs create <name> [entitytype] |
Create an NPC at your location |
/npcs type <entitytype> |
Change the entity type of the selected NPC |
/npcs select [name] |
Select an NPC to edit, or clear your selection |
/npcs rename <newName> |
Rename the selected NPC |
/npcs remove [name] |
Remove an NPC |
/npcs skin <skin> |
Set the skin of the selected NPC (Mannequin-type NPCs only) |
/npcs addcommand <action> <executor> <command> |
Attach a command to a click action |
/npcs removecommand [targetNpc] <commandId> |
Remove an attached command |
/npcs message <action> <msg> / /npcs sendmessage <action> <msg> |
Attach a chat message to a click action |
/npcs removemessage [targetNpc] <messageId> |
Remove an attached message |
/npcs gravity |
Toggle gravity on the selected NPC |
/npcs immovable |
Toggle whether the selected NPC can be pushed |
/npcs invulnerable |
Toggle invulnerability on the selected NPC |
/npcs lookatme |
Toggle whether the selected NPC turns to face nearby players |
/npcs copy <newName> |
Duplicate the selected NPC |
/npcs teleport |
Teleport yourself to the selected NPC |
/npcs tphere |
Teleport the selected NPC to you |
/npcs near |
List NPCs near your location |
/npcs list |
List all NPCs |
/npcs migrate [migrator] |
Migrate NPCs from another plugin — see Migration |
/npcs reload |
Reload the plugin |
Click actions accept LEFT_CLICK, RIGHT_CLICK, or CLICK (either click) matching is case-insensitive, and LEFT/RIGHT are accepted as shorthand for the two specific-click triggers.
Migration
NPCS can import NPCs directly from Citizens or FancyNpcs, either from the live plugin if it's installed alongside NPCS, or straight from that plugin's save file if it isn't.
Run /npcs migrate with no arguments to see a list of available migrators, then run it again with one:
/npcs migrate citizens # From a running Citizens installation
/npcs migrate citizens-file # Directly from Citizens/saves.yml
/npcs migrate fancynpcs # From a running FancyNpcs installation
/npcs migrate fancynpcs-file # Directly from FancyNpcs/npcs.yml
Migration copies over each NPC's name, location, entity type, skin, and click actions into NPCS's own database. From Citizens, this means commands attached via its Command Trait. From FancyNpcs, this includes both commands and chat messages. Action types with no NPCS equivalent (for example FancyNpcs's wait or need_item actions) are skipped and logged as a warning rather than silently dropped or guessed at.
Migration is built on an extensible Migrator system — every migrator is a small class that implements a single migrate() method, and new ones can be registered at runtime. If you maintain another NPC plugin (or want to migrate from a format not listed above), you can register your own migrator against NPCS's registry without needing a core update.
API
A public API for NPCS is planned for a future release, so other plugins will be able to create, query, and modify NPCS-managed NPCs programmatically including registering custom migrators without reflection. There's no timeline yet check the releases page for updates.
Metrics
NPCS reports anonymous usage statistics via bStats:
bstats.org/plugin/bukkit/NPCS-Hihelloy/33242
This can be disabled globally for all plugins on your server via plugins/bStats/config.yml.
Permissions
Access is gated by npcs.admin or npcs.use at the top level, with a permission per subcommand (npcs.command.<subcommand>, e.g. npcs.command.create, npcs.command.migrate) for granular control.
Support
Found a bug or have a feature request? Open an issue on GitHub.
