- About
- Features
- NEW: Mobile & PWA
- How to Play
- Classes
- Technologies
- Getting Started
- Development
- Performance
- Security
- Contributing
- Documentation
- Roadmap
- License
Dungeon Scoundrel is a progressive web app (PWA) roguelike deck-building card game where you navigate through treacherous dungeons using a standard deck of cards. Fight monsters, collect weapons, use potions, and unlock powerful relics to survive the depths!
- 🃏 Card-Based Combat: Use a deck of 50 cards (Monsters, Weapons, Potions, Specials)
- ⚔️ Strategic Gameplay: Manage resources, build combos, and choose when to fight or flee
- 🔮 Progressive Unlocks: Earn permanent upgrades across multiple runs
- 👥 6 Unique Classes: Each with distinct playstyles and abilities
- 🏆 Achievement System: 50 achievements to unlock
- 🎵 Dynamic Music: Procedural soundtrack with multiple themes
- 📱 Play Anywhere: Desktop, mobile, tablet - even offline!
- ✅ 4 Difficulty Levels: Easy, Normal, Hard, Endless
- ✅ 50-Card Deck System: Monsters (♠♣), Weapons (♦), Potions (♥), Specials (✨)
- ✅ Boss Battles: Epic fights every 10 rooms
- ✅ Combo System: Chain perfect kills for damage bonuses
- ✅ Hold Mechanic: Strategic card management
- ✅ Events & Shops: Random encounters with meaningful choices
- Scoundrel 🎭 - Pure skill, no abilities (always unlocked)
- Knight 🛡️ - Tank with Shield Bash and +5 HP
- Rogue 🗡️ - Double hold slots, Shadow Strike
- Dancer 💃 - Healing specialist with extra luck
- Berserker 💢 - High risk/reward with Bloodlust
- Priest 📿 - Divine protection and Purification
- 22 Permanent Unlocks: Start with bonuses each run
- 53 Relics: Passive and active effects across 4 rarity tiers
- 50 Achievements: Bronze, Silver, Gold, Platinum
- Global Leaderboard: Firebase-powered rankings
- 🌙 Dark Medieval Theme - Pixel-art inspired UI
- 🎵 Dynamic Music System - 5 contextual tracks (menu, gameplay, boss, victory, defeat)
- 🎨 Visual Effects - Particles, screen shake, animations
- ♿ Accessibility - ARIA labels, keyboard navigation
- 📱 Mobile-Optimized - Touch controls, haptic feedback
- 🌐 PWA Complete - Install as app, offline capable
- Install as App: Add to home screen on any device
- Offline Mode: Play without internet after first load
- Service Worker: Smart caching of all assets (11.5MB)
- Auto-Updates: Notifies when new version available
- PWA Score: 100/100 on Lighthouse
- Lazy Loading: Images load on-demand (-94% initial load)
- Adaptive Performance: Detects device capabilities automatically
- Reduced Animations: Optimized for low-end devices
- Touch-Friendly: Long-press to hold, tap to play
- Responsive Layout: Perfect on phones, tablets, desktops
- IndexedDB: Robust save system with backup/restore
- LocalStorage Fallback: Works everywhere
- Cloud Sync: Optional Firebase integration
- Multiple Saves: Store progress safely
| Metric | Before | After | Improvement |
|---|---|---|---|
| Assets Size | 9.5MB | 550KB | -94% 🎉 |
| Load Time | ~5s | ~2s | -60% 🚀 |
| FPS (Mobile) | 30 | 60 | +100% ⚡ |
| PWA Score | 60 | 100 | +40 ✨ |
| Offline | ❌ | ✅ | Working! 💯 |
See Mobile Roadmap for complete details.
-
🎯 Objective: Clear all 50 cards without dying (HP ≤ 0)
-
🏃 Actions Each Turn:
- Enter Dungeon (Draw 4 cards) OR
- Avoid Dungeon (Discard 3 cards from top)
⚠️ Cannot avoid twice in a row (unless you have Four Leaf Clover)
-
🃏 Card Types:
- Monsters (♠ Spades, ♣ Clubs) - Enemies to fight
- Weapons (♦ Diamonds) - Equip to deal damage
- Potions (♥ Hearts) - Heal HP (1 per room limit)
- Specials (✨) - Powerful one-time effects
-
⚔️ Combat:
Damage Taken = Monster Value - Your Weapon Value- Perfect kill (no damage) = Build combo!
- Taking damage = Reset combo to 0
- No weapon = Take full monster damage
-
🔥 Combo System:
- Chain perfect kills for bonus damage
- 2x combo = +1 damage, 3x = +2 damage, etc.
- Breaks when taking damage or equipping new weapon
- Higher combos = Better score multiplier
- Hold System: Save cards for later (Right-click or long-press on mobile)
- Weapon Durability: Weapons break after X uses (varies by difficulty)
- Boss Rooms: Every 10th room, face powerful multi-HP bosses
- Events: Random encounters with risk/reward choices
- Shop: Buy upgrades with gold (costs score penalty!)
- Relics: Passive and active effects that stack
| Class | Unlock Requirement | Passive Ability | Active Ability | Playstyle |
|---|---|---|---|---|
| 🎭 Scoundrel | Always unlocked | None | None | Pure skill baseline |
| 🛡️ Knight | Win on Easy | +5 HP, +1 Durability | Shield Bash (3 CD) | Tanky and consistent |
| 🗡️ Rogue | Win on Normal | 2 Hold slots, +1 Gold/room | Shadow Strike (4 CD) | Flexible combos |
| 💃 Dancer | Win on Hard | Potions +3 HP, 2 uses/room, +15% events | Healing Dance (5 CD) | Sustain specialist |
| 💢 Berserker | Hard + 5 bosses | Bloodlust: +dmg at low HP | Rage Strike (4 CD) | High risk/reward |
| 📿 Priest | 20 relics + 10 events + 5 wins | 15% dodge, Potions +2 HP | Purification (6 CD) | Safe and strategic |
- HTML5 - Semantic markup
- CSS3 - Custom properties, animations, responsive design
- Vanilla JavaScript ES6+ - Modular architecture, no frameworks
- Web Audio API - Procedural sound effects and music
- Service Workers - Workbox 7.0 for smart caching
- IndexedDB - Robust client-side database
- Lazy Loading - Progressive image loading
- Adaptive Performance - Device-specific optimizations
- Firebase Firestore - Leaderboard and cloud saves
- Firebase Auth - Anonymous authentication
- EmailJS - Bug reporting system
- Netlify - Hosting, CI/CD, CDN
- npm - Package management
- Workbox CLI - Service Worker generation
- Git - Version control
- ESLint (recommended) - Code quality
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Node.js 14+ (for development)
- Internet connection (initial load only, then works offline!)
-
Clone the repository
git clone https://github.com/ehgzao/DungeonScoundrel.git cd DungeonScoundrel -
Install dependencies
npm install
-
Generate Service Worker
npm run build:sw
-
Run locally
npm run dev # Opens at http://localhost:8080 -
Play!
- Desktop: Open in browser
- Mobile: Add to home screen for app-like experience
# Python
python -m http.server 8080
# Node.js
npx serve public
# PHP
php -S localhost:8080 -t publicDungeonScoundrel/
├── public/ # Production files (served)
│ ├── index.html # Main game file
│ ├── assets/ # Images, icons
│ │ ├── images/ # Avatars, backgrounds (WebP optimized)
│ │ └── icons/ # Favicons
│ ├── src/
│ │ ├── js/
│ │ │ ├── modules/ # Game modules (state, shop, relics, events)
│ │ │ ├── systems/ # Game systems (achievements, stats, music)
│ │ │ ├── utils/ # Utilities (helpers, mobile-optimization, offline-storage)
│ │ │ ├── data/ # Game data (relics, shop items)
│ │ │ └── core/ # Core systems (Firebase, audio, errors)
│ │ ├── css/ # Stylesheets
│ │ └── config/ # Firebase configuration
│ ├── sw.js # Service Worker (generated)
│ └── site.webmanifest # PWA manifest
├── docs/ # Project documentation
│ ├── guides/ # Roadmaps and planning
│ ├── architecture/ # Technical structure
│ ├── releases/ # Changelog and releases
│ ├── security/ # Security audits
│ ├── development/ # Dev process
│ ├── mobile/ # Mobile implementation
│ └── merge-history/ # Archived merge docs
├── scripts/ # Build and deploy scripts
├── package.json # npm configuration
├── workbox-config.js # Service Worker config
├── SECURITY.md # Security policy (245 lines)
├── README.md # This file
└── LICENSE # MIT License
npm run dev # Start local development server
npm run build:sw # Generate Service Worker
npm run deploy # Deploy to Netlify (production)-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make changes
- Code in
public/directory - Test in multiple browsers
- Check mobile responsiveness
- Code in
-
Test thoroughly
- All difficulty levels
- All classes and abilities
- Mobile/desktop compatibility
- Offline functionality
- Achievement unlocking
-
Commit with meaningful messages
git commit -m "feat: Add Lucky Horseshoe relic" -
Push and create PR
git push origin feature/your-feature-name
- JavaScript: ES6+,
constoverlet, descriptive names - HTML: Semantic markup, ARIA labels
- CSS: BEM naming, CSS custom properties
- Comments: JSDoc for functions, explain complex logic
- Modules: One responsibility per file, clear exports
- Load Time: < 2s (4G connection)
- FPS: 60fps constant
- Lighthouse Score: 95/100
- Performance: 92
- Accessibility: 98
- Best Practices: 95
- SEO: 97
- PWA: 100 ⭐
- Load Time: ~2s (4G), instant after cache
- FPS: 60fps on mid-range devices
- Battery: Optimized (reduced animations on low-end)
- Data Usage: 550KB initial, 0KB after cache
- ✅ 100% functional after first load
- ✅ Service Worker caches 49 files (11.5MB)
- ✅ All game features work offline
- ✅ Leaderboard syncs when online
- Lazy Loading: Images load on-demand
- WebP Format: 94% smaller than JPEG
- Code Splitting: Modular architecture
- Adaptive Performance: Device detection
- Smart Caching: Workbox strategies
- Reduced Animations: Mobile/low-end optimization
See Mobile Progress Report for detailed metrics.
We take security seriously. Please review our Security Policy for:
- Supported Versions: Which versions receive security updates
- Reporting Vulnerabilities: How to report security issues privately
- Response Timeline: What to expect when reporting
- Security Features: Built-in protections
- Hall of Fame: Contributors who helped secure the game
- ✅ HTTPS-only (enforced by Netlify)
- ✅ Content Security Policy headers
- ✅ Firebase security rules
- ✅ Input sanitization
- ✅ No sensitive data in localStorage
- ✅ Anonymous authentication only
Found a vulnerability? Please report it privately via GitHub Security Advisories.
We love contributions! Whether it's code, art, music, or documentation - all help is welcome.
- Fork the repository
- Clone your fork
- Create a feature branch
- Make your changes
- Test thoroughly
- Commit with clear messages
- Push to your fork
- Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
- 🎨 UI/UX Design: Visual improvements, animations
- 🎵 Music & Sound: Additional tracks, SFX variations
- 🌍 Localization: Translate to other languages
- 🐛 Bug Fixes: Check open issues
- ⚡ Performance: Optimize code and assets
- 📚 Documentation: Tutorials, guides, API docs
- 🎮 Game Design: New relics, classes, mechanics
- 🧪 Testing: QA on different devices
- README.md - This file (overview and setup)
- SECURITY.md - Security policy and reporting
- CONTRIBUTING.md - Contribution guidelines
- LICENSE - MIT License
- Mobile Roadmap - Complete mobile implementation guide (1308 lines)
- Mobile Progress - Phase 1 tracking (Weeks 1-2 complete)
- Merge Analysis - Code review and compatibility analysis
- Merge Guide - Git workflow for mobile branch
- CHANGELOG.md - Version history and changes
- BACKLOG_PRIORIZADO.md - Prioritized feature backlog
- MODULES.md - Module architecture documentation
Total Documentation: 4100+ lines across 11 files
- ✅ Mobile PWA implementation (Phase 1)
- ✅ Service Worker and offline mode
- ✅ IndexedDB for robust saves
- ✅ Performance optimizations (60 FPS mobile, -60% load time)
- ✅ Cloud saves working
- ✅ Security audit and improvements
- ⏳ Additional language support
- ⏳ Advanced tutorial for experienced players
- ⏳ Tutorial replay option in menu
- ⏳ Touch-friendly UI improvements
- ⏳ Mobile tooltips (tap instead of hover)
- Native mobile apps (Capacitor)
- iOS App Store release
- Google Play Store release
- In-App Purchases (remove ads, starter packs)
- Push notifications (daily rewards)
- Native features (Game Center, Google Play Games)
- Multiplayer mode (async PvP)
- Daily challenges with leaderboard
- Seasonal events
- New class: Mage 🧙
- More relics (70 total)
- Card crafting system
- Mod support (custom cards, relics)
- Level editor (community dungeons)
- Steam release (desktop app)
- Achievements via Steam/Epic
- Cloud save sync across platforms
- Localization (10+ languages)
See Mobile Roadmap for detailed Phase 2 planning.
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License - Copyright (c) 2025 ehgzao
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
[Full license text in LICENSE file]
- Balatro - UI/UX design and visual polish
- Slay the Spire - Roguelike deck-building mechanics
- Inscryption - Card game innovation and atmosphere
- Google Fonts - Cinzel, Cinzel Decorative, MedievalSharp
- AI-Generated Art - Class avatars and background (via Midjourney)
- Custom Pixel Art - UI elements and icons
- Firebase - Backend as a Service
- Netlify - Hosting and CI/CD
- EmailJS - Email integration
- Workbox - PWA toolkit by Google
- Web Audio API - Procedural audio synthesis
- All contributors and playtesters
- The roguelike community on Reddit
- Open source maintainers
- Early access players who provided feedback
- 🌐 Play Now: dungeonscoundrel.com
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: hello@dungeonscoundrel.com (or use in-game bug report)
- 👨💻 GitHub: @ehgzao
- 🔗 Repository: DungeonScoundrel
- 📚 Full Documentation: docs/
- 🛡️ Security Policy: SECURITY.md
- 🛡️ Security Audit: SECURITY_AUDIT.md
- 🗺️ Mobile Roadmap: MOBILE_ROADMAP.md
- 📝 Changelog: CHANGELOG.md
| Resource | Description |
|---|---|
| 🎮 Play Game | Start playing now (PWA, works offline!) |
| 📱 Mobile Guide | Complete mobile implementation roadmap |
| 🛡️ Security | Report vulnerabilities, security policy |
| 🐛 Report Bug | Found a bug? Let us know |
| ✨ Request Feature | Have an idea? Share it |
| 📖 Documentation | Read all docs (organized by category) |
| 🤝 Contributing | Join the development |
| 📜 License | MIT License details |
Made with ❤️ by ehgzao
⭐ Star this repo if you enjoy the game! ⭐
🎮 Play Now | 📱 Mobile Roadmap | 🛡️ Security | 🐛 Report Issue
Version 1.4.3 | PWA Score: 100/100 | Offline Ready | Lighthouse Optimized
Dungeon Scoundrel is a free, open-source game. No ads, no tracking, no microtransactions.