Commands / Reference

Command reference

Every command this plugin adds. Anywhere you see <name>, you can leave it out if you have an NPC selected — the plugin will tell you if you haven't selected one and the command needs a target.

Creating and removing

CommandWhat it does
/npc create <name> [type]Spawns a new NPC at your location. Leave out [type] to get a player-shaped NPC. Selects the new NPC automatically.
/npc remove <name>Deletes an NPC permanently.
/npc copy <name> <newname>Duplicates an NPC under a new name, including its skin, actions, equipment, tags, path, and every other setting.
/npc listLists every NPC that exists.
/npc nearbyLists NPCs near your current location.
/npc info <name>Shows everything currently set on an NPC.

Selecting

CommandWhat it does
/npc select <name>Marks an NPC as your active one.
/npc selectNo name given — selects whichever NPC is physically closest to you right now.
/npc deselectClears your current selection.

Position and movement

CommandWhat it does
/npc teleport <name>Teleports you to the NPC.
/npc move_here <name>Moves the NPC to where you're standing.
/npc move_to <name> <x> <y> <z>Moves the NPC to exact coordinates.
/npc rotate <name> <yaw> <pitch>Sets the exact direction the NPC faces.
/npc center <name>Snaps the NPC to the center of its current block, instead of an off-center spot.
/npc turn_to_player <name> <true|false>Makes the NPC's head and body turn to face nearby players automatically.
/npc gravity <name> <true|false>Turns falling on or off. Off by default, so NPCs stay exactly where you put them.

Appearance

CommandWhat it does
/npc displayname <name> <text>Sets the name shown above the NPC's head. Supports color codes and MiniMessage formatting — see Skins for how text formatting is handled.
/npc type <name> <entitytype>Changes what kind of entity the NPC looks like (PLAYER, ZOMBIE, VILLAGER, and so on).
/npc scale <name> <factor>Resizes the NPC. 1.0 is normal size.
/npc skin <name> <username|@none|@mirror>Sets a player-type NPC's skin. See Skins.
/npc skinlayers <name> <layer> <true|false>Shows or hides one part of a skin (cape, jacket, sleeves, pants, hat) independently.
/npc glowing <name> <color|disabled>Makes the NPC glow a color, the way a glowing potion effect would.
/npc collidable <name> <true|false>Whether players physically bump into the NPC or walk straight through it.
/npc show_in_tab <name> <true|false>Whether a player-type NPC shows up in the tab player list.

Visibility

CommandWhat it does
/npc visibility <name> <ALL|PERMISSION_REQUIRED|MANUAL>ALL shows the NPC to everyone, PERMISSION_REQUIRED only to players with the npcs.see permission, MANUAL hides it from everyone until you control it through other means.
/npc visibility_distance <name> <blocks>How far away a player can be and still see the NPC. -1 means use the server default.
/npc interaction_cooldown <name> <ms>How long (in milliseconds) a player must wait between clicks before actions fire again.

Equipment and attributes

CommandWhat it does
/npc equipment set <name> <slot> <material>Puts an item in the NPC's hand, head, chest, legs, or feet slot.
/npc attribute set <name> <attribute> <value>Stores a custom key/value pair on the NPC, for your own use or another plugin's, via the API.

Behavior

CommandWhat it does
/npc action <name> <trigger> add <type> <value>Adds something the NPC does when clicked. See Actions & triggers for the full list of types and triggers.
/npc animation <name> <type>Plays a one-off animation (arm swing, take damage, critical hit, and so on) immediately.
/npc path add|remove|clear|listBuilds a sequence of waypoints the NPC walks between.
/npc group assign|remove|create|listGroups NPCs together so you can manage several at once.

Extras

CommandWhat it does
/npc tag add|remove|listAttaches a floating text or item display near the NPC, with its own offset.
/npc hologram add|remove|set|listStacks multiple lines of floating text above the NPC, like a multi-line sign.
/npc migrate citizens [confirm] [citizensnpcname]Brings Citizens NPCs over to this plugin. See Citizens migration for the full walkthrough.

Admin commands

CommandWhat it does
/npcs reloadReloads the config and every NPC from disk.
/npcs saveForce-saves every NPC right now.
/npcs infoShows the plugin version and some basic stats.
/npcs debugShows whether debug logging is on.
/npcs skin_cache clearClears cached skin lookups, forcing fresh downloads next time.