Launching a Bot With Custom Settings

Introduction

In some cases, your bot may benefit from a further-customized RuneLite plugin configuration. For instance, if your bot requires numerous objects on screen to be highlighted various colors, it is not ideal to force the user to tag them manually each time they use the bot. This tutorial will show you how to add a launch game button to your bot's control panel that will fire-up the game with specific settings.

Prerequisites

This tutorial assumes you already have a bot script to work with. This tutorial is relevant for any RuneLite-based game.

I will refer to your bot script file as <bot>, and the game it's meant for as <game>.

Launching a Bot With Custom Settings

NOTE: If your RuneLite version is 1.9.11.2 or higher, know that RuneLite uses a new feature for managing plugin configurations called the Profile Manager. At the time of writing this document, OSRS is likely the only game that uses this feature. Please be aware that the instructions below will specify if you need to take any special steps to use the Profile Manager.

Step 1: Launch RuneLite with Default OSBC Settings

1. Launch OS Bot COLOR.
2. Navigate to your game's Home View via the sidebar in the app.
3. Launch RuneLite via the Launch <game> button on the UI.

Step 2: Configure Your RuneLite Plugins

NOTE: If your game uses the Profile Manager, you can access it from the menu bar (see image below). If OSBC launched RuneLite successfully, you should already have a temp profile selected.

1. Manually configure the RuneLite plugins to your liking via the RuneLite interface.
   1. Sometimes you need to stay logged in for a few minutes for the changes to take effect.
   2. It is wise to not change object/tile/npc tagging plugin properties, such as their width and feathering. This may negatively affect OSBC's ability to locate outlined objects. You can safely adjust their colors though if you intend to pre-tag objects with specific colors.
2. (Profile Manager only) Once you are happy with your settings, open the temp profile in the Profile Manager menu, and select Export profile. Save it to a temporary location you can easily access.
3. (Legacy RuneLite only) Log out, and close RuneLite. Your custom settings have been saved to src/runelite_settings/temp.properties in the OSBC filesystem. You can either leave this file here for now, or move it to an easier-to-access location.

Step 3: Organize Your Bot Files

Next, we are going to bundle your bot file along with its custom settings file into a single folder. This will make it neat and tidy. Additionally, it'll be easier to distribute your bot to others if you decide to do so.

1. In src/model/<game>/ create a new folder where your bot file & settings file will live. Give it a name relevant to <bot>.
   1. E.g., if my bot is called "OSRSCombat", I might name it's parent folder "Combat".
2. Move your bot file into this new folder.
3. In src/model/<game>/__init__.py, adjust the reference to your bot such that it points to the new location (from .<folder_filename>.<bot_filename> import <bot>).
4. Move the plugin config (.properties) file from Step 2 into the new folder. Rename it to custom_settings.properties.
5. Edit this file, removing any lines that contain rsprofile. These lines may contain your account name, so it is best to remove them if you plan to distribute your bot.

Step 4: Add a Launch Button to Your Bot's Control Panel

1. In src/model/<game>/<bot>.py, import the game_launcher utility, and pathlib.

import utilities.game_launcher as launcher
import pathlib

2. Make your bot inherit from launcher.Launchable by adding it within the parentheses in your class declaration.

# Note: your bot class may inherit from a different base class (i.e., not OSRSBot).
class BotName(OSRSBot, launcher.Launchable):

3. Add a launch_game method to your bot. I like to put it above the main_loop() method. It must be named launch_game exactly.

def launch_game(self):
    pass

Step 5: Make it Work

1. In the launch_game method, identify the path to your custom settings file and save it to some variable.

def launch_game(self):
    settings = pathlib.Path(__file__).parent.joinpath("custom_settings.properties")

The previous line can be read as: "Get the path to the current file (__file__, i.e., your script), then get the parent directory (i.e., its containing folder), then add custom_settings.properties to the end of that path."

2. Call launcher.launch_runelite(). Carefully specify each required argument.

If using Profile Manager

def launch_game(self):
    settings = pathlib.Path(__file__).parent.joinpath("custom_settings.properties")
    launcher.launch_runelite(
        properties_path=settings,
        game_title=self.game_title,
        use_profile_manager=True,
        profile_name="OSBCCombat",  # Supply a name if you'd like to save it to PM permanently
        callback=self.log_msg,
    )

If using Legacy RuneLite

def launch_game(self):
    settings = pathlib.Path(__file__).parent.joinpath("custom_settings.properties")
    launcher.launch_runelite(
        properties_path=settings,
        game_title=self.game_title,
        use_profile_manager=False,
        callback=self.log_msg,
    )

3. (Optional) If it is important that the user does not have an instance of RuneLite already running, add this to the top of your launch_game method:

def launch_game(self):
    # If playing RSPS, change `RuneLite` to the name of your game
    if launcher.is_program_running("RuneLite"):
        self.log_msg("RuneLite is already running. Please close it and try again.")
        return
    ...
    # Other code below...

Step 6: Test Your Bot

1. Close RuneLite if it's running.
2. Launch OSBC.
3. Navigate to your game's Home View via the sidebar.
   1. Select skip to unlock the scripts in the sidebar.
4. Select your bot from the sidebar.
5. The bot should now have a Launch button in its control panel. It is disabled until you've configured your bot's options.
6. Launch RuneLite via the Launch button.

Since the Launch button waits for your bot to be configured, you have an opportunity to further modify your custom settings file before launching RuneLite. For instance, the OSRSCombat bot's option menu allows users to identify what items should be looted, and then the settings file is modified automatically to highlight those items. See the OSRSCombat bot's source code for an example of how to do this.