NPCs

NPCs

NMS-backed fake-player NPCs for shops, patrols, guards, bodyguards, quest actors, testing, and plugin integrations without requiring Citizens.

NPCs is a standalone Paper plugin for creating and managing lightweight fake-player NPCs. It is built for servers that need controllable NPCs for staff testing, traders, patrol routes, guards, bodyguards, quest scenes, court scenes, reconstruction playback, and other plugin integrations.

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 standalone NPCs, including role, owner, patrol state, trader offers, equipment, and stat overrides.
• Select NPCs by short ID, full UUID, profile name, or display name.
• List all NPCs or nearby NPCs by radius and page.
• Open a clickable management inventory for common NPC actions.
• Assign NPC roles: neutral, trader, guard, or bodyguard.
• Neutral NPCs can stand still or patrol when configured.
• 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.
• Bodyguards prioritise staying leashed to their owner while protecting them, reducing stalled chases and emergency teleports.
• Bodyguards use a faster default follow step so they can keep up better with sprinting owners.
• 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, armour group, or all at once.
• Per-NPC stat overrides support movement speed, attack damage, attack speed, attack cooldown ticks, and reset-to-default controls.
• NPCs can be moved, teleported, removed, saved, backed up, reloaded, audited, and inspected through status commands.
• Linked NPCs can be created by other plugins without being persisted as standalone NPC records.
• Linked NPCs can opt into managed behaviour, roles, trader offers, patrol radius, glowing state, protection, vulnerability, respawn delay, threat targets, and movement helpers.
• Invulnerability, vulnerability, auto-respawn, respawn delay, collision, movement speed, attack range, attack damage, attack cooldown, trader offer limits, fake-player tab visibility, fake-player world-player counting, and clean-up behaviour are configurable.
• Fake-player NPCs can stay out of the tab list and avoid counting as normal world players by default.
• Runtime status shows NMS availability, total NPCs, standalone NPCs, linked NPCs, live handles, respawning count, fake-player accounting, dirty state, storage health, and storage description.
• Audit/stat commands show role counts, live handles, respawn count, storage health, and fake-player accounting.
• Temporary traversal blocks are protected, tracked, cleaned up automatically, and can be manually requested for clean-up.
• Traversal assist can place temporary bridge or drop-recovery blocks when NPCs need help crossing gaps or descending safely.
• NPCs avoid temporary traversal placement in configured blocked worlds such as court, jail, reconstruction, and scene worlds.
• Linked quest NPCs and other managed NPCs avoid placing temporary cobblestone traversal blocks inside constructed interiors or next to remembered village structure blocks.
• NPCs that spawn or path around trees can try safer descent instead of only building forward.
• Bow-equipped linked NPCs can hold a high perch while they have a clear shot, then come down when the target or owner moves too far away.
• NPCs can use temporary boats for longer or deeper water crossings when pathing around shores.
• Boat crossings are bounded by configurable water distance, depth, scan range, and boat speed.
• NPCs honour CommandFoundry vanish when CommandFoundry is installed, so vanished players are not selected as owners, threats, linked threat targets, or attack victims.
• Database connections use the shared secure storage layer, including safer default TLS settings for MySQL/MariaDB and redacted credential handling.

Storage And Security

• YAML storage works by default with no external database setup.
• SQLite, MySQL, and MariaDB are supported for larger setups.
• SQLite paths are confined to the plugin data folder.
• Example MySQL and MariaDB URLs use certificate and hostname verification.
• JDBC credentials are handled through the shared secure storage layer.
• Linked NPCs created through the API are runtime-only and are not saved as standalone /npcs records.
• Temporary traversal blocks are journaled with ownership metadata so they can be cleaned up without touching unrelated blocks.
• Fake-player support fails cleanly with command feedback and console warnings when the server runtime is unsupported.

Commands

Main command aliases:

• /npcs
• /npc

Common commands:

• /npcs help
• /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 gui [id|name]
• /npcs set [id|name] <role|owner|patrol-radius|move-speed|attack-damage|attack-speed|attack-cooldown-ticks|all> <value>
• /npcs stats
• /npcs stats runtime
• /npcs stats [id|name]
• /npcs stats [id|name] <move-speed|attack-damage|attack-speed|attack-cooldown-ticks|all> <value|+delta|reset>
• /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 [id|name]
• /npcs patrol clear [id|name]
• /npcs patrol list [id|name]
• /npcs trader add [id|name] <item> <amount> <price-item> <price-amount>
• /npcs trader remove [id|name] [index]
• /npcs trader clear [id|name]
• /npcs trader list [id|name]
• /npcs remove <id|name|all>
• /npcs move <id|name> <world> <x> <y> <z> [yaw] [pitch]
• /npcs tp [id|name]
• /npcs status
• /npcs audit
• /npcs tempblocks status
• /npcs tempblocks cleanup [namespace] [key]
• /npcs save
• /npcs backup
• /npcs reload

Permissions

Every permission defaults to operator access.

Grant everything:

• npcs.admin

Or assign individual permissions:

• npcs.command
• npcs.spawn
• npcs.clone
• npcs.remove
• npcs.move
• npcs.teleport
• npcs.gui
• npcs.near
• npcs.role
• npcs.equip
• npcs.patrol
• npcs.trader
• npcs.stats
• npcs.status
• npcs.tempblocks.cleanup
• npcs.save
• npcs.backup
• npcs.reload

Optional Integrations

NPCs is fully usable on its own, but it can work with other plugins when they are installed.

• CommandFoundry vanish is honoured when available, preventing NPCs from seeing, targeting, following, or attacking vanished players.
• ThunderPerms and other Bukkit permission managers can control NPCs permissions through the normal Bukkit permission system.
• Bodyguard can use NpcsApi to create, move, equip, protect, and remove linked fake-player visuals.
• StormQuests can use linked NPCs for invulnerable, geared, glowing quest NPCs and escort NPCs.
• BlockLedger can use NPCs fake-player support for reconstruction playback when configured to require NPC actors.
• Other plugins can use NpcsApi to create linked runtime fake players, move linked NPCs, step or face them toward targets, remove one linked NPC or a whole namespace, set equipment, set roles, set trader offers, set patrol radius, set glowing state, set damage protection, set vulnerability, set respawn delay, set or clear threat targets, query temporary NPC blocks, request temporary block clean-up, inspect NPC records, query nearby NPCs, resolve fake-player handles, trigger fake-player attacks, and check storage health.

These hooks are optional. If the other plugins are missing, NPCs keeps working normally with its own standalone NPCs, commands, storage, roles, patrols, traders, guards, bodyguards, and management tools.

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.

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

Normal use does not require a database. YAML storage is the default, while SQLite, MySQL, and MariaDB are available for servers that prefer database-backed persistence.