[!CAUTION] This project is no longer being worked on.

[!TIP] Searching for bot usage documentation? Find information on using the bot on the wiki section of the repo.

[!CAUTION] This bot has not been tested against large numbers of users/servers. Be aware that performance problems might arise under such circumstances.

About

This is BSBot, a python discord bot.

Its use is communicating with the Brawl Stars API and displaying data to the requester in an engaging format.

Additionally, it can save and work with received data to further utilize API data.

BSBot uses discord-interactions-py as it's Discord API wrapper.

Setup

Create and Invite your Bot

Visit Discords Developer Platform and create a bot.

For it to work correctly, visit the "Installation" section and select the bot scope under "Default Install Settings" (while enabling Guild Installation).

Next, check the following permissions:

• Attach Files
• Embed Links
• Send Messages
• Use external Emojis
• Use Slash Commands
• View Channels

Invite your Bot to your server after.

[!IMPORTANT] This server will be an "Admin-Server" with additional privileged commands. Make sure only trusted users are inside this server, or create a server just for the bot instead.

Prerequisites

Software

Python >= 3.10 is required for certain packages.

API

BSBot needs additional resources outside of python related to you. These consist of:

• A Discord Bot Token gotten while creating your bot in Discords Developer Platform
• A Brawl Stars API Token via their Webpage

[!NOTE] The API requires your bot host's IP. If it's IP changes, you have to regenerate your key.

BSBot will notify you either when starting the bot or if a request fails because of this.

• A Sentry DSN for capturing any exceptions that may occur. Create a new project on their site and select Python. Skip the Framework selection and just copy the string shown after dsn=.

[!WARNING] You can use the bot without Sentry's service, this however requires editing BSBot's code.

• An OpenAI API Key for using the /gpt command. You may skip this if you don't intent on using the feature or have no way of obtaining a key.

Custom Emojis

Custom Emojis are an integral part of BSBot by visualizing a lot of data in a more digestible format than simply dumping text everywhere. However, for them to function, they have to be set first.

A bot can use an emoji reference (e.g. <:bingus:1228965645262258207>) to display custom emojis. To get Emoji references:

• Send a message with a Backslash in front of the emoji in a Server the App and Emoji is in.

or

• Press the "Copy Markdown" button of the Emoji in the Emoji Section of your Application

[!NOTE] For a bot to use a custom emoji, the emoji has to be in the same server where the app is in, or has to get added to the application itself. If you are using multiple applications interchangeably, the second option will lead to only one app being able to use assigned Emojis.

On first run setup, every Emoji utilized is asked to be assigned by pasting in the references obtained during Emoji creation.

The list of Emojis (and Examples used) is as follows: | Prompt | Description | Example | | --- | --- | --- | | Power1 - Power11 | Brawler Power Indicators | | | Gadget_OK | Brawler has a Gadget | | | SP_OK | Brawler has a Star Power | | | Gear_OK | Brawler has a Gear | | | Slot_Empty | Brawler does not have this item | | | Bronze, Silver, Gold | Star Icons for Rankings and Star Player | | | Trophy, Bling, PPoint, GadgetIcon, SPIcon, GearIcon, HChargeIcon | Represenation for the in game symbols | | | Error, Warning, Info | Symbols for emphasizing process outcomes | | | Connected | Indicates bot startup | | | Rank<tier> | Rankings for certain functionality | See below |

Here are all rank icons. You can use them by copying their URLs.

| Rank | Icon | | --- | --- | | None | | | E | | | D | | | D+ | | | C- | | | C | | | C+ | | | B- | | | B | | | B+ | | | A- | | | A | | | A+ | | | S- | | | S | | | S+ | | | SS | | | EX | |

Installing

• Clone the repo into the directory of your choice or download from the Releases
  • When downloading from Releases, unpack the archive.
• cd into the directory
• Create a venv with python -m venv .venv
• Activate it
  • .venv\Scripts\activate.bat (Windows)
  • source .venv/bin/activate (Mac/Linux)
• Install the requirements via pip install -r requirements.txt
• Start main.py and follow any instructions that may occur (see next section)

[!TIP] Additionally, set up something like a systemd service! With the correct configuration your bot could be automatically recovered when your bot goes down.

First Run

[!WARNING] On the bot's first run, important files will be generated. Avoid modifying code until the bot has successfully run once to avoid any unexpected behavior.

Upon running main.py for the first time, you will be asked of all the information listed in the prerequisites section.

If you do not posess an OpenAI API Key, skip the prompt by simple entering nothing.

You can assign a name to your Discord bot token. When starting the bot after the setup has concluded, you can save multiple bot tokens to switch between them (for example when testing while a stable version is already running).

You will also be asked for a logging channel and an "Admin-Server". Paste their respective IDs to assign them.

Finally, set all needed Emojis.

After entering everything, your first-run-setup is done!

[!TIP] To start off optimally, use the Wiki Section of this repo to learn all commands that BSBot has to offer.