🎮 Dungeon Crawler MMO

A Production-Ready Multiplayer Game Boilerplate

Build your own MMO with Vampire Survivors-style combat, real-time multiplayer, and instanced dungeons.

Quick Start • Documentation • Features • Contributing

crawler.mp4

🎯 What is this?

This is a fully-featured MMO game boilerplate designed as a foundation for building multiplayer games. It includes complete implementations of core MMO systems that would typically take months to build from scratch.

Perfect for:

• 🎮 Game developers wanting a multiplayer foundation
• 📚 Developers learning real-time game architecture
• 🚀 Startups prototyping multiplayer game ideas
• 🔧 Anyone interested in Socket.IO/WebSocket game patterns

✨ Features

🎮 Core Gameplay ⚔️ Vampire Survivors Combat - Auto-targeting, radius-based attacks, piercing, upgrades 🌍 Persistent Hub World - Social hub where all players gather 🏰 Instanced Dungeons - Party-based dungeon runs 👥 Party System - Create/join parties, party-only chat 💬 Tabbed Chat System - Global and party chat 🎭 Multiple Characters - Up to 5 characters per account	📈 Progression Systems 📊 Character Leveling - Persistent XP, levels, kills, deaths ⚡ In-Match Upgrades - Temporary buffs that reset after dungeon 🔓 Account Upgrades - Permanent unlocks and stat boosts 🗡️ Weapon System - Multiple weapon types with upgrade paths 💎 Loot Drops - Enemy drops (foundation ready for item system)
🔒 Security & Auth 🔐 Session Management - Database-backed with view/terminate 🚫 Concurrent Login Prevention - Blocks duplicate sessions ⚡ Force Login - Option to kick existing session 🔑 Secure Password Change - With current password verification 🎫 Play Ticket Auth - Short-lived tokens for game server	⚙️ Technical Features 🔄 Real-time State Sync - MMO-style concurrent updates 🎨 Modern UI - React + Tailwind CSS dark theme 🎮 3D Graphics - Three.js with camera controls 🐳 Docker Deployment - Multi-service containerized 🌐 LAN Support - Auto-detects hostname for local play

🛠️ Tech Stack

Layer	Technologies
Frontend	React 18, Three.js, Tailwind CSS, Vite, Zustand
Backend	Node.js, Express, Socket.IO
Database	SQLite (easily swappable to PostgreSQL/MongoDB)
DevOps	Docker, Docker Compose, Jest, Playwright
Architecture	MMO-style state sync with server authority

🏗️ Architecture

┌────────────────────────────────────────────────────────────────────────────┐
│                              DUNGEON CRAWLER MMO                           │
├─────────────┬─────────────┬─────────────┬──────────────────────────────────┤
│   Profile   │   Profile   │    Game     │          Game Client             │
│   Client    │    API      │   Server    │       (React/Three.js)           │
│   (React)   │  (Express)  │ (Socket.IO) │                                  │
│  Port 3000  │  Port 3001  │  Port 3030  │          Port 5173               │
├─────────────┼─────────────┼─────────────┼──────────────────────────────────┤
│ • Login UI  │ • Auth API  │ • Gameplay  │ • 3D Rendering                   │
│ • Register  │ • Sessions  │ • Combat    │ • Real-time Game UI              │
│ • Dashboard │ • SQLite DB │ • Parties   │ • WebSocket Client               │
└─────────────┴─────────────┴─────────────┴──────────────────────────────────┘

📖 View Full Architecture Documentation → (850+ lines of detailed system design)

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for local development)

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/ClaytonWas/dungeon-crawler.git
cd dungeon-crawler

# Start all services
docker-compose up

# Access the application
# Profile UI:  http://localhost:3000
# Game Client: http://localhost:5173

Option 2: Local Development

# Terminal 1 - Profile Server (Auth API)
cd client
npm install && npm start

# Terminal 2 - Game Server (Socket.IO)
cd server
npm install && npm start

# Terminal 3 - Game Client (Vite + React)
cd client/game-client
npm install && npm run dev

📖 Documentation

This project includes 4,700+ lines of comprehensive documentation:

Guide	Description
📐 ARCHITECTURE.md	Complete system design, data flow, and component interactions
🤝 CONTRIBUTING.md	Development workflow, code standards, and PR guidelines
🌍 WORLD_CREATION_GUIDE.md	Create custom game worlds with JSON schemas
⚔️ WEAPON_GUIDE.md	Design and implement new weapon systems
👤 CHARACTER_GUIDE.md	Character creation, stats, and progression
🎬 SCENE_QUICK_START.md	Quick reference for scene configuration
🧪 TESTING_GUIDE.md	Testing strategies, Jest, and Playwright setup

🎯 Quick Examples

🌍 Create a New World

# Create a new scene file
cd server/scenes
touch my_dungeon.json

Scene files support hot-reload — no rebuild needed!

⚔️ Add a New Weapon

// server/systems/weaponDefinitions.js
myWeapon: {
  type: 'myWeapon',
  name: 'Fire Sword',
  baseStats: {
    attackRadius: 5.0,
    attackCooldown: 1000,
    baseDamage: 20,
    damageVariation: 5,
    maxTargets: 2
  },
  upgradePath: { /* ... */ }
}

📖 See WEAPON_GUIDE.md for complete weapon creation docs.

🎨 Customize the UI Theme

Edit client/game-client/tailwind.config.js to customize colors, fonts, and spacing.

📁 Project Structure

dungeon-crawler/
├── 📁 client/
│   ├── 📁 profile-client/       # Login/Register UI (React + Vite)
│   ├── 📁 game-client/          # Game UI + Three.js rendering
│   ├── 📄 apiServer.js          # Auth API (Express)
│   └── 📁 db/                   # SQLite database & schemas
│
├── 📁 server/
│   ├── 📄 gameServer.js         # Main game logic (Socket.IO)
│   ├── 📁 systems/              # Combat, weapons, characters, upgrades
│   └── 📁 scenes/               # World definitions (JSON)
│
├── 📄 docker-compose.yaml       # 4-service orchestration
└── 📚 Documentation             # 4,700+ lines of guides

🧪 Testing

# Run all tests
npm test

# Backend tests only
npm run test:backend

# Frontend tests
npm run test:frontend

# E2E tests with Playwright
npm run test:e2e

# Coverage report
npm run test:coverage

🤝 Contributing

Contributions are welcome! This is a template repository — fork it to build your own game, or contribute improvements to the boilerplate.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📖 See CONTRIBUTING.md for detailed guidelines.

📋 Production Checklist

View production readiness checklist

Before deploying to production:

• Replace SQLite with PostgreSQL/MongoDB
• Add input validation (Zod schemas)
• Implement rate limiting
• Add comprehensive error handling
• Set up logging (Winston/Pino)
• Configure CORS properly
• Use environment variables for secrets
• Set up Redis for shared state
• Implement anti-cheat measures
• Add monitoring and alerting

📖 See TESTING_GUIDE.md for testing strategies.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

You are free to use this boilerplate for personal and commercial projects.