Writing Your Own Scripts

Updated 24.02.2023

Introduction

You can write your own custom scripts on top of LSS Bot. Most of the time all you’ll really need is basic Java knowledge. The process is really simple:

1) Import the “lssbot5.jar” library to your project.

2) Write your own script.

3) Build an artifact without dependencies.

4) Place the .jar into the local scripts folder.

The library and local scripts folder can be found in the following directory: C:/Users/USERNAME/lssbot_5/

Requirements

Your lssbot account must have an active subscription and you must also install  Java 17+.

Tools and docs

You can find our development tools in the program in the “Development” tab. Simply run an emulator that is tied to one of your LSS Bot instances and wait until the bot connects to it. Select the emulator in the dropbox and press the “Open Development Tools” button.

The tools should cover most things but if something is missing you can always write your own custom script/tool.

The javadocs can be found on this page.

Structure

Your project must have a class that extends AbstractScript that class must also have a ScriptManifest annotation. This is the main class of your script. Your script must also have a class that implements Config. The config class is used to process script settings.

Structure example

Main class example

Config example

After compiling the script and placing it in the scripts folder the bot will parse it and you should find it in the script configuration menu.

Important

Please avoid using inner classes in your script, this includes statements like switch that create inner classes. Always override onStart methods to avoid running into parse or logical issues.

If the bot fails to parse your script you should get an error in the log.

Basic API usage

Examples can be found below.

Capturing image

The bot will automatically take a screenshot and cache it on every loop. Most methods will automatically reuse that cached image when called, usually these methods are overloaded and you can pass another image too. To access the cached image call getLastScreenshot(). You can also update the cached image by calling updateScreenshotCache().

AbstractScript

The AbstractScript extends APIContext<Device> which contains all the methods you’ll need. You will find ways to interact with the emulator, work with images and also method providers that contain specific game related methods. Game specific methods can be initialized separately for easier access. An example of Last Shelter Survival methods is LSSMethodProvider. The game related classes should be pretty self explaining for someone who plays the game.

ScriptNode

If your script has multiple tasks you can use ScriptNode this will change the way the script executor works. Instead of calling  AbstractScript#loop it will take a node approach. The bot will go through all the nodes that have been added to the AbstractScript until it has none left that should be executed. Adding nodes can be done by calling AbstractScript#addNode.

When using ScriptNode AbstractScript#loop should return a negative value.

Executor

An Executor can be added to AbstractScript and it will take priority over the main loop until it no longer should be executed or gets removed. LSS Bot provides some pre coded executors that will make your life much easier. For example you won’t have to write all the code to handle speedups on Last Shelter Survival, all you have to do is initialize LSSSpeedupSolver and add the executor to AbstractScript by calling AbstractScript#addExecutor. The executor will have priority over your script and will be executed once it hits a condition that tells it that it’s no longer needed, the control will then return to the script.

Logging

You can access different logging levels by calling Device#log, Device#warn, Device#error, Device#debug.

Config

Every script must have a class that implements Config. LSS Bot will automatically convert certain objects and primitives to UI components.

ConfigItem

The ConfigItem annotation targets field variables, most elements are self explaining and are being used to save and display settings. Except for int[] defaultNumberModel and String[] defaultStringModel, these are being used to initialize the NumberPickPanel and StringPickPanel.

Config table

Object or PrimitiveUI ComponentGet selected values
intJSpinnerprimitive int value
booleanJCheckBoxprimitive boolean
ArrayList(String)JComboBox(String)ArrayList#get(0)
NumberPickPanelNumberPickPanelNumberPickPanel#getSelectedValues
StringPickPanelStringPickPanelStringPickPanel#getSelectedValues
StringOrderPickPanelStringOrderPickPanelStringOrderPickPanel#getSelected
StringJLabelHTML string

Examples

We will be using different techniques in the examples below, the purpose is to demonstrate the API usage, even if the used methods may not be the most efficient.

Example #1(LSS)

Let’s write a script for Last Shelter Survival that will open the “World Map Display Settings” and enable all the available options. For demo purposes we will use LSSViewportChanger in this example to open the map, even though it’s much easier to just call the LSSViewport#enterMap.

Source code can be found here.

Templates used in this example

Example #2 (ROK)

Exact source code of the VIP v0.0 script for Rise of Kingdoms can be found here.

Example #3 (ROK)

Exact source code of the Mail v0.0 script for Rise of Kingdoms can be found here.

Example #4 (ROK)

A more complete example RoK Fog Clearing Script v0.0 gist can be found here.