Eternum is the foundational game for Realms World - a living digital ecosystem that evolves through player interaction. It serves as both a game and an open platform.
A high-stakes game played in seasons where players forge their own path to victory. On an infinite hexagonal map, players:
- Build resource stockpiles
- Train troops
- Explore the map
- Trade resources
- Form alliances
- Compete for dominance
Access requires a Season Pass minted from Loot Realms NFTs. Players use $LORDS tokens to trade in the game's free market on Starknet.
Eternum provides the core infrastructure for building games and applications. It includes:
- Core functional systems
- Fungible resource framework
- Extensible architecture
Click to expand
Eternum is built as an Autonomous World with two core principles:
- Radical Openness
- No gatekeepers or central control
- Anyone can build and contribute
- Open source and extensible
- Persistence
- Fully onchain game state
- Immutable seasons
- Player-driven evolution
The platform is designed to be forked and extended by the community, serving as the foundation for an expanding ecosystem of games and applications.
- 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
The Eternum ecosystem is composed of several core packages, each serving a specific role in the development and operation of the game and platform:
The foundation of the Eternum SDK, providing essential building blocks for applications on Starknet & Dojo. Includes the main provider implementation, core data structures, utility functions (such as hex map and resource management), and specialized managers for game logic. Enables seamless blockchain integration and protocol interaction.
A comprehensive, type-safe interface for interacting with Eternum game contracts. Manages all game transactions (army, battle, trading, guild, structure, resource, and quest operations), contract calls, and event handling. Features a smart promise queue that batches and optimizes transaction execution for performance and reliability.
A collection of shared React hooks and stores designed for Eternum game applications. Provides easy access to game state, player data, and contract interactions within React components. Simplifies frontend development by offering hooks for realms, resources, and player-owned data, ensuring smooth integration with the Eternum backend.
Enables advanced querying of on-chain Eternum data. Supports both gRPC-based queries (via the torii-client) and direct SQL queries (via the sql folder), allowing developers to fetch, filter, and aggregate game data efficiently. Ideal for analytics, dashboards, and any application requiring rich data access.
A centralized collection of type definitions and constants used throughout the Eternum ecosystem. Ensures type safety and consistency across all packages, covering entities, resources, transactions, and system properties. Essential for maintaining a robust and reliable codebase.
| Package | Description |
|---|---|
| Core | Foundation for Eternum apps: provider, data structures, utilities, and managers. |
| Provider | Type-safe interface for all game contract interactions and transaction management. |
| React | Shared React hooks and stores for easy frontend integration with Eternum game state. |
| Torii | Advanced on-chain data querying via gRPC and SQL for analytics and dashboards. |
| Types | Centralized type definitions and constants for consistency and type safety. |
- @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
- Install Dojo:
curl -L https://install.dojoengine.org | bash- Install pnpm:
npm install -g pnpm- Install project dependencies:
pnpm install- Build shared packages:
pnpm run build:packagesThis is the main game application for Eternum, built with React, TypeScript, and Vite.
To run the game locally:
- Navigate to the game client directory:
cd client/apps/game - Make a copy of
.env.local.sampleand rename it to.env.local - Update the following environment variables in
.env.localbased on your target environment:VITE_PUBLIC_TORII="http://127.0.0.1:8080"VITE_PUBLIC_NODE_URL="http://127.0.0.1:5050"
- Run
pnpm run devto start the development server
Development of Eternum is open-source. If you would like to contribute comment on an open issue.
pnpm dev- Start game development serverpnpm dev:docs- Start documentation development serverpnpm dev:landing- Start landing page development server
pnpm build- Build game clientpnpm build:docs- Build documentationpnpm build:landing- Build landing pagepnpm build:packages- Build shared packages
pnpm test- Run all testspnpm lint- Run lintingpnpm format- Format codepnpm format:check- Check code formatting
Eternum supports multiple deployment environments:
| Environment | Description |
|---|---|
| Local | For development and testing |
| Slot | Staging environment |
| Sepolia | Public testnet |
| Mainnet | Production environment |
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:localTo 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:sepoliaThis project is licensed under the MIT License. See the LICENSE file for more information.
