🎮 Minesweeper Multiplayer (MM)

A competitive real-time multiplayer Minesweeper game where players race through checkpoints.

🎯 Game Concept

Checkpoint Progression

• 10 checkpoints to reach victory
• Clear a board → Promote to next checkpoint
• Hit a mine → Demote to previous checkpoint
• Safe checkpoints at 0, 3, 6 (can't fall below these)

Difficulty Escalation

Checkpoint	Difficulty	Grid	Mines
0-1	Easy	6×6	5
2-3	Medium	7×7	8
4-5	Hard	8×8	12
6-9	Expert	9×9	15

Match Types

• Ranked 1v1: MMR-based matchmaking, trophy stakes
• Unranked 4P: Casual 4-player races

🏗️ Architecture

mm-minesweeper/
├── packages/
│   ├── shared/          # Shared types, events, utilities
│   └── game-engine/     # Core Minesweeper logic (88 tests)
└── apps/
    └── server/          # Fastify + WebSocket backend

🚀 Quick Start

Prerequisites

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

1. Start Dependencies

docker-compose up -d

2. Install & Build

npm install
npm run build

3. Run Database Migrations

cd apps/server
npm run db:migrate

4. Start Server

npm run dev:server

Server will be available at:

• HTTP API: http://localhost:3000/api/v1
• WebSocket: ws://localhost:3000/ws

🔌 API Endpoints

Authentication

• POST /api/v1/players/register - Register new player
• POST /api/v1/players/login - Login and get JWT token

Player

• GET /api/v1/players/me - Get current player (auth required)
• GET /api/v1/players/:id - Get player profile
• GET /api/v1/players/:id/stats - Get player statistics
• GET /api/v1/players/:id/matches - Get match history

Leaderboard

• GET /api/v1/leaderboard - Get trophy leaderboard
• GET /api/v1/leaderboard/stats - Get leaderboard statistics

Health

• GET /health - Server health check

🎮 WebSocket Protocol

Client Events

Event	Description
find_match	Join matchmaking queue
cancel_find_match	Leave matchmaking queue
ready	Signal ready for match
first_click	First click on board
cell_reveal	Reveal a cell
cell_flag	Flag/unflag a cell
board_completed	Report board completion
reconnect	Reconnect to active match
heartbeat	Keep connection alive

Server Events

Event	Description
match_found	Match created, players joined
match_starting	Countdown to match start
match_started	Match has begun
board_ready	New board ready for player
player_promoted	Player advanced checkpoint
player_demoted	Player fell back checkpoint
player_disconnected	Opponent disconnected
match_ended	Match concluded, results
error	Error message

🧪 Testing

# Run all tests
npm test

# Run game engine tests only
npm run test -w @mm/game-engine

# Type check
npm run typecheck

📊 Current Status

✅ Completed (Phase 1 & 2)

• Seeded RNG for deterministic boards
• Board generation with first-click safety
• Complete Minesweeper game engine
• Match progression system
• Checkpoint/promotion/demotion logic
• Safe checkpoint enforcement
• WebSocket server with auth
• Matchmaking with MMR pairing
• Anti-cheat validation
• PostgreSQL persistence
• Redis live match state

🚧 Upcoming

• Frontend client
• Spectator mode
• Match replays
• Seasonal rankings
• Tournament system

📜 License

MIT