Creating an NPC with the API

Creating the NPC object

To start, you need an NPC object. You can create one by calling NPC::new (The constructor) Here is an example:

World world = Bukkit.getWorld("world"); // the default world name
// But you should do a null check, as 
// an error will be thrown if the world is null 
NPC npc = new NPC(world);

General Customization

Position

From there, you have to do a few things in order for the NPC to be useful. For starters, you should set the spawn location. If you don't the NPC will spawn at (0, 0, 0).

// arbitrary numbers for the sake of example
npc.setPosition(new Location(world, 100, 100, 100));

Rotation

If you want to customize the yaw and pitch of the NPC's head, you should do so using the Location object.

// arbitrary numbers for the sake of example
Location loc = new Location(world, 100, 100, 100, 45, 0);
npc.setPosition(loc);

Skin Data

If you want to specify a skin for the NPC, you should do so using the setSkinData method. To get the signature and value, you can use InventiveTalent's Mineskin.

String value = ...; // assume an actual value
String signature = ...; // assume an actual signature
String skinName = ...; // shown when a user tries to edit the NPC
npc.setSkinData(skinName, signature, value)

The Settings Object

Interactability

Interactability defines if the NPC will have the clickable hologram. (More info Later) If this is set to false, even if you give the NPC actions, they will be ignored. (Defaults to false) To change it, simply call

npc.getSettings().setInteractable(true);

Tunnel Vision

Tunnel vision defines if the NPC will look at nearby players. (Defaults to false) To change it, simply call

npc.getSettings().setTunnelVision(true);

Resilient

Resiliency, or being resilient, defines if the NPC should persist on server restarts or running /npc reload. This defaults to false, unlike creating NPCs using the plugin's UI. Setting this to true may fill up your npcs.yml file if you are not careful. To change it, simply call

npc.getSettings.setResilient(true);

Direction (Deprecated -- To be removed in 1.8)

Lets you set the yaw of the NPC's head. Just set the Yaw in the NPC's location :)

Skin Data (But settings)

The method on the NPC is just a wrapper around the settings object, it is functionally the same. You can view the docs on it here.

Hide Clickable Hologram

This option hides the Clickable hologram, making the NPC appear as if I wasn't interactable, yet still being interactable. (Defaults to false) To change it, simply call

npc.getSettings().setHideClickableHologram(true);

Custom Interactable Hologram

This option allows you to override the global Clickable Hologram value. The string value can contain MiniMessage tags and PlaceholderAPI placeholders. To change it, simply call

npc.getSettings().setCustomInteractableHologram("<Your hologram>");

The Equipment Object

I am not going to go through every method, because their names are self-explanatory. The point is, you can set/get the itemstack object the NPC uses.

If you would like to import that equipment from a player, for example, you can use the importFromEntityEquipment() method.

Here is an example:

Player player = ...; // pretend its valid
npc.getEquipment().importFromEntityEquipment(player.getEquipment());

Using Actions

In 1.7, the Action system got a complete rewrite. This makes it way easier to use over its predecessors. Instead of using a string array and an enum, each action has its own class. If you want to add an action, you can just call NPC#addAction(Action). Here is a list of available actions. For example, sending a message:

npc.addAction(new SendMessage("Text Here", 0, ONE, List.of()));

All actions follow the same general constructor parameter layout:

First, are the action specific parameters, in our case, the message to send.

Then, there is an integer, specifying the number of ticks of delay to run the action after the initial interaction.

Then, there is a Condition.SelectionMode enum constant, signifying if one, or all of the following conditions must be met in order for the action to execute.

Finally, the list of conditions the player must fulfil for the Action to be executed.

If you would like to write your own actions, check out this page.

If you would like to create your own Conditions, check out the Roadmap, as that is a planned feature.

Moving the NPC

You can move the NPC by calling the moveTo(Location) method. Please note that it takes the pitch and yaw into account. The movements are only temporary, as reloading the npcs will put the NPC back to its spawn location.

Looking at things

You can make the NPC look at things in two ways. First, you can use the lookAt(Location) to look at the specified location.

npc.lookAt(new Location(world, 0, 0, 0);

Additionally, you can look at an entity instead.

npc.lookAt(entity, true);

The first argument is the entity to look at. It cannot be null.

The second argument is true of the npc should look at the entity's head, or false for their feet

Swinging the NPC's arm

You can swing the NPC's arm by calling npc.swingArm().

Manual Injection (Not recommended)

Even though the plugin handles injection, or making the NPCs actually appear, it is possible to handle it yourself. This could be useful, for example, if you are creating per-player NPCs. (But even then, there are better ways of doing it) In order to inject NPCs yourself, you can call

npc.injectPlayer(player);

Please note, if you want to do conditional injection, you should cancel the NpcInjectEvent instead :)

Last modified: 21 December 2024