NAV
Example

Care and feeding of NPCs

Creating NPCs can be fun! You can add people or animals in specific locations or have them follow paths around the world. You can have them react to things or go to different locations at random, by time of day, or even weather. You may not do anything more than make an NPC with the look of a police officer that stands guard. That is great too.

This is a basic workflow for creating an all-purpose NPC.

For example, create a wandering priest villager:

/npc create friend1
/npc type villager
/npc profession PRIEST
/npc lookclose
/waypoint provider wander

Depending on the NPC type, additional options may be available.

All other information is available from Citizens Wiki.

Create the NPC

Create a new NPC

/npc create friend1

You can create an NPC with the /npc create command. For example, create the NPC and then assign its mob type and trait. The mob type is any creature type like CHICKEN, PIG, PLAYER. The default type is PLAYER.

create

/npc create [name] ((-b,u) --at (x:y:z:world) --type (type) --trait ('trait1, trait2...') --b (behaviours))

Parameters

Parameter Required Description
name yes Name to give the NPC.
b no Set baby size instead of an adult.
u no No idea.
at no Coordinates and world to place the NPC.
type no Mob type to use.
trait no Adds the trait type to the NPC. NPCs can have multiple traits.
behavior no Adds and removes behaviours from an NPC. A behaviour is a script file that is executed and adds ‘goals’ to the NPC which can run every tick. These can do anything you can program/think of!

Select NPC

Select the NPC named friend1. Then display information about the selected NPC.

/npc select friend1
/npc

When you create an NPC, it is selected automatically. Anytime after that you must select the NPC before you can make any changes to it.

select

/npc select|sel [id|name] (--r range)

Parameters

Parameter Description
name Name of NPC.
id ID number of NPC.
r Block range of NPC.

information

/npc

Gives information about the currently selected NPC such as name, id, type, spawn location, traits.

Set a mob type

Set the NPC to a baby pig:

/npc create piglet
/npc type pig
/npc age baby

Set the NPC to a skeleton:

/npc create dembones
/npc type skeleton

Changes an NPC’s mob type. By default it is a player. Possible types are here supported mob types

type

/npc type [mob_type]

Parameters

Parameter Description
type Mob type name to change the NPC into.

Mob types

Here is a short list of mobs you can create. There are probably more.

Passive Hostile
bat blaze
chicken cave spider
cow creeper
dolphin enderman
horse ender_dragon
iron_golem ghast
minecart magma_cube
mushroom_cow phantom
ocelot pig_zombie
parrot player
pig shulker
polar_bear silverfish
pufferfish skeleton
rabbit slime
sheep spider
squid witch
snowman wolf
tropical fish wither
turtle zombie
villager zombie_villager

Select the NPC costume

Sets an NPC’s skin name. By default, the costume / skin is the name of the NPC. You can keep the name you want but change the costume to the skin of another player.

Change the skin of NPC named marvin

/npc select marvin
/npc skin -l bob_the_builder

By default an NPC will have the default Steve or Alex skin. If you want a custom skin you can do one of the following:

For example, search online for a skin you like, load it into your character first. Then relogin to the minecraft world. Set the NPC to use your skin (without the ‘l’ option). Log out, and reset your skin. Then log in again. Now your NPC will have the previous skin and you will be back to the one you normally use.

Use -l to set the skin to always update to the latest.

skin

/npc skin (-c -l(atest)) [name]

Parameters

Parameter Description
l Retrieve the latest skin for the player name.
name The user ID of the skin to retrieve.
c No idea.

Set villager profession

Set the villager profession to FARMER:

/npc create oldmac
/npc type villager
/npc profession FARMER

If the NPC is a villager mob, changes villager profession.

profession

/npc profession [profession_name]

Parameters

Parameter Description
profession_name Villager profession. Supported professions are BLACKSMITH, LIBRARIAN, BUTCHER, FARMER, or PRIEST.

Set animal or villager age

Set the animal or villager age to baby:

/npc create nelly
/npc type villager
/npc age baby

Modify an animal or villager NPC’s age.

age

/npc age [adult, baby, integer, -l]

Parameters

Parameter Description
adult Set age to adult.
baby Set age to baby.
integer Specifies an exact age.
l Toggles whether the age is locked.

Add a trait or behavior

Traits are add-on personality packs such as sentinel and npcdestinations. When these additional plugins are installed they can give additional personality traits. For example the Sentinel plugin enables NPCs to guard players or areas and attack selected mobs. The NPCDestinations plugin gives your NPCs location and time based personalities such as going to work during the day and heading home at night.

These plugins must be installed into the server to work.

Behaviors are script files that are installed into the NPC plugin folder. Some examples of scripts can be found at the Citizens Script Repo or the mcmonkey studios. We are not using any of these though.

Add a trait

Make an NPC a Sentinel

/npc create knight
/npc select knight
/trait sentinel
/npc equip
Right-click NPC with the weapon or armor

Remove the sentinel trait from the NPC:

/npc select knight
/trait remove sentinel

Set the NPC to use an available trait. After an NPC is assigned to a trait, additional options become available for that NPC. For example, after setting an NPC trait to sentinel, you could use the command /sentinel addtarget MONSTERS to tell that NPC to target nearby monsters. See the sentinel or NPCDestinations instructions for more information.

The installed traits are:

trait

/trait add|remove [trait_name]

Parameters

Parameter Description
trait_name Name of trait.

Sentinel character

The Sentinel plugin enables NPCs to guard players or areas and attack selected mobs.

After you set the NPC trait to sentinel the sentinel commands are enabled for that NPC. More information about Sentinels can be found on this website.

Set the NPC to chase monsters and give it a weapon.:

/npc select knight
/trait sentinel
/npc equip
Right-click NPC with the weapon or armor
/sentinel addtarget MONSTERS

Set the NPC to use the sentinel trait and tell it to guard a player named Bob:

/npc select knight
/trait sentinel
/sentinel guard Bob

Get information about the sentinel settings for an NPC

/npc select soldier1
/npc

Verify the NPC has the sentinel trait

/sentinel info
/sentinel targets

Set two NPCs to attack anyone holding a sword:

/npc create Thing1
/npc select Thing1
/trait add sentinel
/sentinel addtarget helditem:.*sword
/npc equip
Hold a sword and right click on the NPC

/npc create Thing2
/npc select Thing2
/trait add sentinel
/sentinel addtarget helditem:.*sword
/npc equip
Hold a sword and right click on the NPC

Sentinel commands

Sentinel notes

• Damage value for a Sentinel NPC can be set to “-1” to auto-calculate from held item (otherwise, it will used as a raw HP damage amount). • Armor value can be set to “-1” to auto-calculate from equipped armor (otherwise, set a value between 0.0 and 1.0 to indicate how much of any damage will be blocked).

Resetting Sentinel locations:

Sentinel targets

These are all valid targets and ignores:

Sentinel invulnerable only to players

Set the sentinel to ignore players (“/sentinel addignore players”), then enable “protected” config option - find:

Whether NPCs are protected from damage by ignore targets. protected: false

in your config and set it to true instead of false (then restart server).

That will cause Sentinel NPCs to only take damage from non-ignored targets - and since we added ‘players’ to ignore, the Sentinel won’t take damage from players but will take damage from everything else!

NPC Destinations character

The NPCDestinations plugin gives your NPCs location and time based personalities such as going to work during the day and heading home at night.

After you set the NPC trait to npcdestinations the npcdestinations commands are enabled for that NPC. You can quickly set the NPC to use NPC Destinations using the /npcdest autoset command.

NPC Destinations enables most commands through its interface in the chat window. You can click on the features in the chat window to set them directly in the chat window. To reopen that chat dialog use the command /npcdest info More information about NPC Destinations, including videos, can be found on this website.

For example, create an NPC that has a morning and night location:

/npc create worker1
/npcdest autoset

Go to the morning location 
/npcdest addlocation sunrise

Go to the evening location 
/npcdest addlocation sunset
/waypoint provider npcdestinations

/npcdest info

Once you set destinations you can add some extra options such as:

Some NPC Destination tips

Here are some quick gotchas that might slow your testing down:

To help understand the pathfinding consider activating /npcdest debug. This mode enables you to see the pathfinding attempts and hopefully track down where a path fails. You can visually see the NPC calling out for a location to make a path to.

Animations

When this plugin is running you can set the following actions to occur when the NPC arrives at a location set by NPC Destinations.

NPC Destinations Location Commands

To see the syntax for the commands, type /npcdest in the chat window and hover the mouse over a command.

NPC Destinations Config Commands

Tell them what to talk about

Enable the text editor

Add some dialog to the NPC fasttalker1

/npc select fasttalker1
/npc text

Enable the text editor. Editing a NPC’s text is simple. Follow the in-game directions to add, edit, and remove text from NPCs. A NPC being a “random-talker” means that it will repeat random phrases from its list of text. If “random” is false, it will loop through the text linearly. Changing its close-talker setting by typing “close” will toggle whether a NPC talks when a player comes within 5 blocks. If close is false, the NPC will only talk when it is clicked with the configurable talk-item. If close is true, it will only talk when a player comes near.

Note that players need the citizens.npc.talk permission to hear NPCs!

text

/npc text

Creates a text entry that says “hello player_name” and the player_name is the name of the player talking with the NPC and the color of the player_name is cyan. Adds second talk message “Hi there”. The NPC is set to a close talker and random talker. So when a player approaches within 5 blocks the NPC will make a random selection of messages:

/npc select fasttalker1
Type T to enter chat mode
/npc text
Type T to enter chat mode
add
Type T to enter chat mode 
hello <3> <player>
Type T to enter chat mode
add
Type T to enter chat mode 
Hi there
Type T to enter chat mode 
close
Type T to enter chat mode 
random
Type T to enter chat mode 
exit

variables <>

Parameter Description
npc NPC’s name.
owner NPC’s owner.
player Player’s name.
world Player’s world.
# Set the text color.

color codes

Number# Description
0 BLACK
1 DARK BLUE
2 DARK GREEN
3 CYAN
4 DARK RED
5 PURPLE
6 GOLD
7 LIGHT GRAY
8 GRAY
9 BLUE
a GREEN
b AQUA
c ROSE RED
d LIGHT PURPLE
e YELLOW
f WHITE

text editor commands

Command Description
add to add an entry
edit to edit entries
remove to remove entries
close to toggle the NPC as a close talker
item to set the item in hand pattern
range to toggle the talking range
delay to set the talking delay in ticks
random to toggle the NPC as a random talker
exit to clost the text editor

Equip them

Enable the equipment editor

Equip NPC guard1

/npc select guard1
/npc equip
Right-click the NPC with the item you want them to hold or wear
/npc equip to disable the editor

Enable the equipment editor.Toggle equipment editor. see Equipment Editor Used for player armor, player and endermen items, sheep color/sheared, and pig saddles. Equipment are things like armor, held-items, and other visible features on NPCs. Only some NPC types can have their equipment edited.

equip

/npc equip

Humans (regular NPCs)

Human NPCs can have their armor and held item modified. To give armor to a NPC, right-click one with armor in your hand. The armor is placed on the NPC’s body. Any item or armor that was previously on a NPC will be removed and dropped to the ground. To place armor in a NPC’s hand, crouch and right-click. To clear all items, right-click the NPC with no items in your hand.

To put an object in thier offhand, hold the object to give (such as a shield). Then go back to the chat screen and type “offhand”.

If you want to access their inventory you must first despawn the NPC and then use /npc inventory on them. Then, when the inventory is the way you want you can respawn the NPC with the command /npc spawn. When the NPC is already spawned you can only view their inventory but not add things to them.

Endermen

Enderman NPCs can have their carried material modified. The only valid materials that an enderman can hold are blocks - most items do not appear on the client. Note that certain “utility” blocks such as sign posts, silverfish blocks, etc. do not appear on the client either. Click with no items in your hand to remove blocks from the enderman NPC.

Sheep

Sheep NPCs can have their wool color and sheared status modified. To shear, right-click with shears like your normally would. To un-shear a sheep NPC, click it with the shears again. To change the wool color, click the sheep NPC with dye. Clicking with anything but dye in your hand will turn the sheep NPC white and drop the dye on the ground.

Pigs

Pig NPCs can have saddles added and removed from them. Simply right-click the pig NPC with a saddle in hand. Clicking with any other item in your hand will remove the saddle from the pig NPC.

Set movement options

The waypoint provider manages movement between waypoints (destinations). You use the path editor to set the destinations for the NPC to move towards (how the NPC gets to the destination is decided by the waypoint provider).

The default waypoint provider is set to Linear, going from one diestination to the next, always in the same order.If you are okay with that method of moving you can go right to /npc path to start editing a Linear set of destinations for your NPC.

If you want to use a different method to move you must select a different waypoint provider first, such as wander or guided. Then you can use /npc path to set the destination points.

Select a waypoint provider

Display available waypoint providers:

/npc select whitewalker
/waypoint provider -d

Set the waypoint provider to wander anywhere:

/npc select whitewalker
/waypoint provider wander

Disable waypoint teleporting when the NPC cannot get a path to the next waypoint:

/npc select whitewalker
/waypoint disableteleport

waypoint

/waypoint (disableteleport) | (provider [provider_name])

/waypoint provider -d)

The following waypoint providers are included with the NPCs:

Trait based waypoint providers are available with some traits, such as NPC Destinations. NPC Destinations does not use the /npc path editor to set waypoints. Use the /npcdest commands to set waypoints when using this trait.

For the linear waypoint provider, triggers can be added to pause the NPC at certain waypoints, change their speed or say something at a waypoint. More information can be found by typing ‘triggers’ in the waypoint editor.

Parameters

Parameter Description
disableteleport Stops NPCs from automatically teleporting the end of their path if they get stuck.
provider Name of current waypoint provider.
provider_name Name of waypoint provider. Default [linear
d Name of available providers.

Use the path editor

Left click to add a waypoint, right-click to remove, mousewheel or number keys to select individual waypoints. NPC movement to a waypoint is managed by a waypoint provider. If you have problems getting paths to go the way you want, you can set the Citizens plugin debug-pathfinding: true. This is set in the config.yml for Citizens. When this is enabled you can see the paths that an NPC has decided to follow.

Open the path editor for MrHeavyFoot, using the default waypoint provider

/npc create MrHeavyFoot
/npc select MrHeavyFoot
/npc path

path

/npc path

Toggle path editor. Options change depending on the selected waypoint provider.

Wander waypoint provider

Set the NPC to wander in a region:

/npc select friend1
/waypoints provider wander
/npc path

Type T to enter chat mode
xrange 10

Type T to enter chat mode
regions

Left-click somewhere to be the center of the region

Type T to enter chat mode
regions

/npc path

Use wander waypoint provider to define a space where the NPC can wander randomly. After setting the waypoint provider to ‘wander’ use the /npc path command to open the editor.

Path commands for wander waypoint provider

Command Description
xrange (number) modify the x random wander range
yrange (number) modify the y random wander range
regions enter the region editor

Wander regions editor

Left-click to add a new wanderable region using the xrange / yrange box centered at that block. Right-click an existing marker to remove that region. Type ‘regions’ to stop or simply exit the editor. Regions should be overlapping with each other.

Linear waypoint provider

Use linear waypoint provider to just go around adding waypoints. The NPC will go to each one, one after the other. After setting the waypoint provider to ‘linear’ use the /npc path command to open the editor.

After adding a waypoint you can optionally add triggers for the waypoint. For example, you can add a delay at the last waypoint to make the NPC halt for a few seconds before continuing on their way.

Add multiple linear waypoints:

/npc select friend1
/waypoints provider linear
/npc path
Left-click to add a waypoint in the ground
Walk a ways away
Left-click to add a waypoint in the ground
/npc path

NPC will walk back and forth between the points. If you add a small wall they will walk around it.

Add a waypoint with trigger to delay for 2 seconds:

/npc select friend1
/waypoints provider linear
/npc path
Left-click to add a waypoint in the ground


Walk a ways away
Left-click to add a waypoint in the ground
Type T to enter chat mode
triggers
Type T to enter chat mode
add
Type T to enter chat mode
delay
Type T to enter chat mode
40

Type T to enter chat mode
back

/npc path

Path commands for linear waypoint provider

Command Description
left-click add a waypoint
right-click remove a waypoint
toggle path toggle showing entities at waypoints
triggers enter trigger editor and display current triggers
clear clear all waypoints

Linear trigger editor

Triggers can be added to pause the NPC at certain waypoints, change their speed or say something at a waypoint.

Type ‘add’ to begin adding triggers and ‘remove’ to remove triggers. Type triggers to exit the waypoint editor. Valid trigger names are:

Command Description
delay Add a delay trigger. Then type in the server ticks to use (20 ticks = 1 sec).
chat Add a chat trigger. Then type radius to set the block radius to broadcast the messages. Then type the chat lines to say. Then type ‘finish’ to finish chat trigger.
teleport Add a teleport trigger. Then enter the destination in the format world:x:y:z. Type ‘here’ to use your current location.
speed Add a speed trigger. Then type the speed modifier as a percentage of its base speed.
animation Add an animation trigger. Then type in the animation to perform. Valid animations are ARM_SWING, ARM_SWING_OFFHAND, CRIT, EAT_FOOD, HURT, MAGIC_CRIT, SIT, SLEEP, SNEAK, START_ELYTRA, START USE_MAINHAND_ITEM, START_USE_OFFHAND_ITEM, STOP_SITTING, STOP_SLEEPING, STOP_SNEAKING, STOP_USE_ITEM. Then type ‘finish’ to finish animation trigger.
back Return to the edit prompt

Guided waypoint provider

Add random destinations with guided waypoints:

/npc select friend1
/waypoints provider guided
/npc path
Sneak and left-click to add a waypoint in the ground

Walk a ways away
Sneak and left-click to add a waypoint in the ground

Walk a ways away
Sneak and left-click to add a waypoint in the ground

Walk a ways away
Sneak and left-click to add a waypoint in the ground

/npc path

NPC will randomly choose from these destinations and walk to it.

Use guided waypoint provider to define multiple destinations that an NPC will randomly choose from. After setting the waypoint provider to ‘guided’ use the /npc path command to open the editor. Guided waypoints are specifically when you want a generalised path to stick to but do not want the NPC to follow a set order. They also use the new pathfinder so can be more glitchy - there’s a debugging setting if you really want to set this up.

We do not know what the “guided” waypoints do (the NPC never goes to them), but if you set the destination waypoints (left-click while sneaking) your NPC will move randomly among those points. This is different than the linear waypoint provider where your NPC vists one destination after the other. Also, the linear waypoints supported triggers for actions when arriving at a destination.

Path commands for guided waypoint provider

Command Description
left-click add a guide waypoint
right-click remove an existing guide waypoint
sneak + left-click add a destination waypoint
sneak + right-click remove an existing destination waypoint
toggle path toggle showing entities at waypoints

Other movement commands

Add mob dependent options

General commands

Mount a rider on a horse

/npc create horsey
/npc type horse
/npc controllable
/npc horse --color brown
/npc

Take the horsey id number and use below

/npc create rider
/npc select rider
/npc lookclose
/npc mount --onnpc <id>
/waypoint provider wander

Putting wander on the horse seems to make it spin around...
 more than putting wander on the rider.

To stop the wandering just set the waypoint provider to none.

/waypoint provider none

Some common commands are:

Mob specific

Change the horse color

/npc create horsey
/npc type horse
/npc controllable
/npc horse --color brown --style white_dots

Change the parrot color

/npc create birdy
/npc type parrot
/npc parrot --variant green

Change the fish color

/npc create fishy
/npc type tropicalfish
/npc tfish --color black --patterncolor white

Create a red sitting cat

/npc create kitty
/npc type ocelot
/npc ocelot -–type red_cat -s

Manage your NPCs

Teleport to an NPC

/npc select lostnpc1
/npc tp

Change the head pose

/npc create looker1
/npc select looker1

Look in some direction
/npc pose --name lookthisway1 -a

Look at the NPC and they should now be looking...
  in the direction you were

When you despawn an NPC they are kept in the memory but removed from the map. You can bring them back with the /npc spawn command. When you remove an NPC it is permanently removed from the map.

Some common commands are:

Go crazy

Make a ridable turtle

/npc create bigshell --type turtle
/npc controllable

Then right click on it to ride it in the ocean. 
If it dives too deep you will slide off though.

Make a guardian chicken

/npc create hero --type chicken
/npc select hero
/trait sentinel
/sentinel guard <your name>

Control a giant

/npc create bigboy --type giant
/npc select bigboy
/npc controllable

Then right click on it and walk the big guy around.

Give a llama a nice blanket. Riding the llama though will remove the blanket.

/npc create llama1 --type llama
/npc select llama1
/npc equip

Then right click on it while holding a carpet.

/npc equip

Ride a polar bear

/npc create bearbear
/npc select bearbear
/npc type polar_bear
/npc controllable

Then right click on it and guide it around.

Make a trader on a boat (uhm, work in progress, it does not work yet… better to ride a turtle)

/npc create boat
/npc select boat
/npc type boat
/npc controllable
/npc pathopt --avoid water false

Use /npc list to find the id number of the boat.

/npc create trader
/npc select trader
/npc pathopt --avoid water false
/npc lookclose
/npc mount --onnpc <id>

Here are some ideas of what you can do with NPCs.

Sample script for NPC dialog here: https://interpixel.dyndns.org/docs/npc_chat_script_simple.txt

All Commands

Example