Initial commit

2025-11-30 08:53:41 +08:00
commit 0181dafe21
18 changed files with 3161 additions and 0 deletions
--- a/skills/dnd-dm/README.md
+++ b/skills/dnd-dm/README.md
@@ -0,0 +1,201 @@
+# 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!**