Repository files navigation

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

You can join the Avrae Development Discordhere, and invite Avrae to your own Discordserverhere!

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

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

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

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 furtherstreamline combat.

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

Check outthe docs and theAlias Workshop!

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.

Check outREADME-docker.md.

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

Follow steps 1-7 in theFor Bots: Using Service Account portion. Rename the JSONavrae-google.json and put it inthe project root.

Python Packages

We recommend using aVirtual Environment for Avrae development to preventpackage 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 --versionPython 3.X.X(venv) $ pip --versionpip 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 theavrae-automation-common anddraconic dependencies from your local filesystemrather 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.

Discord Bot Token

To create a Discord bot user, go to theDiscord Developer Portal.

• New Application, give it a cool name,Create.
• Bot >Add Bot.
• (Optional but recommended): Switch offPublic Bot so only you can add this bot to servers.
• Scroll down toPrivileged Gateway Intents, and enable the switches to the right ofServer Members IntentandMessage Content Intent.
• Click to Reveal Token, this is yourDISCORD_BOT_TOKEN.

Testing Env Var

TheTESTING env var, if present, enables/disables the following:

• Dicecloud Client: Meteor debug logs enabled
• cogs.publicity: Discord Bot List update disabled
• config:ENVIRONMENT set todevelopment by default if not manually set
• Discord Application Commands: enables command sync debug logs and command testing guilds

(venv) $ python dbot.pytest

  {"version":"0.2.0","configurations": [      {"name":"Run Avrae","type":"python","request":"launch","program":"dbot.py","console":"integratedTerminal","env": {"DISCORD_BOT_TOKEN":"","DISCORD_OWNER_USER_ID":"","DICECLOUD_USER":"","DICECLOUD_PASS":"","DICECLOUD_TOKEN":"","DICECLOUDV2_USER":"","DICECLOUDV2_PASS":"","MONGO_URL":"","REDIS_URL":"","ENVIRONMENT":"","DDB_AUTH_SECRET":"","DYNAMO_REGION":"","DYNAMO_ENTITLEMENTS_TABLE":"","DDB_AUTH_SERVICE_URL":"","AWS_ACCESS_KEY_ID":"","AWS_SECRET_ACCESS_KEY":"","DDB_AUTH_WATERDEEP_SECRET":"","CHARACTER_COMPUTATION_ENDPOINT":"","DDB_WATERDEEP_URL":"","DDB_GAMELOG_ENDPOINT":"","DDB_CHARACTER_SERVICE_URL":"","DDB_SCDS_SERVICE_URL":"","LAUNCHDARKLY_SDK_KEY":""        }      }    ]  }

This repo contains a pytest test suite that mocks a number of interactions between Avrae and the Discord API, and runsend-to-end tests between user input, bot output, and database state.

These tests can be found intests/.

(venv) $ pip install -r tests/requirements.txt

Tests can either be run using Docker Compose, or manually.

Docker

docker-compose -f docker-compose.ci.yml -p avrae up -d --builddocker logs -f avrae_tests_1

Once tests complete, it is recommended to clean up the containers withdocker-compose down.

Manually

(venv) $ TESTING=1 pytest tests/

In either case, you should setNO_DICECLOUD=1.

Avrae uses Sphinx to generate documentation for the Aliasing API and Automation Engine. The source for thisdocumentation can be found indocs/.

By default, each push tomaster will trigger a new build of the docs athttps://avrae.readthedocs.io/en/latest/.

You can also build the docs manually:

# install dependencies(venv) $cd docs(venv) $ pip install -r requirements.txt# build and open browser(venv) $ make preview# build(venv) $ make html

Avrae usesBlack to format and lint its Python code.Black is automatically run on every commit via pre-commit hook, and takes its configuration options from thepyproject.toml file.

The pre-commit hook is installed by by runningpre-commit install from the repo root.The hook's configuration is governed by the.pre-commit-config.yaml file.

In order to runpre-commit orblack, they must be installed.These dependencies are contained within thetest/requirements.txt file, and can be installed like so:

(venv) $ pip install -r test/requirements.txt