Skip to content

About

Turn-based FreeCiv reimagined as a real-time MMO - NestJS player control with tick engine and Docker orchestration

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

FreeCiv MMO

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.


System Overview

┌─────────────────────────────────────────────────────────────┐
│                      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)            │  │                                │  │
│  └──────────────────┘  └────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Core Components

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

Project Structure

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

Quick Start

# 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:dev

With Docker Compose

cd freeciv-rts
docker compose up -d

PostgreSQL, Redis, and the NestJS control plane start up on port 3000.


Technologies

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

Roadmap

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

API Endpoints

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

Database Models

  • 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

License

AGPL v3 - derived from the Freeciv-web project

About

Turn-based FreeCiv reimagined as a real-time MMO - NestJS player control with tick engine and Docker orchestration

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages