Avrae Discord Bot

Avrae is a Discord bot designed to help you and your friends play D&D online.

You can join the Avrae Development Discord here, and invite Avrae to your own Discord server here!

Key Features

Advanced Dice Roller

With a custom dice parser, Avrae is one of the most advanced dice rollers on Discord, capable of supporting pretty much every type of roll needed to play D&D. Advantage, disadvantage, and crits are built in, you can keep, drop, or reroll dice as needed, dice can explode, and dice can be bounded.

Want to use the dice roller in your own code? Check out the code!

Character Sheet Integration

Avrae can read character sheets from D&D Beyond, Dicecloud, or a Google Sheet, automatically generating macros to roll attacks, ability checks, and saving throws. A player can then simply use a command to make a check, save, attack, or cast, and all necessary rolls will be resolved automatically.

Initiative Tracking

The initiative tracker is a fast way to track combat in a text channel. It supports automatic combatant sorting, HP, AC, resistance, and status effect tracking, and integration with the character sheet manager and 5e content to further streamline combat.

Moddability

Have a feature in mind that isn't already in Avrae? Avrae provides a fully-featured modding API to write your own commands, and a place to share them with the community!

Check out the docs and the Alias Workshop!

Contributing

There are a few options to run Avrae locally. Docker is easier to get started with with less managment of dependencies, but slower and more resource-intensive.

Using Docker (Recommended)

Check out README-docker.md.

Building Manually

Dependencies

Services/OS

• Ubuntu 18.04+ or other UNIX system (Windows is compatible but untested)
• Redis Server 4+ (https://redis.io/download)
• MongoDB Community Server 3.6+ (https://www.mongodb.com/try/download/community)
• Python 3.8+ (https://www.python.org/downloads/)

Support Files

You'll need to create a Google Drive Service Account. You can find instructions on how to do this here.

Follow steps 1-7 in the For Bots: Using Service Account portion. Rename the JSON avrae-google.json and put it in the project root.

Python Packages

We recommend using a Virtual Environment for Avrae development to prevent package installs from polluting the global Python install. You can create and active a virtual environment by running:

$ python3 --version  # to ensure that you are creating a venv from the right python version
$ python3 -m venv venv
$ source venv/bin/activate
# if the venv was set up correctly, you should see (venv) before your username in the terminal
# run these commands to check the installed version and path
(venv) $ python --version
Python 3.X.X
(venv) $ pip --version
pip X.Y.Z from (project root)/venv/lib/python3.X/site-packages/pip (python 3.X)

To install the dependencies, run:

(venv) $ pip install -r requirements.txt

Optional - You can install the avrae-automation-common and draconic dependencies from your local filesystem rather than pip+git, to make working on depended libraries in parallel easier:

(venv) $ pip install /path/to/automation-common -e
(venv) $ pip install /path/to/draconic -e

Any changes to the library will immediately be picked up in avrae without requiring a reinstall of the library.

Environment Variables

| Name | Description | Used For | Set By (dev) | Set By (prod) | Required? | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|----------------------|-----------------------------------|-----------------| | DISCORD_BOT_TOKEN | The bot token used to authenticate to the Discord API. See "Discord Bot Token", below. | Connecting to the Discord API | you | AWS Secrets Manager via Terraform | yes | | TESTING | Whether the bot is running in a dev environment. See "Testing Env Var", below. Also set if test arg supplied in CLI. | Enabling certain debug logs | you | N/A | no | | ENVIRONMENT | The environment the bot is running in. Defaults to development if TESTING is set, or production otherwise. | Logs (e.g. Datadog) | set to development | Terraform | yes | | GIT_COMMIT_SHA | The commit SHA of the running deploy. | Cluster coordination key | N/A | Docker via GH Actions | prod only | | NUM_CLUSTERS | The number of clusters (ECS tasks) Avrae is running across. Defaults to 1. | Cluster coordination | N/A | Terraform | prod only | | NUM_SHARDS | An explicit override for the number of shards to run across all shards. Defaults to dynamic value from Discord. | Cluster coordination | N/A | Terraform (nightly/stg) | no | | RELOAD_INTERVAL | An interval to automatically reload gamedata at, in seconds. Defaults to 0. This should be set to 0. | Loading gamedata | N/A | N/A | no | | ECS_CONTAINER_METADATA_URI | https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-metadata-endpoint-v3-fargate.html | Cluster coordination | N/A | AWS Fargate | prod only | | MONSTER_TOKEN_ENDPOINT | The base URL that monster token paths defined in monster gamedata are relative to. | !token | N/A | Terraform | prod only | | DDB_MEDIA_S3_BUCKET_DOMAIN | The S3 bucket domain for DDB media assets, such as character avatars. | !token | N/A | Terraform | prod only | | DRACONIC_SIGNATURE_SECRET | The secret used to sign signatures in the Draconic API's signature() function. Defaults to secret. | Aliasing | optional | AWS Secrets Manager via Terraform | prod only | | MONGO_URL | The connection URL used to connect to MongoDB. Defaults to mongodb://localhost:27017. | Connecting to database | you | AWS Secrets Manager via Terraform | yes | | MONGODB_DB_NAME | The name of the database in Mongo to use. Defaults to avrae. | Connecting to database | optional | Terraform | no | | REDIS_URL | The connection URL used to connect to Redis. Defaults to redis://localhost:6379/0. | Connecting to database | you | Terraform | yes | | REDIS_DB_NUM | The database number to use in Redis. Defaults to 0. | Connecting to database | optional | Terraform | no | | DEFAULT_PREFIX | The default command prefix. Defaults to !. | Running commands | optional | Terraform | no | | DD_SERVICE | The name of the service, used for DataDog. If not set, disables DataDog tracing and profiling. |