AI-Generated Documentation - This README was created by analyzing the codebase and may not be exhaustive or perfectly accurate.
A sophisticated multiplayer game platform built as a microservices architecture. Designed to host and manage multiplayer games (currently featuring TNT Tag) with dynamic server orchestration, matchmaking, social features, and player management.
┌─────────────────┐
┌──────│ Matchmaker │◄──── Players
│ │ Service │
│ └────────┬────────┘
│ │
┌──────────────┐ │ ┌──────▼──────┐
│ Proxy │ │ │ Discovery │
│ Service │◄── Players │ │ Service │
└──────┬───────┘ │ └──────┬──────┘
│ │ │
│ ┌──────▼──────┐ │
│ │ Game Server │◄───────┘
└─────────────►│ (Minestom) │ Direct communication
└──────────────┘
┌─────────────────┐
│ Social │◄────────── Player parties & sessions
│ Service │
└─────────────────┘
Note: The Proxy service loadbalances players to game servers. Game servers communicate directly with Discovery, Matchmaker, and Social services.
| Service | Description | Ports | Notes |
|---|---|---|---|
| Discovery | Server orchestration, container management, server registration | 9393 (HTTP), 50052 (Hermes) | Game servers register here |
| Game | TNT Tag game implementation using Minestom | 25565 | Communicates directly with services |
| Matchmaker | Player matchmaking & queue management | 8080 | Handles queue & match logic |
| Social | Party management, sessions, real-time notifications | 8080 | Party invites, sessions |
| Proxy | Velocity proxy for player routing | - | Loadbalances players to game servers |
- Language: Java 25
- Build: Gradle (Kotlin DSL)
- Container: Docker, Kubernetes
- Database: PostgreSQL 17
- Storage: MinIO (S3-compatible)
- Game Server: Minestom
- HTTP: Javalin
- Serialization: Kryo, Jackson
# Start infrastructure
docker-compose up -d
# Build all services
./gradlew build
# Run individual services
./gradlew :discovery:server:run
./gradlew :social:server:rungame-service/
├── discovery/ # Service discovery & orchestration
│ ├── common/ # Shared utilities
│ ├── api/ # API definitions
│ ├── server/ # Service implementation
│ └── client/ # Client library
├── game/ # Game implementations
│ ├── core/ # Core game engine
│ └── tnttag/ # TNT Tag game
├── matchmaker/ # Matchmaking service
├── social/ # Social features & sessions
│ ├── common/
│ ├── client/
│ └── server/
├── nodes/ # Node services
│ ├── proxy/ # Velocity proxy
│ └── lobby/ # Lobby server
└── common/ # Shared utilities
├── minestom-base/
└── pack-server/
POST /api/v1/request/{playlist}- Request game serverGET /api/v1/server- List all servers
GET /api/v1/party/{owner}- Get partyPUT /api/v1/party/{owner}- Create partyDELETE /api/v1/party/{issuer}- Disband partyPUT /api/v1/party/{owner}/invite/{joining}- Invite playerPUT /api/v1/party/{joining}/join/{owner}- Join partyWS /api/v1/party/notifications- Party notifications
- Proxy → Game Servers: Routes players to available game servers (Velocity)
- Game Servers ↔ Discovery: Server registration, heartbeat, health checks
- Game Servers ↔ Matchmaker: Queue status, match results
- Game Servers ↔ Social: Player sessions, party state
| Variable | Description |
|---|---|
DOCKER_URL |
Docker socket (e.g., unix:///var/run/docker.sock) |
KUBERNETES_URL |
Kubernetes API URL |
KUBERNETES_TOKEN_FILE |
Kubernetes auth token |
# Build all
./gradlew build
# Build specific service
./gradlew :discovery:server:build
# Run tests
./gradlew test
# Create distribution ZIPs
./gradlew distZip- Java 25 JDK required
- Docker for container management
- PostgreSQL 17 for data persistence
- MinIO for object storage
MIT