Installing HalpBot

This beginners guide is created using IntelliJ. You can download the community version for free from here. If you're a student, you can get the ultimate version for free through an educational license.

Creating a Project in IntelliJ

The first step to creating a Java bot is to create the project which is where we will create all the code for our bot. After clicking on IntelliJ, you can create a new project by selecting the New Project button.

You'll then want to select a Gradle project (Gradle will be what we use to manage the dependencies our bot requires). You'll also want to make sure that the project SDK if 16+ and that the only additional libraries and frameworks selected is Java.

Is your project SDK not 16? Click on the dropdown and then Download JDK. You can then select version 16 from that the popup to download the appropriate JDK (Java Development Kit - Basically the version of java we're using).

After selecting Next, we then need to name our project and set the group id for our project. This is used to distinguish the files created by you from those created by any dependencies you might be using (This is particularly important in the event that there are two java files with the same name as this group id is the only way to distingish between them).

When your press Finish, IntelliJ will then automatically create our project with the basic filestructure needed. This may take a few minutes as if it has to download Gradle. Your project should look like this:

Adding HalpBot to Your Project

Currently Halpbot is not available on Maven, however, there is a built version you can download from here. To add this .jar file as a dependency within your project, you'll want to create a new folder called libs and place the downloaded .jar file inside like so:

To actually be able to use Halpbot though, you'll need to include this .jar file within your build.gradle file. This can be down by adding the following lines of code within the dependencies { ... } section of the file.

dependencies {
    // Load all .jar files from /libs
    implementation fileTree(dir: 'libs', include: '*.jar')

    // We're using logback to nicely log information to the console
    implementation 'ch.qos.logback:logback-classic:1.2.10'

    //... There should automatically be some junit test implementations too
}

NOTE: Halpbot is a JDA framework, however, you don't need to add this dependency yourself as it's built into Halpbot. Halpbot uses version 4.3.0_333 of JDA.

You'll then need to reload Gradle to automatically apply these changes. This can be down by selecting either the blue refresh arrows that automatically appears when you make changes to the build.gradle file or by going to the Gradle tab in the top right and selecting the refresh arrows. Both are underlined in the image below. This causes your project to automatically rebuild.

And just like that, you've added Halpbot to your project. Now you need to set it up so that you can begin creating actions!

Setting up Your Bot

To finish setting up your bot, we're going to need to things:

1. A bot-config.properties file which must be located within the resources folder.
2. A class that implementations the Bot interface which is used to initialise your bot.

Creating the bot-config.properties File

There are several different properties that can be set in this file as described here, however, for the purpose of this tutorial, we'll be using the default values and only setting the 2 required properties, ownerId and defaultPrefix. First though, we need to create our file by right clicking the resources folder (src/main/resources) > New > File and then creating bot-config.properties.

NOTE: The filename is case sensitive, so make sure the file is exactly bot-config.properties.

Within that folder, you'll then want to add the following properties and set the owner id to your discord id and the default command prefix to whatever you desire.

ownerId=260930648330469387
defaultPrefix=$

TIP: Not sure how to find your discord id? Refer to the tutorial here.

This should look like:

Creating the Bot Class

We now need to create our actual java bot class. In the src/main/java folder, you'll want to create your package by right clicking the java file and selecting New > Package and naming it what you specified the base package to be back when you created your project.

Within this newly created package, we can then create our bot class by right clicking the package we just created and then selecting New > Java Class. You can name this class whatever you want, but make sure that you've selected a class. Your file structure should now look like:

You'll then want to make your bot implement the Bot interface like below:

Show Imports

import nz.pumbas.halpbot.common.Bot;

public class ExampleBot implements Bot
{

}

This should cause your class to become underlined in red and if you hover over it, it'll ask you to implement the methods that the Bot interface requires. You can do this by selecting Implement methods > OK. By default, when you select implement methods, it will select all the required methods, which in this case is just initialise. Your bot class will now look like this:

Show Imports

import net.dv8tion.jda.api.JDABuilder;

import org.dockbox.hartshorn.core.exceptions.ApplicationException;

import nz.pumbas.halpbot.common.Bot;

public class ExampleBot implements Bot
{
    @Override
    public JDABuilder initialise(String[] args) throws ApplicationException {
        return null;
    }
}

This initialise method is where we'll setup our bot and specify our token. This can be done like so:

Show Imports

import net.dv8tion.jda.api.JDABuilder;
import net.dv8tion.jda.api.entities.Activity;

import org.dockbox.hartshorn.core.exceptions.ApplicationException;

@Override
public JDABuilder initialise(String[] args) throws ApplicationException {
    // We'll specify the first argument as our token when running the bot
    String token = args[0];

    return JDABuilder.createDefault(token)
            // Set our activity as 'Listening to how cool Halpbot is!'
            .setActivity(Activity.listening("how cool Halpbot is!"));
}

We'll also need a main method. This is where our bot is actually run from. Within it we'll call HalpbotBuilder.build with the class our bot is in and the args. This automatically registers any commands you might have (We'll get to that soon!) and then calls the initialise method.

Show Imports

import org.dockbox.hartshorn.core.exceptions.ApplicationException;

import nz.pumbas.halpbot.HalpbotBuilder;

public static void main(String[] args) throws ApplicationException {
    HalpbotBuilder.build(ExampleBot.class, args);
}

Finally, we'll need to annotate our class with several things to enable the various features Halpbot has to offer. You'll always need to annotate your bot with @Activator and @Service, howevever, depending on the actions you want to use, you'll also need to enable them. For this example, we'll be enabling commands and triggers using @UseCommands and @UseTriggers:

Show Imports

import org.dockbox.hartshorn.core.annotations.activate.Activator;
import org.dockbox.hartshorn.core.annotations.stereotype.Service;

import nz.pumbas.halpbot.commands.annotations.UseCommands;
import nz.pumbas.halpbot.common.Bot;
import nz.pumbas.halpbot.triggers.UseTriggers;

@Service
@Activator
@UseCommands
@UseTriggers
public class ExampleBot implements Bot
{
    //... The rest of your bot
}

Your completed Bot class should look like:

Show Imports

import net.dv8tion.jda.api.JDABuilder;
import net.dv8tion.jda.api.entities.Activity;

import org.dockbox.hartshorn.core.annotations.activate.Activator;
import org.dockbox.hartshorn.core.annotations.stereotype.Service;
import org.dockbox.hartshorn.core.exceptions.ApplicationException;

import nz.pumbas.halpbot.HalpbotBuilder;
import nz.pumbas.halpbot.commands.annotations.UseCommands;
import nz.pumbas.halpbot.common.Bot;
import nz.pumbas.halpbot.triggers.UseTriggers;

@Service
@Activator
@UseCommands
@UseTriggers
public class ExampleBot implements Bot
{
    public static void main(String[] args) throws ApplicationException {
        HalpbotBuilder.build(ExampleBot.class, args);
    }

    @Override
    public JDABuilder initialise(String[] args) throws ApplicationException {
        // We'll specify the first argument as our token when running the bot
        String token = args[0];

        return JDABuilder.createDefault(token)
                // Set our activity as 'Listening to how cool Halpbot is!'
                .setActivity(Activity.listening("how cool Halpbot is!"));
    }
}

Running Your Bot

To the left of your main method, you'll notice a small green arrow in the gutter which can be used to run your bot. If we try and run it currently, you'll get an index out of bounds error because of this line in the initialise method:

String token = args[0];

This is because we haven't actually specified any arguments to be passed when running our bot, so the length of the args array is 0 (As so there is no first element to access). We can specify the discord bot token by clicking the green arrow > Modify Run Configuration... and then specifing your discord token. Make sure to save your changes by selecting Apply or OK:

NOTE: Other arguments can be specified by separating them by spaces.

Now if we run the bot, itt should start up successfully!

Continue to: Creating Your First Actions