A project that converts FreeCiv from a turn-based game into a modern Real-Time Strategy (RTS) MMO, similar to Rise of Kingdoms or Tribal Wars.
This project includes a NestJS-based Control Plane that adapts the FreeCiv game into a Tick-Based architecture with concurrent event scheduling.
┌─────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ React/Next.js Dashboard Mobile/Web Client │
└────────────────────────┬────────────────────────────────────┘
│ REST / WebSockets / JSON-RPC
▼
┌─────────────────────────────────────────────────────────────┐
│ API Gateway (Orchestration & Gateway) │
│ NestJS (Fastify) - Auth, Billing, Economy, Ruleset │
└──────────────────────────────┬──────────────────────────────┘
│ Redis PubSub
▼
┌─────────────────────────────────────────────────────────────┐
│ Real-Time Engine │
│ ┌──────────────────┐ ┌────────────────────────────────┐ │
│ │ Tick Engine Core │ │ Freeciv C-Server Wrapper │ │
│ │ (scheduler, │ │ (TCP bridge, command │ │
│ │ resolver, │ │ translation, state sync) │ │
│ │ combat, event │ │ │ │
│ │ loop) │ │ │ │
│ └──────────────────┘ └────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
| Component | Description |
|---|---|
| Orchestrator | Manages the game server lifecycle (create, launch, stop, remove) with Docker |
| Tick Engine | Processes scheduled player events (build, move, combat) |
| Economy | In-game economy system with coins, gems, and Speed-Up items |
| C-Server Wrapper | Bridge between NestJS and the FreeCiv C server for dispatching commands |
FreeCiv/
├── freeciv-rts/ # NestJS control plane
│ ├── src/
│ │ ├── orchestrator/ # Server management (Docker)
│ │ ├── tick-engine/ # RTS tick engine
│ │ ├── economy/ # Economy and monetization
│ │ ├── c-server-wrapper/ # C server bridge
│ │ ├── prisma/ # Database service
│ │ └── redis/ # Distributed locks
│ ├── prisma/schema.prisma # Database models
│ ├── Dockerfile # Control plane Dockerfile
│ └── docker-compose.yml # PostgreSQL + Redis + App
│
├── packages/ # FreeCiv game components
│ ├── game-server/ # Game C server
│ ├── game-client/ # Web client
│ ├── game-proxy/ # WebSocket proxy
│ ├── server-manager/ # Legacy server management
│ ├── assets/ (blender, music) # Game assets
│ └── scripts/ # Build/deploy scripts
│
├── Roadmap.md # Architecture and roadmap document
└── README.md # This file
# Dependencies
cd freeciv-rts
npm install
# Database setup
DATABASE_URL="postgresql://user:pass@localhost:5432/freeciv" npx prisma generate
npx prisma migrate dev --name init
# Run development server
npm run start:devcd freeciv-rts
docker compose up -dPostgreSQL, Redis, and the NestJS control plane start up on port 3000.
| Technology | Purpose |
|---|---|
| NestJS 11 | Backend framework |
| Fastify | HTTP engine |
| Prisma 7 | Database ORM |
| PostgreSQL | Primary database |
| Redis (ioredis) | Cache and Pub/Sub |
| Docker (dockerode) | Container management |
| TypeScript | Development language |
| Phase | Component | Status |
|---|---|---|
| 1 | Server management and Ruleset Engine | Done |
| 2 | Tick Engine (Turn to RTS conversion) | Done |
| 3 | Economy and Speed-Up system | Done |
| 4 | Command translation to C-Server | Done |
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/orchestrator/servers |
Create a new server |
| GET | /api/v1/orchestrator/servers |
List servers |
| POST | /api/v1/orchestrator/servers/:id/launch |
Launch a Docker container |
| POST | /api/v1/orchestrator/servers/:id/stop |
Stop a server |
| POST | /api/v1/economy/speedup |
Apply a Speed-Up item |
- ServerInstance — game server instances managed with Docker
- Ruleset — configurable game parameters (tick rate, speed multiplier, unit costs)
- PlayerState — player balance, currencies, progress on each server
- TimeEvent — scheduled events (build, move, combat) for tick processing
AGPL v3 - derived from the Freeciv-web project