This repository contains the source code for Brawl Box — the loot box simulator for Brawl Stars.

The bot is designed with Discord's latest features in mind, like slash commands and message components.

Brawl Box is written in Python. The bot benefits from the custom-designed Discourtesy framework to handle interactions, which utilises a minimal Starlette web server internally. The various data storage happens on an external database, by using one or more MongoDB clusters.

Brawl Box requires Python 3.10 or higher.

Firstly, clone the source code and install the Poetry dependency manager.

# using the customary way with HTTP
git clone https://github.com/nielsvv08/brawlbox.git

# or using the more secure SSH option
git clone [email protected]:nielsvv08/brawlbox.git


pip install poetry

Then, move to the correct directory in order to create a virtual environment and install the dependencies by running these two commands.

cd brawlbox

poetry install

The bot can be configured by a few environment variables. Rename the .env.example file to .env and fill out the values accordingly. This file includes two example configurations with randomised or invalidated values.

• application_id, token, public_key: the respective information found in Discord's developer portal.
• mongo_uris: the URI or URIs for the MongoDB cluster. When mulitple URIs are provided here, they should be separated by a comma and a space.

• colour: the main colour theme throughout the bot as an integer.

In order for commands to show up in the selection menu, they should be registred first. This is accomplished by sending a PUT request with the command objects as JSON data to the https://discord.com/api/v10/applications/{application_id}/commands endpoint. The specific configuration for Brawl Box can be found in the commands.json file.

Finally, start the bot by running this command.

poetry run uvicorn app:app

Before contributing to Brawl Box, make sure to read through the contribution guidelines.

There is a #development channel in the support server at https://discord.gg/bXQaeFM dedicated to communication about the development process.

This project is licensed under the terms of the AGPL-3.0 license.