Developer API Guide

CraftIRC API

New in CraftIRC 2.x is an API for developers to integrate CraftIRC into their existing plugins, and create all-new CraftIRC plugins with ease.

Savvy? Jump straight into some example code: https://github.com/Animosity/CraftIRC/tree/master/com/ensifera/animosity/craftirc/example

Basic Concepts

Getting the CraftIRC instance:

You'll need to add CraftIRC as a buildtime dependency for your plugin, so add the newest CraftIRC 2.0+ jar file to your project. Then, add CraftIRC to your classes' namespace via import com.ensifera.animosity.craftirc.CraftIRC;. If you're feeling lazy, you can import all CraftIRC classes with import com.ensifera.animosity.craftirc.*;

In your plugin, you'll want to have a class member to store the handle to your user's instance of CraftIRC: protected CraftIRC craftircHandle. Feel free to use a more appropriate access level (private/public/protected) depending on your needs. You will use this handle to access the CraftIRC API methods.

In your plugin's onEnable() method, you should check to see if CraftIRC is even available on your user's server. One way of achieving this is:

public void onEnable() {
    log.info("Loading MyPlugin...");
    Plugin checkplugin = this.getServer().getPluginManager().getPlugin("CraftIRC");
    if (checkplugin == null) {
        log.severe("MyPlugin requires CraftIRC. Please install CraftIRC before using this plugin.");
        getServer().getPluginManager().disablePlugin(this);
    } else {
        try {
            // Get handle to CraftIRC, add and register your custom listener
            craftircHandle = (CraftIRC) checkplugin;
            MyCraftIRCListener ircListener = new MyCraftIRCListener(craftircHandle);
            this.getServer().getPluginManager()
                .registerEvent(Event.Type.CUSTOM_EVENT, ircListener, Priority.Normal, this);
        } catch (ClassCastException ex) {
            ex.printStackTrace();
            log.severe("MyPlugin cannot recognize this version of CraftIRC."
                       + " Make sure you are using a compatible version.");
            getServer().getPluginManager().disablePlugin(this);
        }
    }
}

The above example is for a plugin which is wholly-dependent upon CraftIRC (such as a plugin which adds custom IRC !commands). As such, the above code will only enable the custom plugin if CraftIRC is running on the server. Otherwise, the plugin will be disabled.

You should have noticed that in that code, a 'listener' is registered. What is the listener for? Well, CraftIRC needs a way to relay IRC events (such as chat, commands, emotes, kicks/bans/joins, etc) to any plugins which want to use them. So, those events are relayed in Bukkit as a CUSTOM_EVENT named "IRCEvent".

###Tags: Each server operator can configure CraftIRC to output to as many IRC servers and channels as they like. Addressing each individual channel has been abstracted into the concept of the 'Tag'. Server operators can define the tag of a server (which serves to allow messaging all channels that CraftIRC resides in, on that server), and also the Tag of a channel (which serves to target messages to that single channel). It is good practice to allow your plugin users to define which Tags (preferably channel tags) to associate with your plugin.

For example: if you are writing a chat plugin which supports multiple in-game chatrooms, you may want to add an IRC chatroom within your plugin to consolidate such conversations. Allow the server operator to designate which channel Tag/s to associate with that chatroom, so that you can route the output of that chat to appropriate Tags.

You can send a message to a Tag via craftircHandle.sendMsgToTag(String msg, String tag)

You can format messages sent with sendMsgToTag() by including some of CraftIRC's formatting options detailed in its config.yml. In particular, colors and bolding/underlining and any other codes you can use in the mIRC client

• IRC FORMATTING: %b% %u% %r% %o% %k% %kNUM% (NUM is 0 to 15); Do the same as CTRL+key in mIRC
• EASY COLORS: Use the names defined in the config.yml colormap: block, such as %blue% %foreground% %yellow% etc.