Scripting Tutorial [In-Depth] [No prior knowledge needed] WHERE TO GET STARTED! By Apaec

[Apaec 78]

Hi there future scripters! This tutorial I am writing for you all now will go in-depth with everything you need in order to get started writing your very own scripts. After reading through this tutorial you will be capable of writing, compiling and running simple scripts such as a tea thiever, chicken killer and so on. If you are really keen to get started scripting I recommend reading the whole guide through and going back through the parts you did not fully understand.

 

Previous required knowledge:

• None
• Knowledge of basic java helps but is not required!

 

What the guide will teach you:

 

• Downloading your code editor (IDE)
• Simple code and Basic DreamBot API
• Writing a script (with tester snippets to get you started!)
• Exporting a script into DreamBot
• Running your script

Please note:

• Script will not be complex. I will be writing a simple tea thiever.
• Script will have no paint nor GUI, I'll be writing a follow on guide on implementing these later.

So, let's get started!

 

FIRSTLY, DO NOT BE AFRAID OF THESE { OR THESE () OR THESE } OR ANY OF THOSE! They are simple yet look complicated. All { means is defining the start of a block. } defines the end of it. Simple! 

 

Firstly, you're going to want to download an IDE (a program in which you write and compile code). In this tutorial I'll be using Eclipse, a piece of free software which is perfect for scripting for DreamBot. Simply put, Eclipse is like a word document in which you write your code and then save the code as a .Jar file, which is interpreted and run by the DreamBot client.

 

PART 1 - DOWNLOADING ECLIPSE

 

https://www.eclipse.org/downloads/packages/eclipse-standard-432/keplersr2

 

Head to the above site:

 

 

Select the correct download button depending on whether your computer is 32/64.

 

Not sure?

Click here: http://windows.microsoft.com/en-us/windows/32-bit-and-64-bit-windows#1TC=windows-vista to check this information

 

Once the download has completed and you have the ZIP file, run it.

 

 

Open it in WinRar or 7Zip or whichever other programs you will use, and extract it directly to your C root.

 

 

 

And that will extract eclipse to your c:\ directory.

 

 

Open eclipse.exe

 

Once you have your IDE in place you should have Eclipse open and this screen should be visible:

 

 

Then open your workbench:

 

 

Success! You have successfully installed your script developing IDE.

 

 

Let's move swiftly on to part 2 and start coding!

 

 

PART 2 - SETTING UP YOUR JAVA PROJECT

 

Create a new java project going by the name of your desired script like so:

 

 

Give the project the name. 

 

 

Click finish and you've successfully created your workspace project!

 

Now you need to create a new class in which to write your code.

 

 

Give the class a name (I suggest 'Main' for the tutorial, but you could call it 'Cabbages' if you wanted, it doesn't matter!) - Capitalised first letter is the convention (cheers :/) but it really doesn't matter lol

 

 

Now all we need is to "attach" dreambot to this directory, so we can utilise the API:

 

 

Then simply navigate to your client.jar and select it.

 

 

Your eclipse should then look like this:

 

 

Now let's start writing the script!

 

 

PART 3 - WRITING YOUR SCRIPT

 

To start you will need to paste the following framework from which we will start writing the code (You do not need to be able to write this from memory, don't worry! This is where all scripts start off - not from a blank page!):

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

@ScriptManifest(author = "You", name = "My First Script", version = 1.0, description = "Simple Tea Thiever", category = Category.THIEVING)
public class main extends AbstractScript {

public void onStart() {

}

public void onExit() {

}

@Override
public int onLoop() {

return Calculations.random(500, 600);
}
}

 

Go ahead and paste that in, and your eclipse should look like so:

 

 

 

Press Ctrl+Shift+F to format the code. Do this often - it helps!

 

 

This is the basic starting point from which all scripts are made (the 'backbone' of the script). 

 

I will break down each part of this backbone to give you an understanding of what they do and how you use them.

 

 

ONSTART:

 

This look is activated ONLY ONCE when you press the start button on the script while running the client.

You can use this loop for logging things in the console below the screen, initialising timers and variables and much more. Remember this code is always run once and only once when you start the script!

 

Here's an example of me using the onStart to log some information for the user to read:

 

 

Next:

 

 

ONLOOP

 

This is the heart of the script. This loop repeats itself as the main part of the script. this is where the code and core logic of your script is held. There is a return value on the onLoop which defines the delay between loops. At the moment, the return value is:

return Calculations.random(200,300);

This means the delay between every loop is a random number of milliseconds between 200 and 300.

To generate a random number, you use the code: Calculations.random(lower value, higher value). You can use this anywhere in the script to generate random numbers. This is one to remember - it's really useful!

 

Next:

 

 

ONEXIT

 

Similar to onStart, this loop runs only once when you press the red stop button at the top of the bot. You can use this block to log details of the script for example how many teas you thieved, or how long you ran the script for. It often does not serve a hugely useful purpose in the logic of a script, but is handy none the less.

 

 

================================================================================================

 

That's the backbone of the script explained, and I'll now get into the coding.

 

To start with, this script is going to be written using what's called a 'State Machine'. Now you may or may not know what this is, but simply put it means the script will do different things (run different blocks of code) depending on whether a question (which you ask) is answered as true or not.

 

For example, in our tea thiever we want the script to steal tea while the tea stall is available, and drop tea if you have it in your inventory, and if the stall isn't available the script will wait until it is.

 

So that means we want to define three different states: Drop, Steal and Wait.

 

States are held in an Enum (Enumerated Type) and by Java Convention all subjects within an Enum are CAPITALISED_AND_UNDERSCORED_IF_REQUIRED. You do not need to keep to java conventions, but if you do you're a better coder!

 

PLEASE NOTE:

You do not need to understand the following code, as it is universal to every script you will write in the future. You just need to understand how to use it which trust me is simple enough. Once you get more experienced you can start to read it through and decode what it's doing. If you can already then great! you should find this all very easy!

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

@ScriptManifest(author = "You", name = "My First Script", version = 1.0, description = "Simple Tea Thiever", category = Category.THIEVING)
public class main extends AbstractScript {

	public void onStart() {
		log("Welcome to Simple Tea Thiever by Apaec.");
		log("If you experience any issues while running this script please report them to me on the forums.");
		log("Enjoy the script, gain some thieving levels!.");
	}

	private enum State {
		STEAL, DROP, WAIT
	};

	private State getState() {
	        if (condition 1 is true)
	            return State.DROP;
	        if (condition 2 is true)
	            return State.STEAL;
	        return State.WAIT;
	    }

	public void onExit() {

	}

	@Override
	public int onLoop() {
		switch (getState()) {
		case STEAL:
//code to steal from stall here
			break;
		case DROP:
//code to drop tea here
			break;
		case WAIT:
//code to wait here
			break;
		}
		return Calculations.random(500, 600);
	}
}

The code above will demonstrate to you simply how a state machine works

 

First, you run the code in the onLoop. This is seen by the 'getState()' line. This diverts the scripts runner to the getState method which checks if conditions are true. If a condition is true it stops checking which state you are in and returns that state as true, and executes the code in the block defined by that state. If the condition is false it continues to check the second condition.

 

PLEASE NOTE:

You always need a default case which will be set as true if all the above conditions are false. In this case the default is 'WAIT', which will only run if conditions 1 and 2 are both false.

 

Now let's look at the getState in context. At the moment it says 'Condition 1' and 'Condition 2', which are red underlined. That is because that code means nothing, we need to put something in there which means something! What we want to to is first define the tea stall. 

 

To define an entity (AKA GameObject) (non-npc in the game such as a cooking range, bank booth, crate, herb patch) you use the following code:

GameObject entityName = getGameObjects().getClosest("Entity Name");

FOR EXAMPLE:

GameObject stall = getGameObjects().getClosest("Tea stall");

Okay, so we've defined the tea stall, but now what?

 

Now we're going to want to check if it exists. This is called a 'null check'.

The idea behind a null check is to check if an object exists before interacting with it (you can't interact with an object when it doesn't exist, this will throw an error called an NPE (Null pointer error)). A null check will only interact with an object if it is not null (i.e it exists).

 

Here's the implementation:

private State getState() {
       GameObject stall = getGameObjects().getClosest("Tea stall");
        if (stall != null)
            return State.STEAL;
        return State.WAIT;
    }

If you paste that code in, you will probably recieve an error (red underlined "GameObject"). Why is this? because you've not imported what GameObject is, so the script has no idea what you're talking about. If you mouse over the error, it will give you a list of possible solutions. Select the 'import' one, like below:

 

 

What the above code will do when called:

 

1. Defines the tea stall
2. Checks if the tea stall exists
3. If it does, it returns State.STEAL
4. If it doesn't, it returns State.WAIT

Other things you can learn from this code:

 

• '!' means 'not' (inverted)
• brackets surround statements much like basic maths - 1+2*3 = 7 because it's 1+(2*3).
• the whole block is surrounded with { } which simply means the start and the end of the block

 

Simple, huh!? If not, it will be simple given time. Stick to it!

 

Now, we wanted to make the script be able to drop the tea in your inventory. So that's simple too, right?

 

if you're inventory is not empty, then empty it. This will also do the trick of dropping unneccessary random items!

 

Here's the code:

private State getState() {
GameObject stall = getGameObjects().getClosest("Entity Name");
if (!getInventory().isEmpty())
return State.DROP;
if (stall != null)
return State.STEAL;
return State.WAIT;
}

What the above code will do when called:

 

1. Defines the tea stall
2. Checks if your inventory ISN'T empty
3. If it isn't empty, it returns State.DROP
4. If it is empty, then it continues
5. Checks if the tea stall exists
6. If it does, it returns State.STEAL
7. If it doesn't, it returns State.WAIT

OKAY! so that's all good, we have our states defined correctly, but now what :/ I mean, it returns those states, that's great, but where's the code with what to do go?!

 

Well that's simple, it goes right inside your onLoop.

The following code will show you where it goes:

import org.dreambot.api.methods.Calculations;
import org.dreambot.api.script.AbstractScript;
import org.dreambot.api.script.ScriptManifest;
import org.dreambot.api.script.Category;
import org.dreambot.api.wrappers.interactive.GameObject;

@ScriptManifest(author = "You", name = "My First Script", version = 1.0, description = "Simple Tea Thiever", category = Category.THIEVING)
public class main extends AbstractScript {

	public void onStart() {
		log("Welcome to Simple Tea Thiever by Apaec.");
		log("If you experience any issues while running this script please report them to me on the forums.");
		log("Enjoy the script, gain some thieving levels!.");
	}

	private enum State {
		STEAL, DROP, WAIT
	};

	private State getState() {
		GameObject stall = getGameObjects().getClosest("Tea stall");
		if (!getInventory().isEmpty())
			return State.DROP;
		if (stall != null)
			return State.STEAL;
		return State.WAIT;
	}

	public void onExit() {

	}

	@Override
	public int onLoop() {
		switch (getState()) {
		case STEAL:
			GameObject stall = getGameObjects().getClosest("Tea stall");
			if (stall != null) {
				stall.interact("Steal-from");
			}
			break;
		case DROP:
			getInventory().dropItem("Cup of tea");
			break;
		case WAIT:
			sleep(300);
			break;
		}
		return Calculations.random(500, 600);
	}
}

So the following code will actually steal from the stall when the stall exists, drop everything in your inventory if it isn't full, and wait if the stall doesn't exist (when it's unstocked). Make sure the names of the tea stall and the cup of tea are correct first! (I might have got them wrong, I didn't check).

 

That's all on the code front, I've got some extension practice questions which you can try:

 

Easy:

When the script waits, can you make it wait for a random amount of time between 400 milliseconds and 1000 milliseconds, instead of waiting for 300 milliseconds every time?

 

Medium:

Can you make the script occasionally drink tea instead of drop it as a simple form of 'Anti-Ban'?

 

Hard:

Can you make the script flawless?

This includes the Medium task, and stopping the script walking around the other side of the stall (and if it does walk round the other side for whatever reason, make it walk back).

 

Very hard:

Add banking.

 

And that's it - the finished source!

If you have any questions about the source do not hesitate for one second to ask them and i'll do my best to help you out. If you're confused right now, all you need to know how to write is the conditions for the states, and what happens in the states. You do NOT need to know how to write a state machine.

 

 

PART 4 - COMPILING AND RUNNING THE SCRIPT

 

That's the hardest part over, now it's time to load this script up into DreamBot and get it running!

 

First, you need to save it as a .jar. To do this, follow the following steps:

 

 

Export it:

 

 

As a .jar...

 

 

Give it a name and location

 

LOCATION HAS TO BE TO YOUR DREAMBOT SCRIPTS DIRECTORY!

 

Hit finish!

 

To run the script, open up your dreambot, refresh your scripts and it should be there locally!

 

 

 

TEA THIEVER SOURCE CODE AND DOWNLOAD (untested!)

import org.dreambot.api.methods.Calculations;
import org.dreambot.api.script.AbstractScript;
import org.dreambot.api.script.ScriptManifest;
import org.dreambot.api.script.Category;
import org.dreambot.api.wrappers.interactive.GameObject;

@ScriptManifest(author = "You", name = "My First Script", version = 1.0, description = "Simple Tea Thiever", category = Category.THIEVING)
public class main extends AbstractScript {

public void onStart() {
log("Welcome to Simple Tea Thiever by Apaec.");
log("If you experience any issues while running this script please report them to me on the forums.");
log("Enjoy the script, gain some thieving levels!.");
}

private enum State {
STEAL, DROP, WAIT
};

private State getState() {
GameObject stall = getGameObjects().getClosest("Tea stall");
if (!getInventory().isEmpty())
return State.DROP;
if (stall != null)
return State.STEAL;
return State.WAIT;
}

public void onExit() {

}

@Override
public int onLoop() {
switch (getState()) {
case STEAL:
GameObject stall = getGameObjects().getClosest("Tea stall");
if (stall != null) {
stall.interact("Steal-from");
}
break;
case DROP:
getInventory().dropItem("Cup of tea");
break;
case WAIT:
sleep(Calculations.random(500, 600));
break;
}
return Calculations.random(500, 600);
}
}

Download: http://uppit.com/vst9a08w8r5y/simpleTeaThief.jar

 

 

That's the end of this tutorial and hopefully I inspired a new wave of scripters!

 

If you have any questions do not hesitate for a second to post below, send me a PM or even add my skype (i'd prefer contact via DreamBot first before contacting my skype though!)

 

That's all folks!

 

Happy scripting,

Apaec.

Edited May 2, 2015 by Swaq

[Val 125]

Where is the thread that teaches me how to code again? :^)

[Eliot 193]

May I suggest using the default text color so it is more readable on Basik, thanks.

[yoyo0 22]

Thanks will definitely use when i have free time.

[Apaec 78]

May I suggest using the default text color so it is more readable on Basik, thanks.

 

Sorry ,copied over from u know where, forgot to change text colour!

 

EDIT: Made all the grey text black.

Edited December 10, 2014 by Apaec

[Pandemic 2468]

Nice tutorial, thanks

[Antonio 116]

Very detailed guide man, I'll have to give this a shot when I finish my exams

[Swaq 243]

Thanks so much for this my man! I have a month off and nothing to do. I was actually planning on learning and this is really a great help.

[Botre 27]

Coolio 

 

You should (probably always) use the "automatic" color.

 

 

PS: class names should start with a capital letter.

Edited December 11, 2014 by Botre

[Cinnamon 20]

Thanks so much for this my man! I have a month off and nothing to do. I was actually planning on learning and this is really a great help.

Couldn't say it any better.