Whether the current project contains any paid features, is paid only, or is 100% free to use.

This project is free to use and contains no paywalls for core functionality.

Has Paid Features

# Daggerheart Companion Bot

A Discord bot for rolling Daggerheart dice with natural language support, character management, and server configuration.

## Overview

Daggerheart Companion is a pet project Discord bot designed for Daggerheart TTRPG players. Roll 2d12 Hope and Fear dice with advantage/disadvantage, manage character traits, and use natural language commands for gameplay or fun.

Below summary generated by Claude 🤖

## Key Features

### 🎲 Dice Rolling System
- **2d12 Hope & Fear Dice**: Authentic Daggerheart dice mechanics
- **Critical Success Detection**: Automatically detects when both dice match
- **Hope/Fear Tracking**: Results show whether Hope or Fear is dominant
- **Advantage/Disadvantage**: Add or subtract 1d6 from your rolls
- **Reaction Rolls**: Clean rolls without Hope/Fear flavor text
- **Flexible Modifiers**: Add or subtract any bonus to your rolls

### 👤 Character Management
- **Trait System**: Track all 6 Daggerheart traits (Agility, Strength, Finesse, Instinct, Presence, Knowledge)
- **Quick Initialization**: Set all traits and character name in one command
- **Per-Channel Characters**: Maintain different characters in different channels - perfect for multiple campaigns in one server!
- **Automatic Trait Application**: Traits auto-apply when mentioned in natural language rolls
- **Skill Keyword Detection**: Over 30 skill keywords recognized (sprint, perceive, charm, etc.)
- **Character Sheets**: View your complete character sheet with a single command

### 💬 Natural Language Support
- **Intuitive Commands**: Type naturally - "I roll strength with advantage"
- **Keyword Detection**: Recognizes traits, skills, modifiers, and roll types
- **Flexible Syntax**: Works with various phrasings and word orders
- **Abbreviations Supported**: Use "agi", "str", "fin", etc. for quick rolls

### ⚙️ Server Configuration (Admin Only)
- **Channel Whitelisting**: Allow natural language only in specific channels
- **Channel Blacklisting**: Disable natural language in specific channels
- **Global Controls**: Enable/disable natural language server-wide
- **Persistent Settings**: Configuration survives bot restarts
- **Per-Server Settings**: Each server has independent configuration

## Commands

### Slash Commands

#### `/roll` - Roll Daggerheart Dice
Roll 2d12 Hope and Fear dice with optional modifiers.

**Options:**
- `modifier` (optional): Bonus or penalty to add (e.g., 3 or -2)
- `advantage` (optional): Roll with advantage (+1d6)
- `disadvantage` (optional): Roll with disadvantage (-1d6)
- `reaction` (optional): Reaction roll (omits hope/fear flavor)
- `trait` (optional): Character trait to apply (Agility, Strength, etc.)

**Examples:**
```
/roll
/roll modifier:3
/roll advantage:true
/roll modifier:-2 disadvantage:true
/roll trait:Agility modifier:2
```

#### `/character` - Manage Character Traits

**Subcommands:**

**`/character init`** - Initialize all traits at once (recommended!)
```
/character init name:"Aria the Swift" agility:2 strength:3 finesse:1 instinct:0 presence:-1 knowledge:2
```

**`/character set`** - Set a single trait
```
/character set trait:Agility value:2
/character set trait:Strength value:-1
```

**`/character show`** - View your character sheet
```
/character show
```

**`/character name`** - Set your character name
```
/character name charactername:"Kellan the Brave"
```

**`/character reset`** - Reset all traits to 0
```
/character reset
```

#### `/help` - Show Help
Display comprehensive help information about all bot features.

#### `/config` - Server Configuration (Admin Only)

**Subcommands:**

**`/config allow-channel`** - Whitelist a channel for natural language
```
/config allow-channel channel:#dice-rolls
```

**`/config disable-channel`** - Blacklist a channel from natural language
```
/config disable-channel channel:#general
```

**`/config enable-nl`** - Enable natural language everywhere
```
/config enable-nl
```

**`/config disable-nl`** - Disable all natural language (slash commands still work)
```
/config disable-nl
```

**`/config status`** - Show current server configuration
```
/config status
```

### Natural Language Commands

Just type messages in any allowed channel! The bot automatically detects roll intentions.

**Basic Rolls:**
```
roll
I roll
rolling
```

**Rolls with Modifiers:**
```
roll +3
I roll with a +5 bonus
rolling -2
```

**Rolls with Advantage/Disadvantage:**
```
roll with advantage
I roll with disadvantage
rolling advantage
```

**Trait-Based Rolls:**
```
roll agility
I roll strength
rolling to perceive
roll a finesse check
```

**Combined Examples:**
```
roll agility with advantage
I roll strength +3
rolling perception with disadvantage
roll to charm with a +2 bonus
I leap over the gap (uses Agility automatically!)
```

## Trait and Skill Keywords

The bot recognizes 30+ keywords across all 6 traits:

### ⚡ Agility
- **Main**: agility, agi
- **Skills**: sprint, leap, maneuver

### 💪 Strength
- **Main**: strength, str
- **Skills**: lift, smash, grapple

### 🎯 Finesse
- **Main**: finesse, fin
- **Skills**: control, hide, tinker

### 👁️ Instinct
- **Main**: instinct, ins
- **Skills**: perceive, sense, navigate

### ✨ Presence
- **Main**: presence, pres, cha
- **Skills**: charm, perform, deceive

### 📚 Knowledge
- **Main**: knowledge, kno, wis
- **Skills**: recall, analyze, comprehend

## Dice Mechanics

### Hope and Fear Dice
Every roll uses 2d12:
- **Hope Die** (🎲): The first d12
- **Fear Die** (💀): The second d12

Results display the dominant die:
- "**15 with Hope** ✨" if Hope > Fear
- "**15 with Fear** 💀" if Fear > Hope
- "**15**" if Hope = Fear (tie)

### Critical Success
When both dice show the same number, it's a **Critical Success**! 🎆
The result is displayed with special formatting.

### Advantage and Disadvantage
- **Advantage**: Roll an additional 1d6 and add it to your total (+1d6)
- **Disadvantage**: Roll an additional 1d6 and subtract it from your total (-1d6)
- If both are present, they cancel each other out

### Modifiers
Modifiers stack and combine:
- Character trait modifiers (from your character sheet)
- Explicit modifiers (from the command)
- Advantage/disadvantage dice

**Example:**
```
"roll agility +3"
- Your Agility: +2
- Explicit modifier: +3
- Total modifier: +5
```

## Setup and Configuration

### Adding the Bot
1. Invite the bot to your Discord server
2. The bot works immediately with default settings (all channels enabled)
3. Use `/help` to see all available commands

### Recommended Setup
1. **Create a dedicated dice channel**: `#dice-rolls`
2. **Configure natural language** (optional):
   ```
   /config allow-channel channel:#dice-rolls
   ```
3. **Initialize your character**:
   ```
   /character init name:"Your Name" agility:2 strength:1 finesse:3 instinct:0 presence:1 knowledge:2
   ```

### Configuration Modes

**Default Mode: Fully Enabled**
- Natural language works in all channels
- No configuration needed

**Whitelist Mode**
- Natural language only works in specific channels
- Set with `/config allow-channel`
- Best for dedicated game channels

**Blacklist Mode**
- Natural language works everywhere except disabled channels
- Set with `/config disable-channel`
- Best for excluding general chat

**Globally Disabled**
- Natural language disabled everywhere
- Slash commands still work
- Set with `/config disable-nl`

## Privacy and Data

### What We Store
- **Server Configuration**: Channel permissions and natural language settings (per server)
- **Character Data**: Character traits and names (per user, per channel)

### What We Don't Store
- Message content (except during command parsing)
- User metadata beyond Discord user IDs
- Roll history or statistics

### Data Isolation
- Character data is isolated per channel (your character in #campaign-1 doesn't affect #campaign-2)
- Multiple campaigns can run in the same server with independent characters
- Server configurations are independent
- Data persists across bot restarts using PostgreSQL

## Use Cases

### Perfect for:
- **Daggerheart TTRPG Sessions**: Full support for official dice mechanics
- **Play-by-Post Games**: Natural language makes narrative posts seamless
- **Quick Rolls**: Type naturally without memorizing command syntax
- **Multiple Campaigns**: Run multiple campaigns in one server - each channel can have different characters
- **Server Organization**: Admin controls for natural language permissions

### Example Session Flow

**Player 1:**
```
I sneak past the guard
> roll hide with advantage
```

**Bot Response:**
```
🎲 Hope: 8, 💀 Fear: 6
Modifiers:
  Finesse: +3
  Advantage: +4 (d6)

Total: 21 with Hope ✨
(8 + 6 + 3 + 4 = 21)
```

**Player 2:**
```
I try to lift the portcullis!
> roll strength
```

**Bot Response:**
```
🎲 Hope: 10, 💀 Fear: 10
Modifiers:
  Strength: +2

Total: 22
🎆 CRITICAL SUCCESS! 🎆
(10 + 10 + 2 = 22)
```

## Frequently Asked Questions

**Q: Do slash commands work everywhere?**
A: Yes! Server configuration only affects natural language. Slash commands (`/roll`, `/character`, etc.) always work in every channel.

**Q: Can I have different characters in different channels?**
A: Yes! Character data is stored per-channel. You can run multiple campaigns in the same server by creating different channels (e.g., #campaign-waterdeep, #campaign-icewind-dale).

**Q: What happens if I mention multiple traits?**
A: The bot uses the first trait keyword it detects. For example, "roll agility and strength" will use Agility.

**Q: Do advantage and disadvantage stack?**
A: No, if you specify both, they cancel each other out (per Daggerheart rules).

**Q: Can I use negative trait values?**
A: Yes! Traits can range from -10 to +10.

**Q: Does the bot store my roll history?**
A: No, the bot doesn't store any roll history or statistics.

## Technical Details

- **Built with**: Discord.js v14, TypeScript, PostgreSQL
- **Hosting**: Railway (production), supports local development
- **Database**: PostgreSQL for persistent storage
- **Uptime**: 99.9% uptime target
- **Response Time**: Sub-second command response

## Support and Feedback

- **Issues**: Report bugs in our [discord server](https://discord.gg/ebXyf48FN4)
- **Questions**: Use `/help` in Discord for command help
- **Updates**: Bot auto-updates with new features and fixes

**Last Updated**: December 2025

---

**Keywords**: Daggerheart, TTRPG, Dice Roller, Discord Bot, Character Manager, Natural Language, Hope and Fear Dice, d12, RPG, Tabletop Gaming

**Permissions Required**: Send Messages, Embed Links, Read Message History

Daggerheart-dice-bot

A companion bot for Discord. Starting off as just a dice roller, will add more features based on interest and requests

Stemmen voor Daggerheart-dice-bot

Wil je ons ondersteunen?