Creating Your First Script

This guide will assist you through the necessary steps in creating your first DreamBot script. You will begin by installing the required tools and by setting up your development environment. After that you will use these tools to build a minimal script that you can run in the DreamBot client.

Install the Java Development Kit

The very first step you need to take is to install the appropriate Java Development Kit (JDK) that will be used in building your scripts. We recommend releases from Eclipse Temurin.

Warning

Make sure to install the JDK variant and not the JRE (Java Runtime Environment).

WindowsMacOSLinux

Open the JDK download page and click the download button for Windows (.msi file) to start downloading the installer. Once completed, run the installer and follow its instructions.

Open the JDK download page and click the download button for MacOS (.pkg file) to start downloading the installer. Once completed, run the installer and follow its instructions.

Linux users are recommended to follow the official Eclipse Temurin instructions to add the repository to the package manager and install everything within the terminal. This way will allow you to easily get frequent updates.

Set Up the Development Environment

Next you will install and set up an integrated development environment (IDE) which you will use to write and build the script on. There are multiple free Java IDEs you can choose from but this guide recommends and uses JetBrains IntelliJ IDEA (Community Edition). Go ahead and install the community version on your computer.

In IntelliJ IDEA's terms, you will need a project to store the source code for your scripts. Generally, each script will be developed as an individual module within the project. On your computer's file system the files will be structured as follows:

my-scripts/         (project)
├─ first-script/    (module)
│  └─ src/
│     └─ ...        (source code)
└─ second-script/   (module)
   └─ src/
      └─ ...        (source code)

The next steps will guide you through making the project, creating a module for your first script and setting up the project so that you can later focus solely on developing the script.

Create a New Project

To begin creating a new project, open up IntelliJ IDEA and you will be presented with a window similar to the following:

Click on New Project to open a window to create the project. In this window you are going to set up the project and a module for your first script in one go. Pay attention to the following options:

1. Select Java as the project type on the left.
2. Give the project a name, such as my-scripts.
3. Choose the location where you want the project directory to be created.
4. Select IntelliJ as the build system.
5. Choose the JDK you installed earlier.
6. Uncheck Add sample code.
7. Expand the Advanced Settings to change the default module settings.
8. Change the Module name to one that describes your first script, such as first-script.
9. Append the module name to the Content root path, so that you end up creating an additional folder for the module in the project's directory. The Module file location should automatically adjust to Content root but ensure they are the same.

Tip

Advanced users can use Maven as the build system. See the How to Use Maven With DreamBot tutorial for instructions on how to get started.

Click Create and confirm the action, and an empty project will be created and opened for you.

Configure the Project

Before you start writing any code, you need to configure the project. Start off by adding the necessary dependencies in the project and then proceed to setting up an artifact for your script's module.

Set the Project Language Level

The DreamBot client runs on Java 11. In order to avoid Java version mismatch errors you need to limit the project's available Java API to that from version 11 and before:

1. Click on File up on the IDE's toolbar.
2. Select the Project Structure... option.
3. On the Project Structure window, open the Project tab on the left.
4. Select 11 - Local variable syntax for lambda parameters as the project Language level.
5. Click on Apply to save the changes to your project settings.

Add Client Libraries as Dependencies

Scripts control the client via the DreamBot API. In order to have the IDE understand and suggest various methods exposed by the API, you need to add the client libraries as dependencies in your project:

1. On the Project Structure window, open the Libraries tab on the left.
2. At the top of the tab, click on the + symbol to add a new library.
3. Select Java as the library type. The IDE will prompt you to select the library files from your computer.
4. Navigate inside DreamBot's BotData directory and select the repository2 folder. The path to the folder is:
   • Windows: C:\Users\YOUR_USER\DreamBot\BotData\repository2\
   • Linux / MacOS: /home/YOUR_USER/DreamBot/BotData/repository2/
5. Press Ok to add the library in your project.
6. The IDE will prompt you to choose which modules to add the library to. Select your script's module and press Ok.
7. Apply the changes to your project settings.

Now you've successfully added the DreamBot libraries to your project and the IDE is able to assist you in using the DreamBot API by making suggestions as you write your script's code.

Set Up an Artifact for Your Module

In order to have your script appear on the DreamBot client's script manager, you will need to provide it with a Java Archive (JAR) containing your script's compiled source code. In IntelliJ IDEA, you can compile and export your project as a JAR file by building an artifact. To do that, you need to set up one first:

1. Still on the Project Structure window, open the Artifacts tab on the left.
2. At the top of the tab, click on the + symbol to add a new artifact.
3. Select JAR > Empty as the artifact type.
4. Give the artifact a name, such as first-script.
5. Change the Output directory to the DreamBot's Scripts directory. The path to the directory is:
   • Windows: C:\Users\YOUR_USER\DreamBot\Scripts\
   • Linux / MacOS: /home/YOUR_USER/DreamBot/Scripts/
6. Under the Available Elements find your module's compile output and double click it to put it into the output root.
7. Finally, click on Ok the save the changes and to close the window.

You've successfully added an artifact you can use to build your script and export it directly in the client. Your project is now ready to be used in developing your first script.

Create a Simple Script

In this section you will write a simple script, export it from the IDE into your client where you will be able to run it.

Write the Script

Start off by creating a new Java class file to act as the main entry point for the script. Right click on the src folder on the left, select New > Java Class and give it an appropriate name, such as Main.

The IDE will create a new Main.java file for you with the class declaration:

public class Main {
}

Derive From AbstractScript

The client expects the main entry point to the script to be an instance of AbstractScript. By extending from this class you will be able to override its methods and have the client run code you've written in the method implementations.

The onLoop is the only method you are required to implement in your script. This method is repeatedly called by the client until the script is stopped. The return value indicates how long the client should wait in milliseconds before it calls the method again. In this case a return value of 1,000 milliseconds is used which equals one second.

import org.dreambot.api.script.AbstractScript;

public class Main extends AbstractScript {

    @Override
    public int onLoop() {
        return 1000;
    }

}

The AbstractScript has several other important methods you normally would implement in your script, but for the sake of simplicity you may ignore them for now.

Add the ScriptManifest

Making the main class of your script an instance of AbstractScript won't alone suffice to make the script appear in the client's script manager. You also need to provide the client with some metadata of your script. You do this by annotating your main class with the ScriptManifest annotation.

import org.dreambot.api.script.AbstractScript;
import org.dreambot.api.script.Category;
import org.dreambot.api.script.ScriptManifest;

@ScriptManifest(name = "Script Name", author = "Developer Name",
                description = "This is the script description.",
                category = Category.WOODCUTTING, version = 1.0)
public class Main extends AbstractScript {

    @Override
    public int onLoop() {
        return 1000;
    }

}

The values you input in the ScriptManifest specify how the script appears in the client. In the table below you can find more information about the elements used in the manifest.

Element	Type	Description	Optional
name	String	The script name shown in the script manager.	No
author	String	The author name shown in the script manager.	No
category	Category	The category related to the type of work the script will do.	No
version	double	The script version shown in the script manager.	No
description	String	The script description shown in the script manager.	Yes
image	String	The URL of the image shown in the script manager.	Yes

Write a Message in Console

To be able to verify the code you write in the onLoop is in fact executed by the client when the script is running, you can make the client print text in the console each time the onLoop method is called. The Logger.log(Object) method can be used to print information in the client's console.

import org.dreambot.api.script.AbstractScript;
import org.dreambot.api.script.Category;
import org.dreambot.api.script.ScriptManifest;
import org.dreambot.api.utilities.Logger;

@ScriptManifest(name = "Script Name", author = "Developer Name",
        description = "This is the script description.",
        category = Category.WOODCUTTING, version = 1.0)
public class Main extends AbstractScript {

    @Override
    public int onLoop() {
        Logger.log("My first script!");
        return 1000;
    }

}

This is the most minimal script one could write. When this script is started, the client will keep printing the "My first script!" message in the console every second until the script is stopped.

Export the Script

As mentioned earlier, in order to have the script appear in the client it needs to be compiled into a JAR file which is then exported into the client. Because you have already set up an artifact in an earlier step, this process is simple. From the IDE's toolbar select the Build > Build Artifacts... option, choose your script's artifact and click on Build.

Once the build is completed, and if the artifact was set up correctly, the script has now been exported as a JAR file in the directory where the DreamBot client searches for local scripts to load in the script manager.

Run the Script

Open up your DreamBot client's script manager where you should find your script. If you have a lot of scripts loaded you can check only the Local box to filter the list and have an easier time finding it.

Press the button to start the script and open up the console to find that the script is printing the message you specified in onLoop every second.

Next Steps

If you've made it this far, great job! As your next steps you're recommended to practice using the API with the help of our tutorials. You can find them on the navigation panel under Scripting Guides.

When you're ready to start developing your second script, all you need to do is create a new module in your existing project. You can do that in the project settings where you will also be able to make the module use the same dependencies and set up a separate artifact for the new script.

Should you want to read some reference material, browsing our Javadocs will give you an idea what the DreamBot API has to offer.

As a beginner scripter you are likely to encounter some trouble along your scripting journey. Whenever you feel like asking for help, don't hesitate to make use of the Scripting Support section on our forums. The community is always ready to help!