# RANDSUM Discord Dice Bot — D&D, Blades, PbtA & More

See the [Discord Bot landing page](https://randsum.dev/discord) for screenshots and quick setup.

The **RANDSUM Discord Bot** is a Discord application for rolling dice in chat. Built with [discord.js](https://discord.js.org) and Bun, it provides detailed roll breakdowns and full support for all RANDSUM game packages.

## Add to your server

Add the bot to any Discord server with one click:

[Add RANDSUM to Discord](https://discord.com/oauth2/authorize?client_id=1290434147159904276&permissions=274877906944&scope=bot%20applications.commands)

No configuration is required after adding.

## Commands

### `/roll`

The core dice rolling command. Supports the full RANDSUM dice notation with detailed breakdowns showing individual die results, modifiers, and final totals.

<CodeExample lang="bash" code={`/roll notation:4d6L+2
/roll notation:2d20H
/roll notation:3d8+5`} />

### `/blades`

Roll Blades in the Dark action rolls. Takes the number of dice in your pool and returns the outcome (critical, success, partial, or failure) with color-coded embeds.

<CodeExample lang="bash" code={`/blades dice:3
/blades dice:2
/blades dice:0   # Desperate position (rolls 2d6, takes lowest)`} />

### `/fifth`

Roll D&D 5th Edition dice (1d20 + modifier). Supports advantage and disadvantage. Natural 20 results display in gold, natural 1 in crimson — visible at a glance.

<CodeExample lang="bash" code={`/fifth modifier:5
/fifth modifier:3 rolling_with:Advantage
/fifth rolling_with:Disadvantage
/fifth   # Straight 1d20`} />

### `/dh`

Roll Daggerheart mechanics with hope and fear dice. Supports modifiers, advantage/disadvantage, and amplification of hope or fear dice.

<CodeExample lang="bash" code={`/dh modifier:5 rolling_with:Advantage
/dh modifier:3 rolling_with:Disadvantage
/dh amplify_hope:true amplify_fear:false
/dh modifier:2`} />

### `/root`

Roll Root RPG mechanics. Rolls 2d6 with an optional modifier and returns the outcome (Strong Hit, Weak Hit, or Miss).

<CodeExample lang="bash" code={`/root modifier:2
/root modifier:-1
/root   # No modifier`} />

### `/salvageunion`

Salvage Union rolls have moved. This command points you to [SURef](https://salvageunion.io/discord), the official bot from salvageunion.io, which rolls every Salvage Union table and looks up any chassis, system, module, or piece of equipment. It replaces the old `/su` command, which no longer exists.

<CodeExample lang="bash" code={`/salvageunion`} />

### `/pbta`

Roll Powered by the Apocalypse moves (2d6 + stat). Supports forward, ongoing bonuses, and advantage/disadvantage.

<CodeExample lang="bash" code={`/pbta stat:2
/pbta stat:1 forward:1
/pbta stat:3 rolling_with:Advantage
/pbta stat:0 ongoing:1`} />

### `/notation`

Display a reference guide for RANDSUM dice notation. Shows all available modifiers, syntax, and examples.

<CodeExample lang="bash" code={`/notation`} />

### `/help`

Lists all available RANDSUM slash commands with descriptions.

## Game Support

The following game packages have dedicated slash commands:

- **@randsum/games/fifth** -- `/fifth` for D&D 5th Edition rolls
- **@randsum/games/blades** -- `/blades` for Blades in the Dark action rolls
- **@randsum/games/daggerheart** -- `/dh` for Daggerheart hope and fear dice
- **@randsum/games/pbta** -- `/pbta` for Powered by the Apocalypse moves
- **@randsum/games/root-rpg** -- `/root` for Root RPG mechanics

Salvage Union is served by the [SURef bot](https://salvageunion.io/discord) instead; `/salvageunion` points there. The `@randsum/games/salvageunion` package is still published and usable in your own code.

## Features

- **Detailed breakdowns** -- Shows individual die results, modifiers, and step-by-step calculations
- **Full notation support** -- All RANDSUM dice notation features (drop, reroll, explode, etc.)
- **Game-specific commands** -- Dedicated commands for each supported RPG system
- **Color-coded embeds** -- Results are visually distinct by outcome type

## Example Results

See what RANDSUM bot results look like in practice.

![/roll notation:10d20 — rolled a 100](https://randsum.dev/discord-ss-roll-10d20.png)

![/dh modifier:3 — Daggerheart Critical Hope](https://randsum.dev/discord-ss-dh-critical.png)

![/roll notation:2d12+1 result](https://randsum.dev/discord-ss-roll-2d12.png)

## Self-Hosted Setup

If you prefer to run the bot yourself:

<CodeExample lang="bash" code={`# From the monorepo root
cd apps/discord-bot

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env

# Deploy commands
bun run deploy-commands

# Run the bot
bun run dev`} />

For detailed setup instructions, see the [Discord Bot source on GitHub](https://github.com/RANDSUM/randsum/tree/main/apps/discord-bot).

## Links

- [Add to Discord](https://discord.com/oauth2/authorize?client_id=1290434147159904276&permissions=274877906944&scope=bot%20applications.commands)
- [Source code](https://github.com/RANDSUM/randsum/tree/main/apps/discord-bot)
- [discord.js documentation](https://discord.js.org)