Getting Started

Prerequisites
- Dojo onchain game engine v1.0.4
- Node.js
- pnpm v9.12.3
- Bun
Setup
Install Dojo via:
curl -L https://install.dojoengine.org | bash
Eternum uses a pnpm workspace and bun for scripts to allow easy npm packages to be created. Install pnpm:
npm install -g pnpm
Install project dependencies:
pnpm install
Build shared packages:
pnpm run build:packages
Development Scripts
Development
pnpm dev
- Start game development serverpnpm dev:docs
- Start documentation development serverpnpm dev:landing
- Start landing page development server
Building
pnpm build
- Build game clientpnpm build:docs
- Build documentationpnpm build:landing
- Build landing pagepnpm build:packages
- Build shared packages
Testing & Linting
pnpm test
- Run all testspnpm lint
- Run lintingpnpm format
- Format codepnpm format:check
- Check code formatting
Contract Deployment
Eternum supports multiple deployment environments:
Environment | Description |
---|---|
Local | For development and testing |
Slot | Staging environment |
Sepolia | Public testnet |
Mainnet | Production environment |
Deploying to Local
Before deploying to any environment, confirm that you have a .env.{environment}
file in the contracts/common
directory, as well as in the client/apps/game
directory.
To deploy and run the game locally:
# Start local game contracts
pnpm run contract:start:local
Deploying to Sepolia
To deploy the contracts to Sepolia testnet, run these commands in order:
- Deploy game contracts:
pnpm run game:migrate:sepolia
- Deploy season pass contracts:
pnpm run seasonpass:deploy:sepolia
- Deploy season resources contracts:
pnpm run seasonresources:deploy:sepolia
- Update TOML configuration:
pnpm run toml:update:sepolia
- Start the indexer:
pnpm run indexer:start:sepolia
- Deploy game configuration:
pnpm run config:deploy:sepolia
Environment Variables
For local development, create a file called .env.local
in the client repository and add the following:
VITE_PUBLIC_MASTER_ADDRESS="0x127fd5f1fe78a71f8bcd1fec63e3fe2f0486b6ecd5c86a0466c3a21fa5cfcec"
VITE_PUBLIC_MASTER_PRIVATE_KEY="0xc5b2fcab997346f3ea1c00b002ecf6f382c5f9c9659a3894eb783c5320f912"
VITE_PUBLIC_ACCOUNT_CLASS_HASH="0x07dc7899aa655b0aae51eadff6d801a58e97dd99cf4666ee59e704249e51adf2"
VITE_PUBLIC_FEE_TOKEN_ADDRESS=0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7
VITE_PUBLIC_TORII="http://127.0.0.1:8080"
VITE_PUBLIC_NODE_URL="http://127.0.0.1:5050"
VITE_PUBLIC_GAME_VERSION="v1.0.0-rc0"
VITE_PUBLIC_GRAPHICS_DEV=false
VITE_PUBLIC_TORII_RELAY="/ip4/127.0.0.1/udp/9091/webrtc-direct/certhash/uEiDry6d-bDv3UdIS6L9VMugoiZnfwqOeXyFWm6jgKf7aTw"
VITE_SOCIAL_LINK=http://bit.ly/3Zz1mpp
VITE_PUBLIC_CHAIN=local
VITE_PUBLIC_SLOT="eternum-prod"
VITE_PUBLIC_VRF_PROVIDER_ADDRESS="0x0"
VITE_PUBLIC_CLIENT_FEE_RECIPIENT=0x045c587318c9ebcf2fbe21febf288ee2e3597a21cd48676005a5770a50d433c5
VITE_PUBLIC_MOBILE_VERSION_URL=https://next-m.eternum.realms.world
This file is subject to change, please keep an eye on the repository for potential updates.
Project Structure
- Client - React apps built with Vite
- Contracts - Cairo/Dojo smart contracts
- Game contracts
- Season Pass contracts
- Season Resources contracts
- Packages - Shared libraries
- Config - Configuration and deployment scripts
Core Dependencies
- @dojoengine/react - React integration for Dojo
- @dojoengine/recs - Entity Component System
- @cartridge/controller - Game controller integration
- Starknet.js v6.23.1 - StarkNet interaction
- Vite - Frontend build tool
Stack

- Contracts: built using the Dojo framework. This leverages the ECS model, allowing us to build quick and ship fast. It revolves around 3 units: Entities, Components (called Models in Dojo) and Systems (more about this in the Dojo book).
- Client: our client is built using React with Typescript. We leverage Dojo by using DojoJS
- Eternum SDK: our SDK contains most notably the getter and setter of the configuration of Eternum, the EternumProvider and most of the constants/types of the world that needed to be transcribed to Typescript.
- Torii: Dojo's indexer, optimized for that particular framework and well integrated into the stack. From our client, we have a gRPC subscription set up through DojoJS and recs to events. Events are fired in the contracts as a way for the indexer to know what's going on in the world. Every time an entity is created, updated, or deleted, an event is fired which updated Torii's record of the world.
- DojoJS and recs: DojoJS is the SDK that allows easy integration of a Dojo app into your client/node backend. Recs are DojoJS's way of exposing the state of the world to the client. This is done via queries to the Recs state using a simple query language, which doesn't support complex queries yet (e.g. joins, gt, lt, etc...).