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
• 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