NationCraft

Production-quality plugin-driven Telegram nation-simulation game.

NationCraft is a persistent online multiplayer strategy game where players become the ruler of a country inside a parallel world. Each world is fully independent — when one fills up, the server automatically creates another. The entire game is text-driven and delivered through a Telegram bot, while all business logic runs on a FastAPI backend.

The codebase follows Clean Architecture: a domain core with no framework coupling, an application layer of services, an infrastructure layer with concrete persistence and security implementations, and presentation layers (FastAPI REST API + aiogram Telegram bot) that depend only on services, never on infrastructure.

Highlights

• Clean Architecture with strict dependency direction (domain ← application ← infrastructure ← presentation).
• Plugin system with stable Plugin API, auto-discovery, dynamic enable/disable, and zero core modifications.
• Extension system with hookable formulas (production, combat, population, etc.).
• Async event bus with prioritized handlers, wildcard subscriptions, and error isolation.
• Tick engine with ordered phases (production → research → population → events → missions → …) — plugins can subscribe to any phase.
• Configurable everything — resources, buildings, units, technologies, events, missions, countries all defined in YAML.
• REST API with JWT (access + refresh), Argon2id password hashing, rate limiting, audit logging.
• aiogram 3.x Telegram bot with inline keyboards, paginated lists, breadcrumb navigation, context-aware menus, and message editing.
• PostgreSQL + Redis with proper indexing, foreign keys, soft deletes, and audit logs.
• Localization (i18n) with English and Persian (RTL) catalogs.
• Tests at every layer (unit, integration, API, plugin, simulation).
• Production Docker Compose for one-command deployment.

Quick start

Option A — Docker Compose (recommended for production)

# 1. Configure environment.
cp .env.example .env
#   - Edit TELEGRAM_BOT_TOKEN, SECRET_KEY, ADMIN_IDS.

# 2. Launch everything (Postgres, Redis, API, worker, bot).
make up
# or: docker-compose up -d --build

# 3. Apply migrations and seed game data.
docker-compose exec api python -m nationcraft.cli initdb --worlds --data

Visit http://localhost:8000/docs for the interactive API docs, and message your Telegram bot to start playing.

Option B — Single-process launcher (great for local dev)

main.py runs the API, tick worker, and Telegram bot concurrently in one process — no Docker, no Postgres, no Redis required for quick testing (it falls back to SQLite automatically when DATABASE_URL points at a SQLite file).

# 1. Install the package in editable mode (Python 3.11+ required).
pip install -e .

# 2. Configure environment.
cp .env.example .env
#   - Set SECRET_KEY to a 32-byte random hex string.
#   - Set TELEGRAM_BOT_TOKEN from @BotFather.
#   - Set DATABASE_URL to postgres or sqlite+aiosqlite:///nationcraft.db
#   - Set REDIS_URL (or leave default if no Redis).

# 3. Initialize the database (migrations + seed worlds + load game data).
python main.py --initdb

# 4. Run the entire game (API + worker + bot) in one process.
python main.py --log-format console

Other useful invocations:

python main.py --only api           # just the FastAPI server
python main.py --only worker        # just the tick engine
python main.py --only bot           # just the Telegram bot
python main.py --migrate            # apply migrations, then start
python main.py --only api --reload  # dev mode with auto-reload
python main.py --host 127.0.0.1 --port 9000

When running all components in one process, the API uses a single uvicorn worker (no pre-fork). For production with many concurrent players, prefer docker-compose so the API can scale horizontally.

Repository layout

nationcraft/
├── alembic/                    # Database migrations
├── deploy/                     # Deployment manifests
├── docs/                       # All project documentation
├── game/data/                  # Static game data (YAML)
│   ├── resources.yaml
│   ├── buildings.yaml
│   ├── units.yaml
│   ├── techs.yaml
│   ├── countries.yaml
│   ├── events.yaml
│   └── missions.yaml
├── locales/                    # i18n catalogs (en, fa)
├── plugins/                    # Plugin packages (auto-discovered)
│   └── space_race/
├── extensions/                 # Lightweight hook-based extensions
│   └── hardcore_economy.py
├── src/nationcraft/
│   ├── api/                    # FastAPI presentation layer
│   ├── application/            # Services & DTOs (use cases)
│   ├── bot/                    # aiogram Telegram bot
│   ├── core/                   # Cross-cutting: config, events, plugins, extensions, i18n, tick
│   ├── domain/                 # Entities, value objects, enums, repository protocols
│   ├── infrastructure/         # DB, repositories, cache, security, observability
│   └── workers/                # Tick worker entrypoint
├── tests/                      # unit / integration / api / plugin / simulation
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
└── Makefile

Documentation

Comprehensive documentation lives in docs/:

Document	Purpose
Game Design Document	Game systems, economy, combat, progression
Software Architecture Document	Clean architecture, layers, dependencies
API Reference	Every endpoint with request/response examples
Plugin Development Guide	How to write, package, and ship plugins
Extension Guide	Override game formulas via hooks
Configuration Guide	Every YAML schema and env var
Database ERD	Full schema diagram and relationships
Deployment Guide	Production deployment & ops
Tick Engine	How the game loop works
Localization Guide	Adding new languages
Contributing Guide	How to contribute

License

AGPL-3.0-or-later.

Developers

Yasin Aryanfard Contact:

• Telegram: @ysnrfd & @ysnrfd3
• GitHub: ysnrfd & SMNRFD
• Huggingface: ysn-rfd

Amir Hossein Contact:

• Telegram: @Amir_hosseim
• GitHub: amirSAV