    ╔═══════════════════════════════════════════════════════════════════╗
    ║                                                                   ║
    ║   ██████╗ ███████╗ █████╗ ██╗     ███╗   ███╗███████╗            ║
    ║   ██╔══██╗██╔════╝██╔══██╗██║     ████╗ ████║██╔════╝            ║
    ║   ██████╔╝█████╗  ███████║██║     ██╔████╔██║███████╗            ║
    ║   ██╔══██╗██╔══╝  ██╔══██║██║     ██║╚██╔╝██║╚════██║           ║
    ║   ██║  ██║███████╗██║  ██║███████╗██║ ╚═╝ ██║███████║           ║
    ║                                                                   ║
    ║   ███████╗████████╗███████╗██████╗ ███╗   ██╗██╗   ██╗███╗   ███╗║
    ║   ██╔════╝╚══██╔═╝██╔════╝██╔══██╗████╗  ██║██║   ██║████╗ ████║║
    ║   █████╗     ██║   █████╗  ██████╔╝██╔██╗ ██║██║   ██║██╔████╔██║║
    ║   ██╔══╝     ██║   ██╔══╝  ██╔══██╗██║╚██╗██║██║   ██║██║╚██╔╝██║║
    ║   ███████╗   ██║   ███████╗██║  ██║██║ ╚████║╚██████╔╝██║ ╚═╝ ██║║
    ║   ╚══════╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝     ╚═╝║
    ║                                                                   ║
    ║           The Onchain Strategy Game of the Realmverse              ║
    ╚═══════════════════════════════════════════════════════════════════╝

An open-source, fully onchain strategy game built on Starknet with the Dojo engine.

Conquer hex territories. Harvest resources. Build armies. Forge alliances. Win seasons.

Play Now · Documentation · Discord · Twitter

</div>

What is Eternum?

Eternum is the foundational game of the Realms World ecosystem — a fully onchain strategy game where every action lives on Starknet. You claim Realms, manage resources across a hex-based world map, raise armies, trade with other players, and compete in seasonal competitions for $LORDS tokens.

Everything is onchain. Contracts are the game. The client is just a window.

🔥 Blitz

Blitz is the competitive tournament format — shorter, faster, deadlier.

Compact hex maps, compressed timelines
All realms start with the same 9 resources and infinite labor
MMR-ranked matchmaking (Elo-like system)
Points from capturing hyperstructures, essence rifts, camps, and exploration
Seasons and series with $LORDS prize pools

Think of Eternum as the sandbox. Blitz is the arena.

Architecture

eternum/
├── client/                    # Frontend applications
│   └── apps/
│       ├── game/              # Main game client (React + Three.js)
│       ├── landing/           # Landing page
│       ├── game-docs/         # Documentation site (Vocs)
│       └── balancing/         # Game balancing tools
├── contracts/                 # Cairo/Dojo smart contracts
├── packages/                  # Shared libraries & SDK
│   ├── core/                  # @bibliothecadao/eternum (core SDK)
│   ├── provider/              # Game contract interactions
│   ├── react/                 # React hooks and components
│   ├── torii/                 # Onchain data querying
│   └── types/                 # Shared type definitions
├── config/                    # Configuration & deployment scripts
└── docs/                      # Architecture notes & internal docs

Tech Stack

| Layer | Tech | | ------------------- | ---------------------------------------------------- | | Blockchain | Starknet (Cairo) | | Game Engine | Dojo v1.0.4 | | Frontend | React, Vite, Three.js | | Onchain Queries | Torii | | Account Abstraction | Cartridge Controller | | Package Manager | pnpm + Bun |

Getting Started

Prerequisites

Dojo v1.0.4
Node.js (v18+)
pnpm v9.12.3
Bun

Setup

# 1. Install Dojo
curl -L https://install.dojoengine.org | bash

# 2. Install pnpm
npm install -g pnpm

# 3. Clone and install
git clone https://github.com/BibliothecaDAO/eternum.git
cd eternum
pnpm install

# 4. Build shared packages
pnpm run build:packages

# 5. Start development server
pnpm dev

Common Commands

| Command | Description | | --------------------- | ---------------------------- | | pnpm dev | Start game dev server | | pnpm dev:docs | Start docs dev server (Vocs) | | pnpm build:packages | Build shared packages |

Running Contracts Locally

See the Dojo book for running a local Katana node and deploying contracts with Sozo.

cd contracts
sozo build
sozo migrate

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Key entry points for developers:

Contracts → contracts/ — Cairo game logic
SDK → packages/ — shared libraries (package docs)
Game Client → client/apps/game/ — React/Three.js frontend
Architecture → docs/ — internal design notes

Links

| | | | --------------------- | -------------------------------------------------------- | | 🎮 Play | eternum.realms.world | | 📖 Docs | docs.realms.world | | 🌐 Realms World | realms.world | | 💬 Discord | discord.gg/realmsworld | | 🐦 Twitter | @lootrealms | | 🏛️ BibliothecaDAO | @BibliothecaDAO |

License

MIT

Eternum

Install / Use

README