A massively multiplayer real-time pixel war game where players join clans to conquer a pixelated world map.

Open setup.html in your web browser - Beautiful step-by-step installation guide!

# Linux/Mac
bash install.sh

# Windows
install.bat

npm run install-all
npm start

Then open: http://localhost:5173

📖 Having issues? See TROUBLESHOOTING.md or START_HERE.md

• 🎯 Real-time gameplay: Place 1 pixel every 30 seconds
• ⚔️ Clan warfare: Join or create clans with unique colors
• 🎮 Custom wars: Create your own war with customizable parameters
• 📊 Live statistics: Real-time tracking of territory, momentum, and activity
• 🔗 Invitation system: Share wars and clan invites via unique codes
• ⚡ Optimized performance: Chunked canvas loading, WebSocket updates, Redis caching
• 📱 Responsive design: Works on desktop and mobile browsers

# Install dependencies
npm install

# Start Redis
docker-compose up -d

# Start development servers
npm run dev

Visit http://localhost:5173 to play!

• Node.js + TypeScript - Server runtime
• Express - Web framework
• Socket.io - Real-time WebSocket communication
• Redis - In-memory data store (no database!)
• JWT - Authentication

• React + TypeScript - UI framework
• HTML5 Canvas - High-performance map rendering
• Zustand - State management
• Vite - Lightning-fast build tool
• Socket.io Client - Real-time updates

WorldWar/
├── packages/
│   ├── backend/              # Node.js API server
│   │   ├── src/
│   │   │   ├── config/      # Redis configuration
│   │   │   ├── routes/      # API endpoints
│   │   │   ├── services/    # Business logic
│   │   │   ├── websocket/   # WebSocket handlers
│   │   │   └── index.ts     # Server entry
│   │   └── package.json
│   │
│   └── frontend/            # React web app
│       ├── src/
│       │   ├── api/        # API client
│       │   ├── components/ # React components
│       │   ├── pages/      # Page components
│       │   ├── stores/     # Zustand stores
│       │   └── hooks/      # Custom hooks
│       └── package.json
│
├── docs/                    # Documentation
│   ├── INSTALLATION.md     # Setup guide
│   ├── DEVELOPMENT.md      # Dev guide
│   └── API.md              # API documentation
├── docker-compose.yml       # Redis service
└── README.md

• Installation Guide - Setup and deployment
• Development Guide - Architecture and workflow
• API Documentation - REST and WebSocket API

• Place 1 pixel every 30 seconds
• Claim neutral pixels or convert enemy pixels
• Cannot change your own clan's pixels

• Duration: 1-168 hours (1 hour to 7 days)
• Map Sizes: Small (1500x1000), Medium (3000x1500), Large (4500x2250)
• Clans: 2-16 clans per war
• Adjacency Rule: (Optional) Pixels must be adjacent to clan territory

• Clan with most territory at war end wins
• Live tracking of:
  • Territory percentage
  • Momentum (pixels/minute)
  • Efficiency (conversion rate)
  • Active players

• Node.js 18+ (Download)
• Redis 7+ (Download)
• npm 9+

# 1. Clone repository
git clone <repository-url>
cd WorldWar

# 2. Install dependencies
npm install

# 3. Start Redis (Docker)
docker-compose up -d

# 4. Copy environment files
cp packages/backend/.env.example packages/backend/.env
cp packages/frontend/.env.example packages/frontend/.env

# 5. Start dev servers
npm run dev

Frontend: http://localhost:5173 Backend: http://localhost:3000

npm run build
npm start

1. Register a user account
2. Create a new war with 2+ clans
3. Open multiple browser windows/tabs
4. Join different clans in each window
5. Start the war
6. Place pixels and watch real-time updates!

• WebSocket broadcasts pixel placements to all connected clients
• Automatic stats refresh every 10 seconds
• Instant visual feedback

• Map divided into 64x64 pixel chunks
• Only loads visible chunks
• Optimized for large maps (up to 4500x2250 pixels)

• Server-side enforcement (30s default)
• Redis-based with TTL
• Client receives countdown updates

• Optional rule requiring pixels adjacent to clan territory
• Prevents isolated pixel spam
• First pixel always allowed

• War replay/timelapse system
• Permanent user profiles & statistics
• War seasons with global leaderboards
• Custom map shapes (not just rectangles)
• Power-ups and special pixels
• Mobile PWA with touch controls
• Discord bot integration
• War templates and presets

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

MIT License - feel free to use for your own projects!

Redis connection error?

redis-cli ping  # Should return PONG

Port already in use?

# Change PORT in packages/backend/.env
# Change port in packages/frontend/vite.config.ts

Module not found?

rm -rf node_modules packages/*/node_modules
npm install

• Open an issue on GitHub
• Check the documentation
• Review closed issues for solutions

Built with ❤️ for the pixel art community