Parabellum Hero

Rust CI/CD Pipeline License: MIT

Parabellum is an attempt to build a (yet another!) modern, fast, and open-source MMORPG inspired by the classic game Travian 3.x.

This project is for those who love the deep strategy and community of the original but want an alternative built on a modern tech stack. The goal is to create a lightweight, easy-to-deploy server that's completely free from pay-to-win mechanics.

The project is still in its early stages, but the foundations are solidifying every day. It's now at a point where contributions are very welcome to help shape the game.

PLAYABLE DEMO

HEADS UP! Parabellum is under heavy development and is mostly playable. Many core mechanics have been built, others are coming. It's possible to signup and have a decent game until founding a new village or conquering a new one, but it's not complete or full-featured yet, we're getting there. Check the roadmap and status below.

• Core Travian Experience: Replicate the core 80-90% of the game mechanics (building, resource management, troops, attacks, alliances).
• Fast, Robust & Lightweight: Use Rust to create a high-performance server that's easy for anyone to run. Code comes with unit and integration tests to ensure everything is working as expected.
• No "Pay-to-Win": This is a non-negotiable. This project is for the love of the game, not for predatory monetization.
• Modern Stack: Intentionally skipping outdated features like in-game forums or chats, assuming players will use modern tools like Discord.
• Open Source: Create a community-driven project that can be forked, modified, and learned from.

Want to get the server running locally? Here’s how.

Prerequisites:

• Rust (>= 1.85)
• Postgres 16.x
• Bun 1.x
• (optional, but much easier for deploy) Docker & Docker Compose
• sqlx-cli (run cargo install sqlx-cli --no-default-features --features postgres)

Steps:

1. Clone the repo:

   git clone https://github.com/andreapavoni/parabellum.git
   cd parabellum

2. Set up environment:

   # Copy the sample .env file
   cp .env.sample .env

   (You shouldn't need to modify this for local dev).

3. Start database:

   docker-compose up -d db

4. Create databases:

   # This sets up the dev AND test databases
   ./setup_db.sh

5. (optional) Seed game data:

   # Uses seed/default.json by default
   cargo run -p parabellum_server --bin parabellum-seed

   You can also pass a custom data file:

   cargo run -p parabellum_server --bin parabellum-seed -- seed/game.json

   The seeder supports multiple players and multiple villages per player. Root JSON shape:

   {
    "players": [
    {
    "username": "andrea",
    "email": "andrea@example.com",
    "password": "andrea",
    "tribe": "Roman",
    "villages": [
    {
    "template": "developed",
    "quadrant": "NorthEast",
    "buildings": [
    { "slotId": 39, "name": "RallyPoint", "level": 2 }
    ]
    }
    ]
    }
    ]
   }

   Use separate template files to keep village setups reusable, for example:

   • seed/default.json (players + village references)
   • seed/templates/developed.json (village defaults)
   • seed/templates/rusher.json (another village profile)

   Template files are loaded from seed/templates/<template>.json and merged with village overrides (slotId-based upsert for buildings. First village follows signup rules: it is always founded on a random unoccupied valley in the selected quadrant (explicit position is not allowed for the first village). Additional villages can either set an explicit position (must be free) or use random unoccupied valley selection with quadrant. If omitted, login defaults remain deterministic: email is <username>@example.com, password is <username>.

6. Install frontend dependencies:

   bun install

7. (optional) Run app in docker:

   docker-compose up -d app

8. (optional) Run tests:

   cargo test --release --

9. Run the server:

   cargo run --release

From now, you can go to http://localhost:8000 and see the progress.

The frontend is now a Preact + Vite SPA served by the Rust app, backed by JSON endpoints under /api/v1. Cargo builds the frontend bundle automatically through parabellum_web/build.rs; for standalone frontend verification you can also run:

bun run build:release

Parabellum persists game events and projects read models from those events.

• Dry-run replay: inspect event streams and replay windows without mutating read models.
• Full replay: apply events and rebuild read models for the selected target.

# default: --target all --mode dry-run --from 1
cargo run -p parabellum_server --bin parabellum-replay
# full replay for village projections only
cargo run -p parabellum_server --bin parabellum-replay -- --target village --mode full
# bounded window
cargo run -p parabellum_server --bin parabellum-replay -- --from 1000 --to 2000

The replay entrypoint is provided by the server runtime and is intended for maintenance/operations tasks in development or controlled environments.

Older databases created before automatic hero assignment may have players without heroes. Use the backfill command to append missing HeroCreated events through the normal event-sourced flow.

# dry-run: list players that would receive a hero
cargo run -p parabellum_server --bin parabellum-backfill-heroes
# execute: create one level-0 hero for each player missing one
cargo run -p parabellum_server --bin parabellum-backfill-heroes -- --execute

Resources view

Village overview

World map view

There's a DockerHub image, just use: andreapavoni/parabellum:latest. You can use docker-compose-prod.yml a a starting point. Then run it:

docker-compose -f docker-compose-prod.yml up -d

Here's a high-level tracker of what's working, what's in progress, and what's still to do.

• Core Architecture: A clean, command-based application structure.
• Database: Postgres persistence with SQLx adapters.
• Scheduled Actions: Event-driven scheduling and completion flow.
• Game Data: All static data for buildings, units, tribes, and smithy upgrades is defined.
• Player: Player registration.
• Village: Initial village founding.
• Resources: Passive resource generation (the "tick") based on building levels and server speed.
• Population: Population calculation.
• Building: Full command and job cycle for starting and completing construction.
• Unit Training: Full command and job cycle for training a queue of units. Only barracks at the moment.
• Research: Full command and job cycle for Academy and Smithy research.
• Battle: Core battle logic (attacker vs. defender calculation) is implemented.
• Attack Cycle: Full "Attack" -> "Battle" -> "Army Return" job chain.
• Battle Features: Ram/Catapult damage and resource bounty calculation.
• Merchants: Marketplace offers, sending resources between villages.
• Server Speed: Full support for different server speeds influencing times and stocks/merchants capacities.
• Building Upgrades/Downgrades: Upgrading/Downgrading buildings, also considering MainBuilding levels and server speed as well.
• Reinforcements: Sending troops to support other villages.
• Scouting: The "Scout" attack type (logic exists, but no command/job).
• Unit Training: support for all units types in their related buildings.
• Heroes: Hero model and basic bonus logic exists, but they are not yet integrated into armies or battles.
• Users and Auth: Login/register/logout, needs password recovery
• World Map bootsrap: Automatic bootstrap of the game map at first run.
• Settler Expansion: Training settlers, tracking culture points, founding new villages.
• Chief Expansion: Battle calculation for loyalty and conquest

API / UI: Getting the minimal viable views to navigate the game:

• Layout, basic navbar
• Login, Register
• Village Overview (Resources + Buildings)
  • Building queue
• Generic building (info + add/upgrade)
• Basic leaderboard
• Basic player profile page
• Special buildings (info + specific actions)
  • Unit training: Barracks, Stable, Workshop, etc...
  • Rally Point:
    • send troops
    • view troop movements (ongoing/incoming attacks/raids/reinforcements/army returns)
    • view reinforcements in own and other villages
    • release/recall reinforcements from/in other villages
  • Reports
    • troop movements (attack, raid, scout, reinforce)
    • marketplace
  • Academy (research units)
  • Smithy (upgrade units)
  • Merchant, Marketplace
    • Send resources to a village
    • Sell/buy resources
  • Heroes:
    • Complete integration into battles and reports
    • Lifecycle: complete integration with hero lifecycle
    • Oases conquering
  • Palace/Residence (train settlers, expansion slots, culture points)
  • Town Hall (small/big party)
  • Main Building (building downgrades)
  • Romans Horse Drinking Throught
  • Gauls Trappers: Build and apply traps lifecycle
• Map

• i18n System: builtin i18n support (refactor)
• Edit Player Profile: have a bare profile to show
• Messages
  • Player-Player
  • Alliance-Player
• Oases:
  • Capturing and managing oases (models exist, logic does not).
  • Resources bonus when conquered.
  • Resource production and spawn Nature army in free oases.
• Alliances: Creating and managing alliances.
• User Password recovery: using email? Switching to OAuth?
• End Game: Wonder of the World, Natars, etc.
• Admin UI: a minimal dashboard to manage the game.
• Help/Manual: to learn.
• More i18n: add translations for different languages.

The project is structured as a Cargo workspace with several distinct crates:

• parabellum_server: The main binary executable. This is the entry point that ties everything together.
  • Binary entrypoints live in parabellum_server/bin/:
    • parabellum (server runtime)
    • parabellum-seed (seed tool)
    • parabellum-replay (event replay tool)

These packages provide the necessary tools to make the system working. They provide data persistence, communication interfaces, and they can be changed or added independently.

• parabellum_web: The web delivery layer. It serves the JSON API, bearer-token auth endpoints (/api/v1/auth/token/* + /api/v1/auth/refresh), and the SPA shell/assets.
• parabellum_infra: The database layer. This provides the concrete implementation of the database repositories (using sqlx and Postgres).

These packages define the whole game engine. There aren't infrastructure details (like database, http server, etc...). Instead, there are static data (units, costs, times), game rules, validations, etc...

• parabellum_app: The application layer. This is the "brain" of the project. It defines commands, queries, and ports that orchestrate game use cases.
• parabellum_game: The core domain layer. This crate knows nothing about databases or web servers. It contains the pure game rules, models (Village, Army, Building), and logic (e.g., battle.rs).
• parabellum_types: Shared, simple data structures that are used by all other crates to avoid circular dependencies.

• Backend architecture overview: docs/ARCHITECTURE.md
• Frontend architecture overview: docs/FRONTEND_ARCHITECTURE.md
• API contract matrix: docs/api-contract-matrix.md
• Testing and error conventions: docs/TESTING_AND_ERROR_CONVENTIONS.md

Contributions are very welcome! Since the project is in the early stages, things are still very flexible.

1. Find something to work on:
   • Look at the ToDo list in the roadmap above.
   • Pick an In Progress item and help finish it.
   • Find a bug or a missing calculation.
   • Help improve documentation or add more tests.
2. Get in touch:
   • For now, the best way is to open an Issue on GitHub.
   • Describe what you'd like to work on or the bug you've found.
   • We can discuss the best approach there before you start coding.
3. Submit a Pull Request:
   • Create a PR with your changes, and we'll review it together!

Don't worry about "doing it wrong." The most important thing is to get involved!

This project wouldn't be possible without the incredible work done by the TravianZ project and Kirilloid's work on detailing the game mechanics.

Parabellum is open-source software licensed under the MIT License.

A pavonz joint. (c) 2023-2026.