202 lines
5.4 KiB
Markdown
202 lines
5.4 KiB
Markdown
# D&D Dungeon Master Skill
|
|
|
|
A comprehensive D&D 5e Dungeon Master skill for Claude Code that integrates with CandleKeep for adventure books and provides immersive gameplay features.
|
|
|
|
## Features
|
|
|
|
- **Adventure Book Integration**: Query D&D adventure modules stored in CandleKeep
|
|
- **Dice Rolling**: CLI-based dice roller for all game mechanics
|
|
- **NPC Voice Acting**: Optional text-to-speech for bringing NPCs to life
|
|
- **Campaign Management**: Track sessions, character progression, and story arcs
|
|
- **Two Game Modes**: Adventure Mode (immersive) or Debug Mode (transparent)
|
|
|
|
## Quick Start
|
|
|
|
### Basic Setup
|
|
|
|
1. The skill is ready to use out of the box for running D&D campaigns
|
|
2. Make sure you have adventure books loaded in CandleKeep
|
|
3. Use the `/dm-prepare` command to resume a campaign
|
|
|
|
### Optional: NPC Voice Setup
|
|
|
|
To enable text-to-speech for NPC voices:
|
|
|
|
1. **Get an API Key**:
|
|
- Sign up at [ElevenLabs](https://elevenlabs.io)
|
|
- Navigate to Settings → API Keys
|
|
- Copy your API key
|
|
|
|
2. **Configure the Skill**:
|
|
```bash
|
|
cd .claude/skills/dnd-dm
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. **Add Your API Key**:
|
|
Edit `.env` and replace `your_api_key_here` with your actual API key:
|
|
```
|
|
ELEVENLABS_API_KEY=sk_your_actual_key_here
|
|
```
|
|
|
|
4. **Install Dependencies** (if not already done):
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
5. **Test It**:
|
|
```bash
|
|
node speak-npc.js --text "Welcome, brave adventurer!" --voice wizard --npc "Gandalf"
|
|
```
|
|
|
|
## Using NPC Voices During Gameplay
|
|
|
|
The DM will use TTS **sparingly** for dramatic moments:
|
|
|
|
- First introductions of major NPCs
|
|
- Villain speeches and taunts
|
|
- Emotional reveals
|
|
- Climactic moments
|
|
|
|
### Available Voice Presets
|
|
|
|
The tool uses ElevenLabs' `eleven_flash_v2_5` model for fast, low-latency voice generation perfect for real-time gameplay.
|
|
|
|
```bash
|
|
# List all available voices
|
|
node speak-npc.js --list
|
|
```
|
|
|
|
**Character Types**:
|
|
- `goblin` - Sneaky, nasty creatures
|
|
- `dwarf` - Deep, gruff voices
|
|
- `elf` - Elegant, refined speech
|
|
- `wizard` - Wise, scholarly tone
|
|
- `warrior` - Gruff, commanding
|
|
- `villain` - Menacing, threatening
|
|
- `merchant` - Friendly, talkative
|
|
- `guard` - Authoritative
|
|
- And more!
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Goblin ambush
|
|
node speak-npc.js --text "You die now, pinkskin!" --voice goblin --npc "Cragmaw Scout"
|
|
|
|
# Wise wizard
|
|
node speak-npc.js --text "The path ahead is fraught with danger." --voice wizard --npc "Elminster"
|
|
|
|
# Villain monologue
|
|
node speak-npc.js --text "You fools! You've played right into my hands!" --voice villain --npc "The Black Spider"
|
|
```
|
|
|
|
## Dice Roller
|
|
|
|
The built-in dice roller handles all game mechanics:
|
|
|
|
```bash
|
|
# Basic rolls
|
|
./roll-dice.sh 1d20+5 --label "Attack roll"
|
|
./roll-dice.sh 2d6+3 --label "Damage"
|
|
|
|
# Advantage/Disadvantage
|
|
./roll-dice.sh 1d20+3 --advantage --label "Attack with advantage"
|
|
./roll-dice.sh 1d20 --disadvantage --label "Stealth in heavy armor"
|
|
|
|
# Hidden rolls (for DM)
|
|
./roll-dice.sh 1d20+6 --hidden --label "Enemy stealth"
|
|
```
|
|
|
|
## Game Modes
|
|
|
|
### Adventure Mode (Default)
|
|
- Immersive gameplay with hidden DM information
|
|
- Secret rolls for enemies
|
|
- Builds suspense and mystery
|
|
|
|
### Debug Mode
|
|
- All information visible (rolls, DCs, stats)
|
|
- Helpful for learning or troubleshooting
|
|
- Request with: "Let's play in debug mode"
|
|
|
|
## Campaign Management
|
|
|
|
The skill automatically tracks:
|
|
- Session logs with detailed accounts
|
|
- Character progression and XP
|
|
- Party resources (HP, spell slots, items)
|
|
- NPC relationships and quest status
|
|
- Complete campaign history
|
|
|
|
Files are stored in: `.claude/skills/dnd-dm/sessions/<campaign-name>/`
|
|
|
|
## Troubleshooting
|
|
|
|
### TTS Not Working?
|
|
|
|
1. **Check API Key**: Verify `.env` file exists with valid key
|
|
2. **Audio Player**:
|
|
- macOS: Uses `afplay` (built-in)
|
|
- Linux: Install `mpg123` via package manager
|
|
3. **API Quota**: Check usage at [ElevenLabs Dashboard](https://elevenlabs.io)
|
|
4. **Skip It**: TTS is optional! The skill works perfectly without it
|
|
|
|
### Dependencies Not Installed?
|
|
|
|
```bash
|
|
cd .claude/skills/dnd-dm
|
|
npm install
|
|
```
|
|
|
|
### Permission Issues?
|
|
|
|
Make scripts executable:
|
|
```bash
|
|
chmod +x roll-dice.sh
|
|
chmod +x speak-npc.js
|
|
```
|
|
|
|
## Files
|
|
|
|
```
|
|
.claude/skills/dnd-dm/
|
|
├── SKILL.md # Main skill definition
|
|
├── dm-guide.md # Detailed DM guidance
|
|
├── roll-dice.sh # Dice rolling CLI
|
|
├── speak-npc.js # TTS CLI tool
|
|
├── package.json # Node dependencies
|
|
├── .env.example # API key template
|
|
├── .env # Your API key (git-ignored)
|
|
├── sessions/ # Campaign data
|
|
│ └── <campaign>/
|
|
│ ├── campaign-log.md
|
|
│ ├── campaign-summary.md
|
|
│ └── character-*.md
|
|
└── templates/ # Session templates
|
|
```
|
|
|
|
## Tips for Great Games
|
|
|
|
1. **Read Ahead**: Know the next 2-3 encounters
|
|
2. **Take Notes**: Track NPC interactions and player decisions
|
|
3. **Use Voice Sparingly**: Save TTS for impactful moments
|
|
4. **Be Flexible**: Players will surprise you - embrace it!
|
|
5. **Have Fun**: Your enthusiasm is contagious!
|
|
|
|
## Commands
|
|
|
|
- `/dm-prepare` - Resume a campaign session (reads logs and prepares next content)
|
|
- Regular conversation activates the skill automatically
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- Check the [Claude Code Documentation](https://docs.claude.com)
|
|
- Review `SKILL.md` for detailed instructions
|
|
- Consult `dm-guide.md` for DMing tips
|
|
|
|
---
|
|
|
|
**Ready to start your adventure? Just say "Let's play D&D" and begin!**
|