NPCs

NPCs

NPCs is a standalone Paper plugin for creating and managing NMS-backed fake-player NPCs. It is built for servers that need lightweight NPCs for testing, shops, patrols, guards, and plugin integrations without requiring Citizens.

Standalone NPCs are saved by default with YAML storage. SQLite, MySQL, and MariaDB are also supported for larger setups.

Features

• Spawn fake-player NPCs at your position or exact world coordinates.
• Clone existing NPCs, including role, owner, patrol, trader offers, and equipment.
• Select NPCs by short ID, full UUID, profile name, or display name.
• List all NPCs or nearby NPCs by radius and page.
• Assign NPC roles: neutral, trader, guard, or bodyguard.
• Trader NPCs open villager-style merchant windows with configurable item-for-item offers.
• Guard NPCs patrol and attack nearby hostile mobs.
• Bodyguard NPCs follow an assigned online owner and attack nearby threats.
• Linear patrols let NPCs move between saved waypoints.
• Radius patrols let NPCs wander around a chosen centre point.
• Equipment mode lets staff right-click NPCs with armour, shields, weapons, or held items.
• Equipment can be cleared by slot or all at once.
• NPCs can be moved, teleported, removed, saved, backed up, reloaded, and audited.
• Invulnerability, auto-respawn, respawn delay, collision, movement speed, attack range, attack damage, trader offer limits, and cleanup behaviour are configurable.
• Storage status, runtime NMS availability, live handles, linked NPC count, respawning count, and role counts are visible through status commands.
• Database connections use the shared secure storage layer, including safer default TLS settings for MySQL/MariaDB and redacted credential handling.

Integrations

• Bodyguard: Bodyguard can use NpcsApi to create, move, and remove linked fake-player visuals for /bodyguard spawn player.
• Bukkit permissions: works with standard permission plugins, including ThunderPerms-managed permission setups.

NPCs also registers NpcsApi so other plugins can create linked runtime fake players, move linked NPCs, remove linked NPCs, inspect NPC records, query nearby NPCs, and check storage health.

Linked NPCs are intended for other plugins and are not persisted. Standalone NPCs created through /npcs are persisted.

Commands

Main command aliases:

• /npcs
• /npc

Common commands:

• /npcs spawn [name]
• /npcs spawnat <world> <x> <y> <z> [name]
• /npcs clone [id|name] [name]
• /npcs list
• /npcs near [radius] [page]
• /npcs select <id|name>
• /npcs selected
• /npcs info [id|name]
• /npcs set [id|name] <role|owner|patrol-radius> <value>
• /npcs role [id|name] <neutral|trader|guard|bodyguard>
• /npcs owner [id|name] <player|none>
• /npcs equip [id|name]
• /npcs equip clear [id|name] [slot|all]
• /npcs patrol add [id|name]
• /npcs patrol radius [id|name] <radius>
• /npcs patrol stop|clear|list [id|name]
• /npcs trader add [id|name] <item> <amount> <price-item> <price-amount>
• /npcs trader remove|clear|list [id|name] [index]
• /npcs remove <id|name|all>
• /npcs move <id|name> <world> <x> <y> <z> [yaw] [pitch]
• /npcs tp [id|name]
• /npcs status
• /npcs stats
• /npcs save
• /npcs backup
• /npcs reload

Permissions

• npcs.command
• npcs.spawn
• npcs.clone
• npcs.remove
• npcs.move
• npcs.teleport
• npcs.near
• npcs.role
• npcs.equip
• npcs.patrol
• npcs.trader
• npcs.status
• npcs.save
• npcs.backup
• npcs.reload
• npcs.admin

Notes

NPCs uses a contained reflection adapter for Paper's Mojang-mapped runtime internals. If fake-player support is unavailable on a server version, the plugin fails cleanly with a command message and console warning.

Normal use does not require a database.

NPCs is not a replacement for Citizens. It is a lightweight fake-player NPC system for controlled server features, testing, shops, guards, and integrations.