Dord Roller

A Twitch D&D Stream Management Suite

Roll dice, track monsters, manage characters — all in real-time for your stream.

🚀 Live: dordroller-production.up.railway.app

</div>

📖 About

Dord Roller is a modular, real-time web application suite designed for Twitch streamers who run D&D campaigns. It connects Game Masters, Players, and your stream overlay seamlessly through WebSocket technology.

🗂️ Project Structure

DordRoller/
├── 🖥️  backend/        → Node.js server (Express + Socket.io)
├── 🎮  gm-client/      → GM control panel
├── 👤  player-client/  → Player character sheets & rolling
├── 📺  obs-client/     → OBS browser source overlay
└── 🔗  shared/         → Shared utilities & event definitions

✨ Features

🎮 GM Client

| Feature | Description | |---------|-------------| | Dice Roller | Roll d4, d6, d8, d10, d12, d20, d100 with custom labels | | Monster Tracker | Search D&D 5e bestiary, track HP with visual health bars, roll attacks/saves/checks directly from cards | | Monster Roll Buttons | Expandable panel per monster with initiative, ability checks, saves, attacks & damage — all with editable modifiers | | Action Builder | Guided form to compose actions & reactions in the correct format so the roll panel auto-generates attack and damage buttons | | Custom Monster Library | Save any monster to your account and pull it into future rooms — appears in search with a ⭐ Custom tag | | Room Management | Generate unique room codes for player sessions | | Live Broadcasting | Instant sync to OBS overlay and connected players |

👤 Player Client

Full D&D 5e character sheet with automatic calculations:

📝 Basic Info — Name, class, level, race, alignment, XP
💪 Ability Scores — Auto-calculated modifiers & totals
🛡️ Saving Throws — Proficiency tracking per ability
🎯 Skills — All 18 skills with proficiency & expertise
⚔️ Combat — AC, HP, initiative, speed, weapons, armor
✨ Spellcasting — Cantrips, prepared spells (1st-9th), slot tracking
🎒 Inventory — Equipment, features, and feats tabs

📺 OBS Client

Stream-Ready Overlay — Drop into OBS as a browser source (designed for 1920×1080 resolution)
Real-Time Updates — Dice rolls and game state broadcast instantly
Health Bar Overlay — Persona-inspired JRPG health bars for party and enemies
- Grouped display: Party (top-left) and Enemies (top-right) with configurable positions
- Smooth animations: sliding fills, ghost bar trail on damage, heal effects
- Death state: greyed-out bars for downed entities
- Max 10 bars per group (players and monsters independently)
- Player tags: shows "Player: {Name}" under each player's bar with auth service icon (Twitch, etc.)
GM Overlay Controls — Full customization from the GM settings panel
- Toggle overlay, names, and HP numbers on/off
- Independent bar font/size, header font/size, and player tag font/size
- Color pickers: primary bar, low HP, ghost bar, header text, monster names, player names, player tag
- Visual position picker for each group (4 corners)
- Per-entity visibility toggles
- Manual sync button to refresh overlay state
- All settings persist to database

🛠️ Tech Stack

| Layer | Technologies | |-------|--------------| | Backend | Node.js, Express.js, Socket.io, JWT | | Frontend | Vite, ES6+ JavaScript, CSS3 | | Real-time | WebSocket (Socket.io) | | Database | PostgreSQL (with JSONB for character sheets) | | Authentication | Twitch OAuth 2.0 | | Security | bcrypt, validator, rate limiting, OWASP compliance | | Deployment | Docker, Docker Compose, Railway, VPS | | Data | D&D 5e Bestiary JSON (5etools format) |

🚀 Deployment

🚂 Railway (Recommended)

The easiest and most secure way to deploy. No server management, automatic HTTPS, no port forwarding required.

⚠️ Important: You must fork this repository to your own GitHub account. Deploying directly from the original repo means you won't be able to customize settings, update your instance, or control your data. Fork first = you own your installation.

Fork this repository to your GitHub account (click "Fork" button top-right)
Go to Railway and create an account (GitHub login recommended)
Click "New Project" → "Deploy from GitHub repo"
Select your forked repository (not the original) and click Deploy
Railway auto-detects the Dockerfile and starts building
Add PostgreSQL: Click "+ New" in your project → "Database" → "Add PostgreSQL"
Link the database: Click on your app service → Variables → "Add Variable Reference" → Select DATABASE_URL from the PostgreSQL service
Set environment variables in Railway (see table below)
Redeploy: After adding variables, Railway will automatically redeploy
Get your URL: Once deployed, click on your service → Settings → Copy your *.railway.app URL

Railway automatically creates database tables on first startup. No manual SQL required.

💡 Tip: Your Railway URL will look like https://your-app-name.up.railway.app. You'll need this for the Twitch OAuth redirect URI.

Environment Variables

| Variable | Required | Value / Description | |----------|----------|---------------------| | NODE_ENV | Yes | production | | DATABASE_URL | Yes | ${{Postgres.DATABASE_URL}} (use Railway's variable reference) | | AUTH_ENABLED | Yes | true to require login, false for anonymous | | JWT_SECRET | If auth enabled | Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | | SESSION_SECRET | If auth enabled | Generate another random string (same command as above) | | TWITCH_CLIENT_ID | For Twitch login | From Twitch Developer Console | | TWITCH_CLIENT_SECRET | For Twitch login | From Twitch Developer Console | | TWITCH_REDIRECT_URI | For Twitch login | https://your-app.railway.app/auth/twitch/callback | | CORS_ORIGIN | Yes | https://your-app.railway.app (your Railway URL, no trailing slash) |

🎮 Setting Up Twitch Login for Railway

Get your Railway URL first — Deploy the app (steps above) and copy your URL from Settings
Create a Twitch App:
- Go to Twitch Developer Console → "Register Your Application"
- Name: Whatever you want (e.g., "My DordRoller")
- OAuth Redirect URLs: https://your-app.railway.app/auth/twitch/callback (use YOUR Railway URL)
- Category: Website Integration
- Client Type: Confidential
- Click Create
Get credentials: Click Manage on your app → Copy Client ID → Click New Secret (save it immediately, you can't see it again!)
Add to Railway Variables:
- TWITCH_CLIENT_ID = your Client ID
- TWITCH_CLIENT_SECRET = your secret
- TWITCH_REDIRECT_URI = https://your-app.railway.app/auth/twitch/callback
- AUTH_ENABLED = true
- JWT_SECRET = generate a random string (use the command in the table above)
Redeploy — Railway auto-redeploys after variable changes

📝 Without Twitch: Set AUTH_ENABLED=false to skip login entirely (anyone can access).

Alternatives: Render, Fly.io — all have free tiers.

🔧 Development Setup

For contributing or testing features locally.

Prerequisites: Node.js >= 18, pnpm, PostgreSQL 14+

git clone https://github.com/misterbytes404/DordRoller.git
cd DordRoller

# Install dependencies
cd backend && pnpm install
cd ../gm-client && pnpm install
cd ../player-client && pnpm install
cd ..

# Configure environment
cp backend/.env.example backend/.env
# Edit with your local PostgreSQL credentials

# Start services (separate terminals)
cd backend && pnpm dev        # Terminal 1
cd gm-client && pnpm dev      # Terminal 2
cd player-client && pnpm dev  # Terminal 3

Access: http://localhost:3000 (backend), http://localhost:5173 (GM), http://localhost:5175 (Player)

🐳 Self-Hosting (Advanced)

⚠️ Warning: Self-hosting requires exposing your server to the public internet. This involves port forwarding, firewall configuration, and security hardening. Only recommended for experienced users.

<details> <summary>Docker Compose (VPS or Local)</summary>

git clone https://github.com/misterbytes404/DordRoller.git
cd DordRoller
cp backend/.env.example .env
# Edit .env with your settings

docker-compose up -d

Access: http://localhost:3000 (or your server IP)

</details> <details> <summary>Manual VPS Setup</summary>

# Install Node.js 20, PostgreSQL, pnpm
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs postgresql postgresql-contrib
npm install -g pnpm

# Clone and build
git clone https://github.com/misterbytes404/DordRoller.git
cd DordRoller
cd backend && pnpm inst

DordRoller

Install / Use

README