Shatteredvoid/README.md

Shattered Void MMO

A post-collapse galaxy MMO strategy game built with Node.js, Express, PostgreSQL, and WebSockets.

🎮 Game Overview

Shattered Void is a text-based MMO strategy game set in a post-collapse galaxy where players rebuild civilizations from ruins through colony management, fleet construction, exploration, and participation in dynamic galaxy-wide events.

Core Features

• Colony Management: Build and upgrade colonies across different planet types
• Fleet Construction: Design modular ships and manage fleets
• Research System: Unlock new technologies and capabilities
• Dynamic Events: Participate in admin-driven and player-triggered galaxy events
• Faction Warfare: Form alliances and engage in diplomacy
• Real-time Updates: WebSocket-powered live game state updates

🏗️ Architecture

Tech Stack

• Backend: Node.js with Express framework
• Database: PostgreSQL (primary) + Redis (caching/sessions)
• Real-time: WebSocket connections for live updates
• Authentication: JWT-based with separate admin/player systems
• Testing: Jest with comprehensive unit and integration tests

Project Structure

src/
├── config/          # Database, Redis, logging configuration
├── database/        # Migrations, seeds, and query files
├── models/          # Database models organized by domain
├── services/        # Business logic layer
├── controllers/     # HTTP route handlers (API + Admin)
├── middleware/      # Express middleware (auth, validation, etc.)
├── validators/      # Input validation schemas
├── utils/           # Helper functions and utilities
├── plugins/         # Plugin system for extensible game mechanics
├── jobs/            # Background job processing
└── routes/          # Route definitions

tests/
├── unit/            # Unit tests for services, models, utils
├── integration/     # API and database integration tests
├── e2e/             # End-to-end tests
├── fixtures/        # Test data
└── helpers/         # Test utilities

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm 9+
• PostgreSQL 14+
• Redis 6+

Installation

1. Clone the repository
2. Copy environment configuration:

   cp .env.example .env.development
   

3. Update .env.development with your database credentials
4. Install dependencies:

   npm install
   

5. Set up the database:

   npm run db:setup
   

6. Start the development server:

   npm run dev
   

The server will start on http://localhost:3000 with WebSocket support.

🎯 Game Systems

Resource Economy

• Scrap Metal: Basic building materials
• Energy Cells: Power for operations
• Data Cores: Advanced technology storage
• Rare Elements: Exotic materials for advanced construction

Colony Management

• Build on 6 different planet types (Terran, Industrial, Research, Mining, Fortress, Derelict)
• Construct 8+ building types with upgrade paths
• Manage population, morale, and defense

Fleet Operations

• Design custom ships with modular components
• Move fleets across galaxy coordinates (A3-91-X format)
• Engage in instant combat with detailed battle logs

Research & Technology

• Unlock technologies across 4 categories: Military, Industrial, Social, Exploration
• Build research facilities to accelerate progress
• Prerequisites system for complex tech trees

🔧 Development

Available Scripts

• npm run dev - Start development server with hot reload
• npm run test - Run test suite with coverage
• npm run test:watch - Run tests in watch mode
• npm run lint - Run ESLint code quality checks
• npm run db:migrate - Run database migrations
• npm run db:seed - Populate database with initial data
• npm run db:reset - Reset database to clean state

Code Quality

The project enforces strict code quality standards:

• ESLint configuration with Node.js and Jest rules
• Comprehensive error handling with custom error classes
• Structured logging with Winston and correlation IDs
• Input validation with Joi schemas
• Database transactions for data integrity

Testing Strategy

• Unit Tests: Individual functions and modules
• Integration Tests: API endpoints and database operations
• E2E Tests: Complete user workflows
• Coverage target: 80%+ for critical game systems

🎮 Game Tick System

The game runs on a configurable tick system:

• Default: 60-second intervals
• User groups: Players distributed across 10 processing groups
• Retry logic: 5 attempts with bonus tick compensation
• Real-time monitoring for administrators

🔌 Plugin Architecture

Extensible plugin system for game mechanics:

• Combat resolution plugins
• Event system plugins
• Resource calculation plugins
• Custom game rule implementations

📊 Admin Features

• Real-time game statistics dashboard
• Event creation and management tools
• Player administration and support
• System configuration with hot-reloading
• Performance monitoring and alerts

🔒 Security

• JWT authentication with separate admin/player tokens
• Rate limiting and CORS protection
• Input validation and SQL injection prevention
• Audit logging for all critical operations
• Environment-based configuration management

📈 Scalability

Designed to support 100-1000+ concurrent players:

• Connection pooling and query optimization
• Redis caching for frequently accessed data
• User group distribution for tick processing
• Comprehensive indexing strategy
• Performance metrics collection

🐳 Deployment

Docker support included:

• Development and production containers
• Docker Compose configurations
• Environment-specific builds
• Automated CI/CD pipeline ready

📝 API Documentation

• Player API: Authentication, colonies, fleets, research, events
• Admin API: System management, player administration, analytics
• WebSocket Events: Real-time game state updates
• Full API documentation available in /docs/api/

🤝 Contributing

1. Follow the existing code style and patterns
2. Write comprehensive tests for new features
3. Update documentation for API changes
4. Use conventional commit messages
5. Run npm run lint && npm test before committing

📄 License

Private - All rights reserved

---

Built with ❤️ for the post-collapse galaxy simulation community