Open-source, fully onchain strategy games by BibliothecaDAO.
Play · Docs · Discord · X

Every move in Realms is a transaction on our own Starknet appchain: the contracts are the game, and the client draws what the chain says. One codebase runs every format. A game is a row in a persistent world, created with an immutable balance preset (config/source), not a separate deployment. This repository holds the games, their contracts and every service that runs them.

The rules of each are on docs.realms.party.

contracts/l3/world-native   Cairo contracts: the world and its rules
        │ signed player intents, randomness recorded in each play
        ▼
Madara sequencer            one appchain per shard (deploy/shard, deploy/athanor)
        │ blocks
        ▼
Herald (apps/herald)        folds confirmed blocks; streams snapshots and ordered diffs over one WebSocket
        │
        ▼
native fact store           packages/core: the client's one store of current game facts
        │
        ▼
three.js scenes + React UI  apps/game

Starknet mainnet holds what has value outside a game: the ledger (Blitz entries, Frontier withdrawals, prizes), MMR, LORDS and the collectibles (contracts/l2). Sign-in, the shard directory and launches are Cloudflare Workers.

Contributors start with AGENTS.md, the coding and review standard for the whole repo, and CONTRIBUTING.md.

You need Node.js 20.19 or later and pnpm 10.25. The contract checks and deploy scripts also use Bun.

git clone https://github.com/BibliothecaDAO/eternum.git
cd eternum
pnpm install --frozen-lockfile
pnpm run build:packages

The game client plays on the dev environment's shards: it signs in against them and lists their games. It needs your own Alchemy endpoint for Starknet mainnet in apps/game/.env.local (gitignored); without one, the dev server refuses to start.

echo 'VITE_PUBLIC_L2_RPC_URL=https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_9/<your-key>' > apps/game/.env.local
pnpm dev        # https://localhost:5173

The docs site: pnpm dev:docs (http://localhost:5173).

The world contracts need the Scarb and Starknet Foundry versions pinned in .tool-versions. On Linux (x86_64 or aarch64), this installs them in their own directory, leaving any other toolchain alone; the installer supports no other platform:

bash deploy/athanor/scripts/install-native-tools.sh "$HOME/.local/share/eternum-native-tools"
source "$HOME/.local/share/eternum-native-tools/env"
cd contracts/l3/world-native && scarb build

Their tests need a patched snforge (TOOLCHAIN.md), and bash contracts/l3/check-native.sh is the full check before a contract change lands. Running a shard of your own (Madara, Herald and the RPC) is covered in deploy/shard and deploy/athanor.

MIT