osrsb / script-template

Template for OsrsBot scripts

Script Template

---

Community

• Discord

Building your first script

Setting up the environment

It is a personal recommendation that you attempt to clone this repository using IntelliJ

This is so the intended template present is loaded as it was created.

Doing so will allow the run configurations to be prepared for you to simply run the script effortlessly.

Making Changes

The project uses Gradle to handle dependencies, so if you're interested in adding a new library to your script then simply add it in whatever manner that library recommends.

API Reference

To explore the methods you can use in your script check out the API References here:

OsrsBot API Reference

One for the DaxWalkerRSB API will be added later.

By default, the project will come with RuneLite, OsrsBot, and DaxWalkerRSB already listed as imports for use.

The script in the example is a basic cannonball making script to outline general script making practices and capabilities. An advanced script maker can go far beyond this adding their own dependencies, functionalities, utilizing the WebWalker (DaxWalkerRSB), and even go as far as edit the underlying API if they see the need to. After all, it is open source.

Testing your script

To Run

To run your script it is as easy as hitting the green play button in Intellij

Using the drop-down menu provided you can easily select from a few different pre-made run configurations like headless mode or running inside a docker container (and of course whatever variation you choose.)

Debugging

You can use the debugging features present in both IntelliJ (the bug button beside the play button) and utilize some ones present in both OsrsBot and RuneLite to diagnose any unwanted behavior. In the future the API will support being launched using an RSPS client for quick testing scripts.

Why is it so easy?

The reason this works so simply is due to Gradle run tasks being configured to enable accessing OsrsBot 's main method without IntelliJ throwing an error. Since we have the project set-up to already have settings configured script-template[botRunGUI]. If not just select that one to launch. Other options are available, so feel free to toy around with them.

Deploying your script

Using IntelliJ you should find that compiling your script is rather simple. In IntelliJ build outputs are referred to as Artifacts.

IMPORTANT

When you go to create an artifact ensure that ONLY the compiled source is selected as output UNLESS you imported an external dependency that wouldn't be used in OsrsBot, DaxWalkerRSB, or RuneLite

Instructions:

To set up an artifact that outputs as a jar (the format one would use in the OsrsBot.jar) simply hit:

1. File
2. Project Structure
3. Artifacts
4. The plus sign in the center column
5. Jar
6. Empty
7. From Available Elements Open the drop-down for Script_Template
8. From that drop-down open the one for Main
9. Double-click 'Script_Template.main' compiled output
10. Click Ok
11. Click Apply (in the Project Structure interface)
12. Click Ok (in the same interface as above)
13. Your jar will be present in the project's build directory inside libs

Now you have a script you can use in the OsrsBot.jar OR you can continue to run and test within your build environment. It is up to you.

Where to put your scripts

To use a script for OsrsBot, traverse to the following location and place the .jar:

Windows: C:\Users\[username]\OsrsBot\Scripts\Precompiled
Linux: /home/[username]/.config/OsrsBot/Scripts/Precompiled
MacOS: /Users/[username]/Library/Application Support/OsrsBot/Scripts/Precompiled

Otherwise; if the script is in the form of class files drop them into the Scripts/Sources folder.

Now you're ready to script.

Docker

The script-template additionally includes a Dockerfile to aid in building containers. The Dockerfile itself is fairly simple and anyone experienced with Docker should find this all very easy to use. That said it isn't necessary for general script builders to be utilizing containerization, but decent reasons include wanting to keep the bot files separate from your actual PC. (Currently the builds target your PC, but execution will occur on the container). That said there are Gradle tasks for easier Docker building, but some essential instructions are needed first.

Install Docker:

https://docs.docker.com/engine/install/

XServer

For Windows, I personally use: https://mobaxterm.mobatek.net/

For Mac, XQuartz is a nice XServer tool. Click this link for extra details on setting that up

Nix users should be capable of setting up an XServer without instruction.

Easy Instructions

So provided are run configurations which are accessible next to the green play button at the top in which you can select options dockerRunGUI or dockerRunHeadless which will both build and run the docker build. This is by far the easiest method to launch, but should you choose to be difficult then below are some helpful commands.

Manual Instructions

Build Docker:

docker build -t bot-image .

Run Docker:

This will remove the container every time you run it (Fresh container)

docker run -e DISPLAY=host.docker.internal:0 -t --rm bot-image

Without removing the container

docker run -e DISPLAY=host.docker.internal:0 -t bot-image

Or without docker.host:internal

docker run -e DISPLAY="$(ip -o route get to 8.8.8.8 | sed -n 's/.*src \([0-9.]\+\).*/\1/p'):0.0" --rm -t bot-image

Open Terminal in IntelliJ: Alt+F12 (Windows)

To connect to a running container with Bash open the terminal in Intellij (or wherever) and then run the following

docker container ls

Note the name for the container (unless you want to copy the id) Then with that name run

docker container exec -it {container-name} bash

For Windows users if you make any mistakes with your Docker setup, check here for some guidance docker/for-win#6971

Script Reloading

The above link redirects to the wiki page with detailed info on how to appropriately perform script-reloading in the current state of the client

If you find a bug in any API of OSRSB report it in the respective API library.

Current libraries are:

1. OsrsBot
2. DaxWalkerRSB

script-template's Issues

[TODO] Add DaxWalkerRSB use

The walker isn't really used in the script so no example usage is given. This is compounded by the lack of server-side control currently for said API.

Multi-stage Dockerfile with Gradle cache + local dependency copies

We should implement a multi-stage Dockerfile that cache gradle dependencies and copies over the local dependencies for a Script - minimally that's just OSRSBot, but we can use DaxWalker as well

Here's an example that isn't quite right

# using multistage docker build
# ref: https://docs.docker.com/develop/develop-images/multistage-build/

# temp container to build using gradle
FROM gradle:7.4.2-jdk17-alpine AS TEMP_BUILD_IMAGE
ENV APP_HOME=/usr/app/
WORKDIR $APP_HOME
COPY build.gradle settings.gradle $APP_HOME

COPY gradle $APP_HOME/gradle
COPY --chown=gradle:gradle . /home/gradle/src
USER root
RUN chown -R gradle /home/gradle/src

RUN gradle build || return 0
COPY . .
RUN gradle clean build

# actual container

# Set base image from Docker image repo
# https://adoptium.net/temurin
FROM eclipse-temurin:17-jre-centos7

# Installs XDisplay packages so we can actually view the container (and run the bot)
RUN yum install libXext.x86_64 libXrender.x86_64 libXtst.x86_64 -y

ENV BOT_JAR_FILE=OSRSBot.jar
ENV APP_HOME=/usr/app/

# Adds the bot jar to the container
COPY --from=TEMP_BUILD_IMAGE $APP_HOME/$BOT_JAR_FILE .
# Adds the scripts to the container
COPY --from=TEMP_BUILD_IMAGE $APP_HOME/build/libs root/.config/OsrsBot/Scripts/Precompiled

# Exposes a port to connect via
EXPOSE 8080

# Runs the bot with the bot flag
ENTRYPOINT exec java -jar ${BOT_JAR_FILE} -bot-runelite -developer-mode

[TODO] Add comments to the script

Currently, it is a bit too ambiguous. Good for now, but definitely should be improved later.

[FEATURE] Finish containerization implementation

Currently, the docker instructions are added, the docker file is added, and the client does run within the container, but we need to add to the Dockerfile the script directory.
Currently this is a bit of an issue since we generate the script output directory straight to the user home directory.
Docker is unable to actually view anything outside the working directory.
This means we should instead build into the standard build directory AND the script directory.
This will have to be implemented in Gradle via task that triggers on build.

Project has become a bit chaotic and needs to be brought back in line for streamlined ease of use and accessability.

Use Wireguard & Docker Compose to spoof IP

This will need to be more fleshed out but I had some time to write up a compose file that will spoof our IP when using a docker container. There are some services with free WireGuard credentials, ProtonVPN is a good one

Here's an example of docker-compose.yml You will need to mount the config volume (alternatively you can pass the config through env variables or use wg-quick to build the config)

---
version: "2.1"
services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /path/to/config:/config
      - /lib/modules:/lib/modules
    ports:
      - 8080:8080
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped
  script:
    image: bot-image
    container_name: bot
    network_mode: service:wireguard
    environment:
      - DISPLAY=host.docker.internal:0

Create a folder called /config/ in script-template, then create your wg0.conf that contains your WireGuard credentials
Here's an example of that file

[Interface]
# VPN Accelerator = off
PrivateKey = myprivatekey
Address = 10.2.0.2/32
DNS = 10.2.0.1
PostUp = DROUTE=$(ip route | grep default | awk '{print $3}'); HOMENET=192.168.0.0/16; HOMENET2=10.0.0.0/8; HOMENET3=172.16.0.0/12; ip route add $HOMENET3 via $DROUTE;ip route add $HOMENET2 via $DROUTE; ip route add $HOMENET via $DROUTE;iptables -I OUTPUT -d $HOMENET -j ACCEPT;iptables -A OUTPUT -d $HOMENET2 -j ACCEPT; iptables -A OUTPUT -d $HOMENET3 -j ACCEPT;  iptables -A OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
PreDown = HOMENET=192.168.0.0/16; HOMENET2=10.0.0.0/8; HOMENET3=172.16.0.0/12; ip route del $HOMENET3 via $DROUTE;ip route del $HOMENET2 via $DROUTE; ip route del $HOMENET via $DROUTE; iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT; iptables -D OUTPUT -d $HOMENET -j ACCEPT; iptables -D OUTPUT -d $HOMENET2 -j ACCEPT; iptables -D OUTPUT -d $HOMENET3 -j ACCEPT

[Peer]
# US-FREE#16 - this is ProtonVPN's Free US WireGuard server
PublicKey = mypublickey
AllowedIPs = 0.0.0.0/0
Endpoint = 37.19.200.17:51820

That should be all you need to have your IP spoofed in the bot docker container.

[TODO] Gradle Run Tasks

A Gradle run task would likely not receive the obnoxious pop-up that appears every run in the run configurations.

[BUG] Gradle is causing some runtime issues again.

Gradle is likely misconfigured and needs to be reviewed to fix runtime errors preventing the script-template from seamlessly being launched.

[TODO] Add Instructions for Hot Swapping/Reloading

Going to be adding hot swapping/reloading scripts to the client so documentation for this will be needed eventually

[BUG] There might be an issue in the ScriptPanel

There is an error when we go to run the program after building our artifact in the GService directory.
This will need to be fixed in the RSB API