shattered-realms

Shattered Realms ARPG

A Path of Exile-inspired Action RPG built with Phaser.js and MCP (Model Context Protocol) integration.

🎮 Game Features

Core Systems ✅

• 5 Character Classes: Warrior, Ranger, Mage, Assassin, Paladin
• Entity Component System (ECS): Scalable game architecture
• Real-time Character Movement: WASD/Arrow key controls with smooth camera following
• Health & Mana Systems: Regeneration and UI bars
• MCP Integration: 5 game tools for authentication, character management, item generation, and combat

Database Features ✅

• 15 Database Tables: Users, characters, items, skills, passive tree, trading
• SQLite with WAL Mode: Optimized for performance
• Complete Game Schema: Ready for full ARPG implementation

Technical Stack ✅

• Frontend: Phaser.js 3.70+ with TypeScript
• Backend: Node.js with MCP servers
• Database: SQLite with optimization
• Authentication: OAuth 2.1 with PKCE + JWT tokens
• Build Tools: Webpack 5, TypeScript 5.2+
• Testing: Jest with coverage reporting

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm 8+

Installation

# Clone the repository
git clone https://github.com/oryosef1/shattered-realms.git
cd shattered-realms

# Install dependencies
npm install

# Setup database and seed data
npm run setup

# Start development
npm run dev

Available Scripts

• npm run dev - Start development servers (client + server)
• npm run build - Build for production
• npm test - Run test suite
• npm run typecheck - TypeScript type checking
• npm run lint - ESLint code quality
• npm run db:migrate - Run database migrations
• npm run db:seed - Seed initial game data

🎯 Project Status

✅ Completed (Week 1-2)

• MCP server architecture with 5 game tools
• Complete SQLite database schema (15 tables)
• OAuth 2.1 + PKCE authentication
• JWT token management
• Phaser.js game client setup
• Entity Component System (ECS)
• Character movement and controls
• Health/mana systems with UI
• Webpack build pipeline
• TypeScript configuration

🚧 In Progress (Week 3-4)

• Character creation system
• Basic combat mechanics
• Inventory and item management
• Skill system implementation

📋 Planned Features

• Combat System: Real-time ARPG combat with skills and spells
• Item System: 100+ base items, unique items, crafting currencies
• Skill Tree: 80 skills across 5 classes
• Reality Shards: 200 support gems for skill modification
• Passive Tree: 2500 nodes for character customization
• Trading System: Player-to-player item trading
• Procedural Dungeons: Endless dungeon generation
• Multiplayer: Party system and shared instances

🏗️ Architecture

MCP Server Tools

1. authenticate_player - OAuth 2.1 with PKCE authentication
2. get_character_data - Retrieve character stats and equipment
3. create_character - Create new characters
4. generate_item - Procedural item generation with affixes
5. calculate_damage - Combat damage calculations

Database Schema

• Users: Authentication and account management
• Characters: Player characters with stats and progression
• Items: Base items, generated items, and equipment
• Skills: Character abilities and progression
• Trading: Market listings and transactions
• Sessions: Game analytics and session tracking

Client Architecture

• Scene Management: Loading, Menu, Character Select, Gameplay
• ECS Components: Position, Velocity, Health, Mana, Sprites
• Systems: Movement, Health, Input, Rendering
• Real-time UI: Health/mana bars, debug information

🎮 Gameplay

Character Classes

• Warrior: High strength, melee combat specialist
• Ranger: Dexterity-based, ranged combat with bows
• Mage: Intelligence-focused, elemental magic caster
• Assassin: Balanced stats, critical strikes and stealth
• Paladin: Holy warrior with support abilities

Controls

• Movement: WASD or Arrow Keys
• Attack: Spacebar (placeholder)
• Camera: Automatically follows player
• UI: Real-time health/mana display

🛠️ Development

Code Quality

• TypeScript: Full type safety
• ESLint: Code quality enforcement
• Prettier: Code formatting
• Jest: Comprehensive testing

Performance Targets

• 60 FPS: Consistent frame rate
• <3s Load Times: Fast scene transitions
• <2GB Memory: Efficient resource usage
• <100ms Network: Responsive multiplayer

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

This project is developed as a learning exercise for game development with modern web technologies and MCP integration.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com