Tutorial: Simple agar.io bot

Saw that small code snipped on our startpage? In this tutorial we’ll program something quite similar: A super basic agar.io bot script.

agar.io is an online browsergame were you start as a small blob and become bigger by “eathing” other blobs. Once big enough you can even start “eating” other players.

While winning a game is difficult, writing a simple bot for educational purposes is simple.

In this tutorial we will use botfathers Browser API, Vision API and Helper API.

Step 1: Loading the game

The first thing our bot shall do is loading the games website http://agar.io/. To do so we use the Browser.loadUrl method. This method is asynchronous, which means that it does not wait for the website to finish loading.

Browser.loadUrl("http://agar.io/");

But we want the bot to wait for the website to finish loading. We could use a method such as Helper.sleep to wait for some seconds. But depending on the users internet connection we might be waiting too long or not long enough.

Browser.loadUrl("http://agar.io/");
Helper.sleep(10); // Wait for 10 seconds. This might be too long or not long enough for the website to load.

Instead we use the Browser.finishLoading method to make the Browser wait for the website to finish loading. Doing so the script will continue once the website finished loading.

Browser.loadUrl("http://agar.io/");
Browser.finishLoading(); // Wait for the website to finish loading.

By default the Browser.finishLoading methodreturns false after 30 seconds, if the website takes longer to load. Read the Browser API documentation to learn more.

Step 2: Start the game

After loading the games website, we’re presented with the games start screen. Here we have to click the play button and optionaly enter a username.

There are two methods to solve this “problem”. We could either take a screenshot, find the play button and click at it’s location or execute some javascript in the browser to submit the login form.

While executing javascript is the faster and more robust way, it’s not always possible. Executing javascript does only work on websites, neither on Android nor on the Desktop. Taking screenshots, finding subimages (templates) on it and clicking them always works.

Using browser javascript

As shown on botfathers startpage we just have to find the HTML play button and click it using javascript. If you known HTML (Hypertext Markup Language) this is straight forward for you: Just write a little javascript code snipped and execute it using the Browser.executeJavascript method.

For newcomers this might be confusing: We’re writing bot scripts in javascript and sending a javascript to the browser to execute it there (dafuq?). If you don’t know HTML you might want to ignore this section, but look at the Using image recognition instead.

The play button elements id it play. Using document.getElementById we can get a reference to the element and call its .click method to click it.

var click_script = "document.getElementById('play').click();";
Browser.executeJavscript(click_script);

Using image recognition

Mastering image recognition is what you want to create good bots. We’ll employ a method called template matching. To do so we need a screenshot of the browser and an smaller image, called template, we want to find in the screenshot.

To get good results, called matches, you want your template to look as distinct as possible. The template must look the same as in the screenshot. Looking for a scaled version of it won’t work.

To take a screenshot of the browser we use the Browser.takeScreenshot method. It will return an Image object. We store the screenshot in a variable called screenshot.

var screenshot = Browser.takeScreenshot();

On the screenshot we’ll look for a template of the play button shown below. Download and put it next to your script file.

To load the play buttons template image we use the Image constructor method. We store the loaded template Image object in a variable called template.

var template = new Image("play_button.png");

It’s time to use one a Vision API method. Vision.findMatch takes three parameters: A screenshot, a template and a score a returns a Match object.

The match object will tell us where the template has been found on the screenshot. If there are multiple matches, the best one is returned.

The score tells the Vision.findMatch method how good at match must atleast be. A score of 0.5 means: the template must match something in the screenshot atleast 50%. We want the template to match atleast to 95%.

var match = Vision.findMatch(screenshot, template, 0.95);

Using the Match.isValid method we can check whether the play button could be found.

To click the play button we use the Browser.leftClick method which takes a Point object. We want to click the play button matches center. To do so we use two methods: Match.getRect and Rect.getCenter(). Read the Rect objects documentation to learn more.

// Complete code using image recognition:

var screenshot = Browser.takeScreenshot();
var template = new Image("play_button.png");

var match = Vision.findMatch(screenshot, template, 0.95);

if (match.isValid()) {
    var play_button_position = match.getRect().getCenter();
    Browser.leftClick(play_button_position);
}

Step 3: Play the actual game

work in progress…

Step 4: Respawn

work in progress…