Developers / API module

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.

What the API does not expose
Packet construction, ProtocolLib types, and other implementation details stay internal to the plugin. The API only exposes plain Bukkit types (Location, EntityType, Player) and the plugin's own interfaces, so depending on it doesn't pull ProtocolLib into your own plugin.