1.x/API

Not Supported!
This page is about Citizens 1.x, while the current version is Citizens 2.0.2. This page's content may be outdated, and shouldn't be trusted as being correct. See this page's talk page for more information. If you were looking for the 2.0.2 equivalent of this page, try API. If you feel this message was displayed in error, please contact an administrator.

JavaDocs

Our API documentation can be found here. For a basic guide on hooking into Citizens, see below.

Using the Citizens API

Hooking into Citizens is the same as hooking into any other Bukkit plugin like PermissionsBukkit or iConomy. Add the latest version of Citizens.jar to your build path. Then, add this code to your onEnable in the main class:

public void onEnable() {
    PluginManager pm = getServer().getPluginManager();
    Plugin test = pm.getPlugin("Citizens");
    if (test != null) {
        System.out.println("Successfully hooked into Citizens!");
    } else {
        System.out.println("Citizens isn't loaded.");
        // disable your plugin because Citizens was not loaded
        pm.disablePlugin(this);
    }
}

Now, to actually use the methods that Citizens has to offer, add the following import to your code:

import net.citizensnpcs.api.CitizensManager;

For specifics on the methods CitizensManager has, see our JavaDocs. For now, here is a basic example of how to use the class.

//checks if the passed Bukkit entity is an NPC
public void checkNPC(Entity entity) {
    if(CitizensManager.isNPC(entity)) {
        Bukkit.getServer().broadcastMessage(CitizensManager.get(entity).getStrippedName() + " is an NPC!");
    }
}

The last step is to make sure Citizens loads before your plugin. If it doesn't, your plugin will throw some nasty console errors. Add this line to your plugin.yml:

soft-depend: [Citizens]

Creating an NPC type

To create an NPC type, you need two things - a class extending CitizensNPCType, and a class extending CitizensNPC. You'll also need to create a file called 'type.info' (essentially like a plugin.yml), and place that in the root of your JAR. The type.info should contain a main: setting that points to the class extending CitizensNPCType.

Now, place your compiled JAR into the plugins/Citizens/types folder - and you're done! Caveats: due to Bukkit restrictions, Citizens cannot register new commands for you.