Creating New Commands

The process for creating new commands is very simple, they are simply an annotated Java class.

Writing the plugin

Create the class

Firstly, you need to create your new Java class. This can be in any package but for consistency they are being stored in the package uk.co.unitycoders.pircbotx.commands. This class should extend uk.co.unitycoders.pircbotx.modules.AnnotationModule in order to use the annotation system. You should pass the name of your command as an argument to AnnotationModule's constructor (see below).

package uk.co.unitycoders.pircbotx.commands;

import uk.co.unitycoders.pircbotx.modules.AnnotationModule;

public class HelloCommand extends AnnotationModule {

    public HelloCommand() {
        super("hello");
    }

}

Write your method signatures

Next you need to create some methods for the bot. The method signature for command actions is as follows: public void onInfo(Message message) where Info is the name of the action you want to implement. It's actually not important what the method is named, but naming it in this fashion will help you find it again if you need to later.

package uk.co.unitycoders.pircbotx.commands;

import uk.co.unitycoders.pircbotx.modules.AnnotationModule;
import uk.co.unitycoders.pircbotx.commandprocessor.Command;
import uk.co.unitycoders.pircbotx.commandprocessor.Message;

public class HelloCommand extends AnnotationModule {

    public HelloCommand() {
        super("hello");
    }

    public void onHello(Message message) {
    }

}

Write your methods

Next write your action logic in the method. If you want to know what methods are available to you as part of the event, see the PircBotX documentation

package uk.co.unitycoders.pircbotx.commands;

import uk.co.unitycoders.pircbotx.modules.AnnotationModule;
import uk.co.unitycoders.pircbotx.commandprocessor.Message;

public class HelloCommand extends AnnotationModule {

    public HelloCommand() {
        super("hello");
    }

    public void onHello(Messages message) {
        message.respond("Hello, World!");
    }

}

Tell the bot about it

Annotate your actions

Now we have a plugin, but we have to tell the bot about the plugin. Registering the plugin with the bot is a two step process, firstly you must tell the bot about the actions in your command. Then you must register the command with the bot so it looks for the actions.

Informing the bot about the actions is done with annotations. These take an optional argument which will be the name of the bot responds to. This defaults to "default" when no argument is supplied. I will demonstrate both uses.

package uk.co.unitycoders.pircbotx.commands;

import org.pircbotx.PircBotX;
import org.pircbotx.hooks.events.MessageEvent;

import uk.co.unitycoders.pircbotx.modules.AnnotationModule;
import uk.co.unitycoders.pircbotx.commandprocessor.Command;
import uk.co.unitycoders.pircbotx.commandprocessor.Message;

public class HelloCommand extends AnnotationModule {

    public HelloCommand() {
        super("hello");
    }

    @Command
    public void onHello(Message message) {
        message.respond("Hello, World!");
    }

    @Command("goodbye")
    public void onGoodbye(Message message) {
        message.respond("Goodbye, World!");
    }

}

Inform the bot the plugin exists

The next step is when we tell the bot the plugin exists. The bot's plugin list is determined from a file in META-INF. To add your plugin to the bot you simply need to add your command as a new line in src/main/resources/META-INF/services/uk.co.unitycoders.pircbotx.modules.Module. If you need to pass arguments to your plugin you will need to add it to legacyModules in BotRunnable.java instead.

Add it to the end of the list in src/main/resources/META-INF/services/uk.co.unitycoders.pircbotx.modules.Module:

uk.co.unitycoders.pircbotx.commands.CalcCommand
uk.co.unitycoders.pircbotx.commands.RandCommand
uk.co.unitycoders.pircbotx.commands.DateTimeCommand
uk.co.unitycoders.pircbotx.commands.HelloCommand

Or you can do this in Java (uk.co.unitycoders.pircbotx.BotRunnable):

Module[] legacyModules = new Module[] {
    ModuleUtils.wrap("factoid", new FactoidCommand(DBConnection.getFactoidModel()) ),
    ModuleUtils.wrap("help", new HelpCommand(processor)),
    ModuleUtils.wrap("plugins", new PluginCommand(processor)),
    ModuleUtils.wrap("sesssion", new SessionCommand(security)),
    new HelloCommand()
};

Running the bot

Now recompile and run your bot.

mvn package
java -jar java -jar target/uc_pircbotx-0.2-SNAPSHOT-jar-with-dependencies.jar

You should now be able to use the command you wrote on irc.

<webpigeon> &hello
<bot> Hello, world!
<webpigeon> &hello goodbye
<bot> Goodbye, world!