Brawl Box

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.

Tech Stack

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.

Environment Setup

Brawl Box requires a modern version of Python. Currently, Python 3.10 is used in production.

Firstly, clone the source code and install the uv 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 git@github.com:nielsvv08/brawlbox.git


pip install uv

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

cd brawlbox

uv sync

Configuration

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.

Required

• 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.

Optional

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

Command Registry

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.

Startup

Finally, start the bot by running this command.

uv run uvicorn app:app

The production version is managed by pm2, whose configuration values are collected in the pm2.yml file.

Contributing

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.