API module
Other plugins can read and control NPCs through a small API module, without depending on this plugin's internals (and without needing ProtocolLib themselves).
Adding the dependency
Depend on the api module's output, not the main plugin jar. Add this plugin as a softdepend or depend in your own plugin.yml so it loads first.
Getting the API
NpcsService npcs = NpcsApi.get();
This throws if the npcs plugin hasn't registered its service yet — normally because it isn't installed, isn't enabled, or hasn't finished starting. Check first if you're not sure:
if (NpcsApi.isAvailable()) {
NpcsService npcs = NpcsApi.get();
}
Looking up NPCs
Optional<ApiNpc> bob = npcs.getNpc("Bob");
Collection<ApiNpc> all = npcs.getAllNpcs();
boolean exists = npcs.exists("Bob");
Creating and removing
ApiNpc npc = npcs.createNpc("Guard", EntityType.PLAYER, location, playerUuid);
npcs.removeNpc("Guard");
Reading and changing an NPC
ApiNpc covers the same ground as the in-game commands: display name, type, location, skin, glowing, gravity, collision, scale, custom attributes, and click actions.
npc.setDisplayName("<gold>The Guard");
npc.setSkin("Notch", textureValue, textureSignature);
npc.setGlowing(true, "RED");
npc.addAction("interact", "message", "Halt!");
npc.save();
npc.respawnForViewers();
Changes don't take effect for players already seeing the NPC until you call save() and respawnForViewers().
Working with selection
Optional<ApiNpc> selected = npcs.getSelectedNpc(player);
npcs.selectNpc(player, npc);
npcs.deselectNpc(player);
Listening for clicks
npcs.registerInteractListener((player, npc, type) -> {
if (type == NpcInteractListener.InteractType.RIGHT_CLICK) {
player.sendMessage("You right-clicked " + npc.getName());
}
});
This fires for every click on every NPC, regardless of whether that NPC has any built-in actions configured — it runs alongside this plugin's own action system, not instead of it.
Location, EntityType, Player) and the plugin's own interfaces, so depending on it doesn't pull ProtocolLib into your own plugin.