A Discord bot for Dungeons & Dragons players which aims to provide commands using modern Discord features.
Powered by 5e.tools for up-to-date 5e data based on the Lenny D&D data repository.
- Dice Roll Commands: Easily roll dice with flexible expressions, such as
2d6,1d20+6, or1d8+4+2d6. - D&D Data Lookup: Look up D&D data and get detailed information about them directly in Discord, powered by 5e.tools.
- D&D Homebrew data: Allows servers to add and manage their own homebrew data for spells, items, creatures, and more.
- Customizable Color Embeds: Customize the colors of your dice roll embeds for better visual appeal and easy identification, auto-generated if not specified.
- Character Stat Rolling: Automatically roll and generate D&D character stats.
- Voice Chat Sound Effects: The bot can join voice channels to play sound effects for your rolls, including special sounds for natural 1s and 20s, as well as effects for attacks, damage, and fire.
- Token-Image Generation - Generate a 5etools-style token from an image or image-url for your characters or custom creatures.
- Initiative Tracking - Track initiatives for combat easily, with easy-to-use buttons for players and dungeon masters.
- Discord Utilities - Various utility commands to help with planning sessions, generating timestamps, and playing sound effects.
To get the bot running and usable for your own Discord servers, follow these steps:
Clone the repository and its submodules using the following command:
git clone https://github.com/DaFrankort/lenny-dnd-bot.git
cd lenny-dnd-bot
git submodule update --initOnce cloned, navigate to the repository directory and install the required dependencies:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt --forceCopy .env.example and rename it to .env, make sure it's in the project root folder.
Add your discord-bot token and optionally add a guild ID:
DISCORD_BOT_TOKEN="your-token-here"
GUILD_ID=0
- If you don't have a bot token, you can create one by following Discord's bot creation guide.
- To get a guild ID, enable developer mode on discord.
Afterwards you can right click on your server of choice and select
Copy Server ID. TheGUILD_IDfield is optional and mainly serves to prioritize syncing with a certain server (for development purposes).
If you don't wish for the bot to play immersive sound effects on dice rolls and initiative rolls, you can skip this step.
For voice chat capabilities FFMPEG is required. You can follow this tutorial for help with installing it.
To start the bot, simply run the following command:
python lennyYou can add the following arguments if you wish:
--verbose, --no-verbose- Run with or without debug-logging.--voice, --no-voice- Run with or without voice-chat functionalities.
The bot should now be online, don't forget to invite it to your servers!
Once the bot is added to your server, the commands below are available. When setting up the bot, the config commands should be used first to set the game master roles.
Configure bot-specific settings for your server.
/config permissions- Set the roles which are allowed to configure the bot further. Only the server admin is allowed to use this command./config sources <content> [search]- Enable or disable which sources will be used during the/searchcommands. Only users with the permission roles can change the sources. You can filter content between official & partnered, and also quick-search to find the page a specific source is on.
Roll D&D dice using dice-expressions (e.g. 2d6 / 1d20+2).
/roll <dice-expression> [advantage] [reason]– Roll a single dice expression, optionally specify a reason for the roll (e.g. Acrobatics) and the advantage on the roll./d20- Rolls a basic 1d20 without any modifiers./multiroll <dice-expression> <amount> [advantage] [reason]– Roll a dice expression multiple times, shows the individual results as well as the total./tableroll <table-name> <roll-result>- Rolls on a D&D table from 5e.tools, showing the result and it's description./distribution <expression> [advantage] [min-to-beat]- Creates a graph showing likeliness of your dice expression's roll results./average ac <hit> <damage> [min_ac] [max_ac] [crit_min] [miss_damage]- Calculate the average damage of an attack based on hit chance and critical range against various armor classes./average dc <dc> <damage> <miss_damage> [min_mod] [max_mod]- Calculate the average damage of a save-based attack based on save DC against various saving throw modifiers.
Look up various D&D data from 5e.tools.
/search spell <spell-name>– Look up a D&D Spell (e.g. Fireball)./search item <item-name>- Look up a D&D Item (e.g. Dagger)./search condition <condition-name>- Look up a D&D Condition (e.g. Blinded)./search creature <creature-name>– Look up a D&D Creature (e.g. Orc)./search class <class-name> [level] [subclass]– Look up a D&D Class (e.g. Wizard)./search rule <rule-name>– Look up a D&D Rule (e.g. Saving Throw)./search action <action-name>– Look up a D&D Action (e.g. Dash)./search feat <feat-name>– Look up a D&D Feat (e.g. Savage Attacker)./search language <language-name>- Look up a D&D Language (e.g. Common)./search background <background-name>- Look up a D&D Background (e.g. Soldier)./search table <table-name>- Look up a D&D Table (e.g. Wild Magic Surge)./search species <species-name>- Look up a D&D Species (e.g. Human)./search vehicle <vehicle-name>- Look up a D&D Vehicle (e.g. Galley)./search object <object-name>- Look up a D&D Object (e.g. Ballista)./search hazard <hazard-name>- Look up a D&D Trap or Hazard (e.g. Spiked Pit)./search deity <deity-name>- Look up a D&D Deity (e.g. Bahamut)./search all <query>- Look for many related results regarding D&D data. Example:/search all firewould return any data with 'fire' in the name.
You can mark certain D&D data entries as your favorite, making it easy to quickly look them up again later.
/favorites add <entry>- Mark a D&D data entry as your favorite./favorites remove <entry>- Remove a D&D data entry from your favorites./favorites view [type_filter]- List all your favorite D&D data entries.
You can also right-click on an embed and select "Add to Favorites" to manage your favorites quickly.
Manage your server's homebrew D&D data for spells, items, creatures, and more. For entry deletion or editing you will need to either be the original creator of the entry, have config permissions or have the Manage Messages permission for the server. Entries can be added straight from a markdown file, any formatting will be converted to match Discord's formatting. Additionally this handles some formatting from Obsidian (such as tables and file-links).
/homebrew add [md_file]- Add a new homebrew entry, can be filled directly from a markdown file./homebrew edit <entry>- Edit an existing homebrew entry./homebrew delete <entry>- Delete an existing homebrew entry./homebrew list [filter]- List all homebrew entries in the server, can be filtered by D&D type./homebrew search <entry>- Show details of a specific homebrew entry by its ID.
/stats roll– Automatically roll stats for a new character's ability scores, using the 4d6 drop lowest method. Also generates a radar-graph to visualize the stats./stats buy- Generate stats using the point-buy method, where you have 27 points to spend on your ability scores. Also generates a radar-graph to visualize the stats./stats visualize <str> <dex> <con> <int> <wis> <cha>– Visualizes ability scores in a radar-graph./namegen [race] [gender]- Generate a random name, race and/or gender can be specified but will default to random./charactergen [gender] [species] [char_class]- Generates a character with name, class, species, background and stats. Ensures that the build that is generated is somewhat optimal for your class; automatically selecting fitting backgrounds and assigning stats optimally. Preferred gender, species or class can be provided.
Create 5e.tools-style token images quickly, like this example.
Optionally adjust the frame's color with hue-shift (default: gold), control image alignment using h_alignment and v_alignment (default: center), and variants for generating up to 10 numbered variants of your tokens.
Additionally supports gif images as input, which will be preserved in the output tokens.
/tokengen file <image-attachment> [hue-shift] [background_type] [custom_background] [h_alignment] [v_alignment] [variants]- Generate a token from an image attachment./tokengen url <image-url> [hue-shift] [background_type] [custom_background] [h_alignment] [v_alignment] [variants]- Generate a token from an image URL.
/plansession <in_weeks> [poll_duration]- Quickly generates a poll where players can vote for days they're available within a given week./playsound- Allows users to play a sound effect from a file through the bot, allowing for more atmospheric role-play!/timestamp relative [seconds] [minutes] [hours] [days] [weeks]- Generates a timestamp relative from when you used this command./timestamp date <time> <timezone> [date]- Generates all possible timestamps for a specific date & time. Date defaults to the current day.
Commands that resemble user-actions are highlighted with colors that are unique per user. This makes it easy to discern different user's actions. By default the user's color is automatically generated based on their display name. Users can adjust their colors using following commands:
/color set base <color>- Set your color from a selection of basic colors./color set hex <hex_color>- Set your color using a hexadecimal color value./color set rgb <r> <g> <b>- Set your color using a RGB value./color set image [image] [style]- Generates color suggestions based on your profile picture.[image]- You can optionally upload a different image instead.[style]- Apply a different color-selection algorithm, changing the overall mood of the generated colors.
/color clear- Clears your set color and enforces use of an auto-generated color./color show- Shows the color you've set to everyone.
Command to help track initiatives for combat. Names are enforced to be unique and will overwrite each other if specified twice.
/initiative- Summons an embed with buttons to track initiative. Available buttons are as follows:Roll- Rolls initiative for a user, can also roll for a creature if a name is specified.Set- Set an initiative to a specific value, handy to rectify mistakes or if you want precise control over certain initiatives.Delete Roll- Remove a single user or creature from the initiative tracker. Removes user's initiative by default.Bulk- Adds creature initiatives in bulk, making it easy for a DM to add a group of creatures at once. These are numbered automatically for easy tracking.Lock- Disables all the buttons, to avoid accidental adjustments.Clear Rolls- Clears all stored initiatives in the server, used after a battle.