Creating Your First Actions

Setting up the HalpBot Command Adapter

Before you can create your first command, you need to create a CommandAdapter. The command adapter is responsible for managing all your commands and intercepting messages to check if they're calling one of your registered commands. When someone invokes your command, it will automatically parse the arguments and call the commands respective method.

As HalpBot has been built on top of the JDA framework, it's very simple to integrate the CommandAdapter into your bot.

public class Bot
{
    public Bot(String token) throws LoginException {
        JDABuilder jdaBuilder = JDABuilder.createDefault(token);
        String commandPrefix = "$";

        // Create a command adapter for the JDABuilder with the specified prefix.
        AbstractCommandAdapter commandAdapter = new TokenCommandAdapter(jdaBuilder, commandPrefix);

        // Pass an instance of the class with your commands in them to here.
        commandAdapter.registerCommands(new BotCommands());

        jdaBuilder.build();
    }
}

Let's break down what's happening here. Firstly, you're creating a TokenCommandAdapter and passing into it the JDABuilder with the prefix you want your commands to have. Next, we're registering the commands we've made to the command adapter by passing an instance of the class the command methods are contained within (We'll get to creating commands in a second). You can then build your JDA bot like normal.

Creating Commands With HalpBot

Commands can be created inside any class simply by annotating a method with @Command. When you register commands with the command adapter, it scans the objects you pass to it for methods with this annotation.

Let's start by creating a simple command called $ping which pings the person who calls it.

public class BotCommands
{
    @Command(alias = "ping", description = "Pings the person who calls this command")
    public String ping(MessageReceivedEvent event) {
        return "Haha... " + event.getAuthor().getAsMention();
    }
}

There are quite a few things going on here, so we'll cover each thing step by step. Inside the BotCommands class, we've created a method called ping with the @Command annotation. This tells us that this method is to be used as a command. Inside the @Command annotation, the parameter alias specifies what should be used to call this command.

NOTE: Command aliases are NOT case sensitive. Therefore this command could be called by any of the following: $ping, $Ping, $PiNg.

The description parameter describes what this method does and is used by the built-in halp command. More information on the built-in commands can be found here.

We then get to the method itself. In the parameters of the method, we can see MessageReceivedEvent event. This is the MessageReceivedEvent that was received by JDA when someone invoked the command. Finally, a String is returned by the command. The returned values of methods are automatically sent as messages to the channel where they were called by the command adapter. In this case, returning the String is the equivalent of doing:

String message = "Haha... " + event.getAuthor().getAsMention();
event.getChannel().sendMessage(message).queue();

You can also return MessageEmbeds and they will also be automatically sent as an embed. For custom objects, override the toString() method in the class to adjust what is automatically sent to the discord channel.

Okay, but what if you wanted to pass in some parameters to your command? Fortunately, HalpBot makes this extremely easy to do. Parameters in your method are automatically interpreted as parameters and parsed to the correct type. Now there are a few things to note: This doesn't apply to anything that extends GenericEvent (Like the MessageReceivedEvent from before). A more in-depth guide of command arguments can be found here.

For now, lets consider:

@Command(alias = "Add", description = "Adds the two specified numbers")
public double add(double num1, double num2) {
    return num1 + num2;
}

When you call the command $add, it will automatically try and parse the next two numbers as doubles and pass them to the method. If you don't specify two valid numbers, then a help message will automatically be sent in the channel used to call the command. If the two doubles were valid, then this method will automatically be invoked and the sum of those numbers returned.

Pretty neat right?