Design
Updated to v0.2.3-alpha
OSBC is designed using the Model-View-Controller (MVC) pattern. This pattern is used to separate the application's logic from its presentation. Models, in this application, refer to bots (their properties, functions, etc.). Views refer to the user interface (the buttons, text, etc.). Communication between these two layers is handled by a single controller instance.
The UI is divided into two main sections: the left-side panel, and right-side frame. The words "panel" and "frame" may be used interchangeably.
The left side is used for navigation throughout the application, and the right side is for displaying information and controlling bots.
OSBC takes a "nearly-single file" approach to UI. This means that the components that make up the UI are divided into multiple files, but all of the files are imported into a single file, OSBC.py. This is done to make it easier to navigate the codebase.
The UI is divided into the following files:
-
OSBC.py- The main file that imports all of the other UI files. The left-side navigation panel is also defined here. - Home Views - Views that serve as an introduction to the selected game and allow the user to perform initial client configuration.
-
bot_view.py- The view that displays the bot's information and controls. It consists of two components:info_frame.pyoutput_log_frame.py
One special UI component is the Options Builder. This is a utility that builds a dynamic window for collecting user input on how a bot should operate. It is defined in ./src/utilities/options_builder.py. It allows for a dynamic UI to be built at runtime.
Many of these UI files should remain untouched by developers adding their own bots. It helps to understand how they function, but in practice, developers will only need to perform minor edits in the OSBC.py file and Home Views should they be adding support for a new private server.
In OSBC, bots are represented in code as classes in order to make them more modular, reusable, and organized. No matter what game a bot is being made for (whether that be OSRS or a private server), they all share common qualities; for example, all bots have a name, a description, a current status, a worker thread, and the ability to start and stop itself. For this reason, OSBC uses an abstract base class, Bot, to represent all bots. This class is defined in bot.py.
Additionally, some RuneScape-based games offer RuneLite support, which allows for enhanced botting capabilities. Therefore, a further abstraction is made in the form of the abstract RuneLiteBot class, which inherits from Bot. This class is defined in runelite_bot.py. This class defines properties and functionality that are common to all RuneLite bots.
While not necessary, it is wise for each game (OSRS or private server) to have its own base class that inherits from Bot or RuneLiteBot. This class should define properties and functionality that is specific to that game. For example, the OSNRBot (Near Reality RSPS) class inherits from RuneLiteBot and defines a function that allows the user to teleport to any location using the game's custom teleport interface - a feature that is unique to this game only. Future bots for this game can be made by inheriting from OSNRBot so that they can take advantage of this functionality as well.
OSBC also contains a number of utilities that are used by bots. Most utilities are decoupled from the bot classes, so they may be imported on a script-by-script basis when they are needed. Some utilities include:
-
color.py- Contains a class for representing colors in RGB format, functions for color manipulation in images, and predefined colors that are often found in RuneScape. -
debug.py- Contains functions for debugging and logging. -
geometry.py- Contains data structures for representing points, rectangles, and irregular polygons (outlined RuneLite objects). This allows developers to easily access the coordinates of these objects on screen. -
imagesearch.py- Contains custom functions for locating images on screen. -
mouse.py- Contains functions for moving the mouse and clicking on the game client in a human-like manner. -
ocr.py- Contains custom functions for performing optical character recognition on OSRS fonts. -
options_builder.py- Contains functions for building a dynamic UI for collecting user input for setting bot options. -
random_util.py- Contains a collection of functions for sophisticated random number generation. -
record_mouse.py- Allows you to record a sequence of clicks and screenshots for each. -
runelite_cv.py- Contains functions for performing computer vision specific to RuneLite features (E.g., object detection). -
window.py- Used at runtime for finding the game client window and import UI positions.
Because many of the computer vision functions are generic and verbose, they can be unintuitive to use on their own. It's likely they need to be used in a combined manner in order to arrive at the desired result. Therefore, it's recommended that computer vision function calls be encapsulated in user-intuitive functions. For instance, if I were to write a combat bot for a RuneLite game, we would require this bot to click on blue-outlined NPCs. It is much smarter to write a single function within the bot's parent class called get_nearest_npc() that makes use of the computer vision utility functions rather than using them directly in the bot's code. In other words, if you're isolating colors and finding contours in your bot's main loop using cv utilities, you're probably doing it wrong. Make things easier by writing reusable, self-explanatory functions within parent classes. See runelite_bot.py for examples.
OSBC uses a single controller instance to handle communication between the model and the view. This controller is defined in bot_controller.py. It is responsible for notifying bots when a user has requested that they start or stop, and it is responsible for notifying the view when a bot's internal status has changed. It also handles requests to update the view from the model (E.g., when a bot wants to log a message to the output log, it asks the controller to do so).
As mentioned, only a single instance of the controller exists at runtime. This is necessary as the UI is a single-page design - so instead of each bot having its own dedicated view, they all share the same dynamic view. When a user selects a bot from the navigation panel, the UI will be cleared to a default state, the controller will redirect its model pointer to the bot in question, and the view will be updated according to that bot's properties.
This file can remain untouched by the developer. It is complete and fully functional for all future bots.