⚔️ DM Toolkit — Dungeon Master's Companion

A full-featured D&D 5e Dungeon Master toolkit with AI generation, dynamic battle maps, combat tracking, procedural soundtrack, and dice simulation.

Features

Module	Description
🧙 AI Generator	Generate story passages, NPCs, encounters, traps, and lore using Gemini AI
🎵 Soundtrack	Procedural Web Audio API music — no external files, fully browser-based
🗺️ Battle Map	24×16 grid with drag-and-drop tokens, AI terrain generation, tile painting
⚔️ Battle Engine	Initiative tracker, HP management, spell slots, conditions, death saves, attack resolver
🎲 Dice Simulator	All D&D dice, modifiers, advantage/disadvantage, animated rolls, roll history

Prerequisites

• Node.js 18+
• A free Gemini API key (get one at aistudio.google.com)

Setup

1. Install dependencies

npm run install:all

This installs both root and client dependencies.

2. Configure your API key

cp .env.example .env

Edit .env and add your Gemini API key:

GEMINI_API_KEY=your_actual_key_here

3. Start the app

npm run dev

This starts both the Express API server (port 3001) and the Vite dev server (port 5173).

Open http://localhost:5173 in your browser.

Getting a Free Gemini API Key

1. Go to aistudio.google.com
2. Sign in with a Google account
3. Click "Get API Key" → "Create API Key"
4. Copy the key into your .env file

The free tier supports generous requests — perfect for table-side use.

Usage Guide

AI Generator

• Select a generation type (Story, NPC, Encounter, Trap, Lore)
• Type a prompt or click a quick preset
• Press Ctrl+Enter or the Generate button
• History is saved to localStorage

Soundtrack

• Pick a scene and mood, then generate an AI soundtrack
• Or load a preset (Dungeon, Combat, Tavern)
• Click ▶ Play — music plays procedurally via Web Audio API
• Mute/unmute individual instrument layers
• Adjust volume with the slider

Battle Map

• Use AI Map Generator to create terrain from a text description
• Switch between Select/Move and Paint Tiles tools
• Drag tokens to reposition them
• In Select mode, click a token to highlight its movement range
• Add custom tokens with the form at the bottom

Battle Engine

• Add players and enemies with the form at the bottom
• Click Roll Initiative to start combat
• Next Turn advances to the next character
• Click ⚔️ on any character to open the Attack Resolver
• Track spell slots, conditions, and death saving throws
• All actions are logged in the Combat Log

Dice Simulator

• Select dice quantities with +/- buttons
• Set a modifier and advantage/disadvantage for d20s
• Click ROLL DICE (or use presets)
• Critical hits (20) and fumbles (1) are highlighted
• Roll history shows the last 20 rolls

Architecture

dnd-dm-toolkit/
├── server/
│   └── index.js          # Express API — proxies Gemini calls (SSE streaming)
├── client/
│   └── src/
│       ├── components/   # Feature modules (one per tab)
│       ├── hooks/        # useSSE — streaming API hook
│       └── App.jsx       # Tab navigation shell
├── .env.example
└── package.json          # Root — runs both with concurrently

API Routes

Route	Description
POST /api/ai/generate	AI story/NPC/encounter/trap/lore generation
POST /api/ai/terrain	Battle map JSON generation
POST /api/ai/soundtrack	Soundtrack layer JSON generation

All routes stream responses via Server-Sent Events (SSE). "# DDHelper"