Script Building Tool

Updated 08.07.2024

Introduction

With the release of LSS Bot 5.13.0 on Dec. 18 2023 a new tool was added, as of Jan 3 2024 it has been released to the public.

This tool allows the user to create basic to intermediate scripts for the bot without any programming knowledge. It comes with prewritten code, all the user has to do is build the logical blocks by selecting from the available code.

Important! LSS Bot will not provide support or help creating, maintaining, fixing or debugging your personal scripts. 

Requirements

In order to use this tool and load the created scripts, you must have an active script builder tool license.

Please read the tutorial step by step, if you skip a step it most likely will be difficult to understand what the next step talks about!

Creating Projects

Before we start, please keep in mind that while the script builder tool is open the bot will only load local scripts. The server scripts won’t be displayed.

Let’s create our first project. Start off by opening the new script builder tool that can be found in the “Script Building” tab. The project manager will open up. Press the “Create New Project” button in the bottom to get started. Give your project a name, select a game from the list and fill the other fields if you wish. Finish off by hitting the “Create New Project” button.

Note: the description accepts HTML if you’re familiar with it and feel like adding a fancy description for your script.

Screen Tab

Now let’s go over some basics and start with the “Screen” tab. This tab can be used to gather information from the emulator that later on will be used in your scripts.

Actual usage of templates (assets), coordinates and other things mentioned in this tutorial can be found in the “Variable Types” tutorial.

Templates (Assets)

You will often times find yourself comparing templates to figure out what menu the bot is on, or to find a button that the bot should interact with. Getting templates is super easy, all you have to do is open the needed menu in game (on the emulator), press the “Update image” button in the “Screen” tab, the live in-game screenshot will appear in the tool. Next select the “Save As Template” and “Build Rectangles” checkboxes. Now whenever you select 2 points on the screen the bot will automatically crop the image and save the template on your PC.

As an example we have opened the “Commander Skill” menu on the Age of Origins game and saved the menu title asset to later on check whether that menu is open in our script.

Getting Coordinates

Often times buttons or other objects will appear in a consistent area on screen, so there is no need to look for a template. We can simply interact with that area. The bot allows you to interact with a rectangle area (it gets a random point within that area) or a point (x, y coordinates).

You can move your cursor on top of the image that is in the “Screen” tab and the coordinates of your mouse position will be display in the top of the menu. Additionally you can uncheck the “Save As Template” option and click on the image. The bot will print the point that you interacted with, or build a rectangle if you toggled the “Build Rectangles” checkbox. You can configure the text colors if they are difficult to read on your image by pressing the “Configure colors” button in the top menu. The coordinates are automatically copied to your clipboard and printed in the “Logs” tab.

Rectangle format: x, y, width, height
Example: 30, 50, 10, 10

Point format: x, y
Example: 300, 250

Threshold Tool

The bot is able to read text from the emulator. There is however a lot of noise on the image, making it difficult for the bot to get an accurate result. For that reason we can add different filters to the image as well as crop it. The threshold tool will give you a visual example of the available filters and will also give you an option to test what text the bot sees on the given image.

Most of the time you will want to crop your image before reading the text. Reading the whole image will take a lot of time and chances are slim that you’ll get the correct result. Select the “Build Rectangles” checkbox and build a rectangle of the area that contains the text that you want to read. Press the “Threshold tool” button in the top and select the “Last Cropped Screenshot” option. The tool will open up in the back. You can use the sliders to change the filter type and it’s value. To check what text the bot sees you can press the “Parse Text” button. As an example we’ll use the same area from the AoZ game that we took a template of.

Tip: most effective filters are type 1 and 3, values ranging anywhere from 80 to 150 in most cases.

Script Tab

This is the main part of the tool that you’ll spend most time using. It contains your project structure, list of assets that you have saved by using the “Screen” tab or manually cropping the images and putting them into the folder, list of conditions and loaded code (methods).

Conditions

Conditions are code pieces that the bot will use on certain methods. For example the bot is able to sleep until a condition is met or if it’s taking too long for the condition to be completed. If you have programming knowledge you can manually write the code for the conditions by pressing the “Add Manually” button in the “Conditions” tab. In most cases this is not necessary as you can save conditions in the “Add Condition” menu that we’ll talk about later in the tutorial.

We’re jumping a little bit ahead and will have a better example of conditions being used in action later. On the image below you can see 3 conditions. Two of them have been added using the “Add Condition” menu, as the name suggests they check whether the bot is in base, or on map. The third condition has been added manually and is a combination of the first two conditions. It checks whether the bot is in base or on map at the same time. We will be able to pass it on later to the bot and sleep until a condition is met.

Project Structure

Your project will have a tree based structure and will consist of basic “if”, “else if”, “else” code blocks. For a better understanding, if you have no programming knowledge the pattern is pretty simple, we will use the same Age of Origins example with the “Commander Skill” menu:

-If the “Commander Skill” template
—-We click an area on screen to use a skill
—-We stop the script
-else if we are in base
—-We print a message saying that we’re in base
—-We click an area of the open skill menu button to open the menu
—-We print a message saying that we have clicked the area on screen
—-We sleep until the template becomes visible or 5 seconds (5000 milliseconds) will pass
-else if we are on map
—-We print a message saying that we’re on map
—-We click an area of the open skill menu button to open the menu
—-We print a message saying that we have clicked the area on screen
—-We sleep until the template becomes visible or 5 seconds (5000 milliseconds) will pass
-else
—–We print a message saying that we don’t know what menu is open
—–We try to close the menu (can be done in many ways but more on that later)

For beginners it is recommended to only use the “if” statement and close every single “if” block with a “return” statement. Here’s the same example but without the log messages and without sleeping until the menu is open:

-if commander skill template is visible
—-click the area on the commander skill menu
—-return -1 (to stop the script)
-if we’re in base
—-open the commander skill menu by pressing an area on screen
—-return 0 (this will tell the bot to not check for any conditions below)
-if we’re on map
—-open the commander skill menu by pressing an area on screen
—-return 0 (this will tell the bot to not check for any conditions below)
-we just add an action, trying to close the unknown menu. No return statement is needed here as it’s the last line

Please keep in mind that these are just examples, the actual area that the bot is clicking is random. You can get the correct area using the “Screen” tab as described in the previous tutorial step.

Check the next tutorials to learn how to create the logical blocks and how all the statements work.

Variable Types

In this step you will learn in detail how to create your script. It contains many real use case examples, explains how to add actions, check for conditions, search and interact with templates, read text and use different operators.

When adding actions and conditions to your logical blocks you will notice that every method (action or condition) will have a “return type”. These show what type of result you’ll get using the selected method and how the result can be used. Currently the bot loads all available methods that have been coded into the bot, yet this tool is currently unable to utilize all of them. Below you’ll find a list of the supported return types and examples on how to use them.

If a method has a parameter it also will have a type. This tutorial is mainly about return types and their usage but it will also make clear what parameters to pass and what they should look like.

Void

Void does not return any value, it’s an action that will be executed from your top node to the bottom node until a return statement is reached. Voids won’t appear in the “Add Condition” menu as they’re being used as plain actions. You’ll find them in the “Add Action” menu. All the available return types can be used as voids, if you do not want to check whether an action was successful or not.

Examples of the voids you’ll use the most:

  • sleep(int) – wait X milliseconds before performing the next action in queue.
  • getDevice#log(String) – print entered message into the logs on the INFO level.
  • getMouse#click(BRectangle) – clicks (touches) an area on screen where BRectangle: xCoord, yCoord, width, height.
  • getMouse#click(int, int) – clicks a point on screen where int, int: x coordinate and y coordinate.
  • getMouse#drag(DragDirection) – performs a swipe event to drag or move the screen in the selected direction.
  • getMouse#drag(int, int, int, int, int, int) – performs a swipe event, where int parameters are: xStart, yStart, xEnd, yEnd, stepCount, executionTimeInMilliseconds. Example: getMouse#drag(50, 60, 200, 300, 25, 750).
  • getKeyboard()#pressBack() – sends a back event, just as if you’d press the back button on your Android phone, can be used to close most pop ups and menus.
  • getKeyboard()#type(String) – types the entered text.
  • updateScreenshotCache – updates the screenshot (image) that the bot should work with in the future, check the “sleep” tutorial for examples on when this should be used.
  • isMenuOpen(String) or getMenu#isOpen(String) – may be called slightly different depending on the game that you play. It reads the in-game menu header part and returns true if it sees a text match (usually is not case sensitive).

Boolean

If you haven’t learned about conditions yet it is recommended to read the conditions tutorial in the “Script Tab” section first.

A boolean is a value with two choices – true or false. Booleans will allow us to check if a certain condition is true or false. For example we can tell the bot to check if a certain menu is open, or some text is on screen, or a template is visible and only perform actions when it is. You’ll find boolean methods in the “Add Condition” and “Add Action” menus.

While it’s best to use booleans to check for conditions and only act if a condition is true, they can still be used the same way a void is used. For example the bot has the boolean “sleepUntil(Condition, int)”. As the name suggests this method will force the bot to sleep until the given condition is true, or if the condition isn’t met within X milliseconds. We can tell the bot to do something if the expected condition was met and do something else if it timed out (example 1). But we can also use the “Add Action” menu and tell the bot to sleep until some condition, and no matter what the outcome is going to be – whether it’s met or not the bot will execute the action node below (example 2).

Example 1 – using booleans to act based on result

Example 2 – using booleans as voids

Example 3 – a more complex logical chain

We can also add a “logical not” check to any boolean. In the “Add Condition” menu select the “!” operator and the bot will check for the reverse condition. For example if you want to make sure that we are not on map we can do the following:

String

If you haven’t learned about conditions yet it is recommended to read the  conditions tutorial in the “Script Tab” section first.

Strings represent text, unlike booleans Strings will only be useful for checking if a condition is true. In most cases text reading related methods will return a String. Since a String returns text we’ll have to use “operators” to check whether a condition was met or not. Conditions that can be used with Strings are:

  • contains
  • equals
  • equalsIgnoreCase
  • startsWith
  • endsWith

Adding operators is pretty simple, there’s a selection box in the “Add Condition” menu. Simply select the method, operator and enter a value. In the examples below we’ll try to identify whether the “Mail” menu is currently open by reading text and using different operators.

You can convert the return value to String, if you want to use an operator that only works for a String value, by ticking the “To String” checkbox, this can in some cases lead to logical errors.

Example 1 – reading text on screen within a constant area

In this example we’ll tell the bot to look at a certain area, in this example 240, 9, 52, 27 (x, y, width, height) and print a message if it can see the word “mail” no matter what the case is (MaiL, maIL, MAIL – either option will return true, this operator ignores the case).

Example 2 – reading text on screen within a constant area but using filters

Reading text is often times difficult and time consuming, however as explained in  the “Threshold Tool” section of the “Screen Tab” tutorial, cropping area and using filters makes the results very consistent if done right. Please make sure to read the “Threshold Tool” tutorial before looking at this example.

This example is similar to “Example 1”, however instead of using get “getOCR#parseText(BRectangle)” method we will use the “getOCR#parseText(BufferedImage)” method.

First build a rectangle and use the threshold tool (“Screen” tab) to find a filter and area that helps the bot see the correct text. In the example below the same area 240, 9, 52, 27 (x, y, width, height) and filter 1, 145 (type, value) seems to work well and the bot sees the correct text on screen “Mail”.

Now let’s add the actual nodes. In this example we will check if the text that the bot sees contains the text that we have entered. It is usually best to use the “contains” operator because the bot might see custom characters or white spaces. We can simply check if part of the text is visible.

Press the “Select” button in the parameters to set the area and filter. For this example leave the optional asset selection empty (do not change it).

As result we’ll end up with the following structure:

Int, double

These return types will return a number:

  • int (ex: 12000)
  • double (ex: 0.7)

Similar to the String example, to compare such values we will have to use “operators”. Supported operators are:

  • == (equal)
  • != (not equal)
  • > (greater than)
  • < (less than)
  • >= (greater than or equal to)
  • <= (less or equal to)

You can convert the return value if it’s a String to an integer, if you want to use an operator that only works for an integer value, by ticking the “To Integer” checkbox, this can in some cases lead to logical errors.

Example 1 – act if we roll a random number greater than

Let’s use the bot’s RNG#nextInt(int, int) method. It generates a random int (integer) number within the passed range (min, max). In this example we’ll “roll the dice”, if the value that we roll will be greater than 50 we will sleep for 5 seconds by adding the “return 5000” statement, else we’ll stop the script.

Example 2 – using double, getLuminance and getColorPatternPercentage

On most games you will encounter a scenario where a button may change it’s color (or become “inactive”) if it cannot be interacted with. For example often times if a reward can be claimed the “claim” button will have a certain color, if it has been claimed before or cannot be claimed yet it will have a different color, or be grayscale. The bot has a method to check whether the image is grayscale or not, however it may not always be consistent. Instead you can use the following 2 methods:

  • ImageUtil#getColorPatternPercentage(BufferedImage)
  • ImageUtil#getLuminance(BufferedImage)

To use these methods effectively you have to know what results the bot sees when calling these methods. Use the “Color tool” in the “Screen” menu to analyze the results with the “active” and “inactive” buttons. Then just set the necessary operator and the crop area (as described in the String tutorial #2).

Important! When you select the BufferedImage only use the “crop area” option. Do not use the threshold filter or an existing asset. Also pass a double operator value that contains a dot (eg 100.0).

BRectangle (and BPoint)

To understand this type it is important to read the “Screen Tab” tutorial first.

BRectangle is a rectangle shaped area on screen (x, y, width, height). We have already learned how to get coordinates on screen and what to pass if the method’s parameter is BRectangle. Now let’s look into the case where the method itself returns a BRectangle.

Whenever the return type of a method is “BRectangle” or “BPoint” additional options will pop up on the “Add Action” menu. These options area:

  • Interact if found – if the area or point exists (is not null) the bot will click it
  • Sleep until condition (checkbox) – sleeps until the selected condition
  • Condition selection – for the sleep until option
  • Sleep until timeout – for the sleep until option above, the timeout value in milliseconds if condition isn’t met
Example – finding a template match on screen

Often times we won’t be able to rely on a button to be in a constant spot. In such situations we can use template matching techniques. In this example we will use the “getOpenCV#getAreaMatch(String, double) method. We have already explained how save templates (assets) in the “Screen Tab” tutorial. In this example we’ll tell the bot to search for a template (button that opens the alliance menu on the AoZ game) on screen and if it’s visible we will interact with it.

Since LSS Bot already has a boolean method that can tell whether the alliance menu is open or not we can find it and save as condition. Press the “Add Conditions” button, find the method and press the “Save To Condition List” button.

Now that we have added a condition that can be used to check whether the alliance menu is open we can move on to calling the “getOpenCV#getAreaMatch(String, double) method.

You likely will notice that even though one of the parameters is a String you’ll end up seeing a “Select Asset” button instead of the default String input field. Instead of having to type the path to your template simply press the button and select the file in the menu that’ll pop up.

Now that we’ve selected the asset we can adjust the double value. The double value in this method represents the accepted match result (how confident the bot is that the template is on screen) in % (value * 100). The default value is set to 0.75, this adds up to be 75%. If the bot’s confidence is equal or greater than 75% it will assume that it sees the template on screen, and that it can be interacted with (is not null). For most cases the default value is good enough for the bot to find a static template and to not confuse it with something else on screen, however sometimes you might have to adjust this. Just for the sake of this tutorial let’s set the value to 0.9 (90%).

Next we want the bot to interact with the template if it finds a match and sleep until the alliance menu opens. Let’s check the checkboxes, select the correct condition and set a sleep timeout.

When you run this script the bot will perform a quick check and see if it’s 90%+ confident that the template is on screen. If it sees the template it will interact with the area on screen and sleep until either the alliance menu opens or 4 seconds pass.

Return Statement

Now let’s look into the “Return” statement and what it does. Whenever the bot executes the code and hits a return statement it will jump back to the top most node and start the loop from start. Passing negative values will stop the script, zero (0) value will do nothing but return to the start of your project structure, positive values will also force the bot to sleep for X milliseconds.

Examples:

1) return 0 – the bot will stop jumping down the nodes and return to start.
2) return -100 – the bot will stop reading the nodes and stop the script.
3) return 5500 – the bot will stop reading the code, sleep for 5.5 seconds and return to the start of the loop.

Let’s look at the following example:

In this example the bot will:

#1 Check if a menu with the title “quest” is open.

*If the menu is open it will print a message, click a point (100, 300) and stop the script
*If it does not see the menu it will jump to #2

#2 Check if it’s in base

*If it is in base it will print a message and attempt to open the quest menu
**If it succeeds it will print a message and return to #1
**If it fails it will jump to #5

#3 Check if it’s on map

*If it’s on map it will print a message and attempt to enter base
**If it succeeds it will print a message and jump to #5
**If it fails it will jump to #5

#4 It does not know what menu is open, it will print a message, send a back key event attempting to close the menu, sleep 3 seconds and return to #1

#5 print the message “We have reached the end of the loop” and return to the start

Executors

Executors are bits of prewritten code that will be executed on top of your script. These can be added on script start or end. Depending on the game you play you will see a set of different executors. To add or remove an executor press the “Add Executor” button. In the executor editor select an executor, set the parameters just like you’d do that in the add actions or conditions menu, select when the executor should be added (on start or on stop) and press the “Add Executor” button. Executors that have been added on start will be executed before running your script code. Executors that have been set to run on stop will be executed on the engine level, meaning that they will be executed before running the next queued script.

Executors are super handy, on some games you’ll be able to force the whole building upgrading process by just adding an executor!

Keep in mind that not all executors can be used and that they will have priority over your script until they finish executing.

Example 1

In this example we’ll add an executor that will run before our script code. It will make sure that we re-enter the base screen on Last Shelter Survival.

Example 2

Let’s tell the bot to perform a full building upgrade of the “Farm” building on Rise of Empires. We’ll pass the parameters to leave 0 free workers, use speedups, open resource boxes and skip base upgrade requirement.

Example 3

Now let’s find the fortress building on Primitive Era.

Tips

Multiple Scripts

Using this tool you won’t be able to have “flags” that will remind the bot that a certain action has been done. If you want to perform an action only once, for example enter coordinates on the world map, or find a building, there is no way to tell the bot that it has already been done using this tool. However there’s a simple workaround – create two separate scripts. Use one to perform the action and follow up with the next script.

Other Useful Methods

Click Template

Another useful boolean you likely will use is getDevice#clickTemplate(String, double, Condition, int) . This method looks for an asset with the pass threshold (double value) and interacts with it if it’s on screen. It will then sleep until the condition is met or if it times out. It is recommended to check whether the template is on screen first by calling getOpenCv#isTemplateOnScreen(String, double)

Compilation

Once your script is ready you can compile it. Open the “Build” tab and press the “Compile Project” button in the bottom. The compilation result will be printed in the “Logs” tab. As long as the logic is correctly structured and no unsupported return types are used you should not see any errors. The code will be saved as a .java file and compiled into .class files, these can be found in your project folder. The bot will also automatically build a .jar file and place it into your scripts folder. 

Some compilation errors might be difficult to understand for an user without programming knowledge. It is recommended to test your script as you build it. Build a block and test whether it works and go from there. It will be much more difficult to spot an error in a large project that you built without testing.

Please keep in mind that while you’re still in developer mode the bot will only load local scripts. Currently you have to restart the program to disable the developer mode.

Videos

We’re in process of recording video tutorials. Please let us know what videos you feel are missing.

Text Reading (OCR)

Interacting With Templates, Using Conditions

Adding Executors