file: docs/pages/index.mdx
meta: {
  "layout": "landing"
}

import { HomePage } from "vocs/components";

<HomePage.Root>
  <div
    style={{
  position: "absolute",
  inset: 0,
  zIndex: -10
}}
  >
    <img
      src={`/images/covers/0${Math.floor(Math.random() * 8) + 1}.png`}
      alt="Eternum Cover"
      style={{
      width: "100%",
      height: "100%",
      objectFit: "cover"
    }}
    />
  </div>

  {" "}

  <img src="/images/logos/eternum_words_logo.svg" alt="Eternum Logo" />

  <HomePage.Description>
    Eternum is a decentralized, open-source, and community-driven 4x MMO game built on the Dojo framework.
  </HomePage.Description>

  <HomePage.Buttons>
    <HomePage.Button href="/overview/introduction" variant="primary">
      Get started
    </HomePage.Button>

    <HomePage.Button href="https://eternum.realms.world" variant="outline">
      Play Now
    </HomePage.Button>
  </HomePage.Buttons>
</HomePage.Root>



---

file: docs/pages/development/client.mdx
meta: {}

# React Client

## Run the dev server

From the root of the project, run:

Easy method:

```bash
./scripts/client.sh
```

Manual method:

```bash
pnpm i && pnpm dev
```

The client requires environment variables to be set. See the [Environment Variables](client/.env.sample) page for more
information.

## Project Structure

### Elements

* Small reusable react UI components

### Components

* Stateful react components composed of Elements. This is where all the onchain state should be stored.

### Modules

* Collection of components composed into Modules

### Containers

* Locations where Modules are composed into a full page

### Layouts

* Collection of containers composed into a full layout

## useDojo Hook

The `useDojo` hook is a core part of the Dojo framework that provides access to essential game functionality, account
management, and network interactions.

### Usage

```tsx
import { useDojo } from "@/hooks/context/dojo-context";
function GameComponent() {
  const { account, network, masterAccount } = useDojo();
  // ... your game logic
}
```

### Features

#### Account Management

The hook provides comprehensive wallet and account management capabilities:

* **Burner Wallet Creation**: Create temporary wallets for players
* **Account Selection**: Switch between different burner wallets
* **Account Listing**: View all available burner wallets
* **Master Account Access**: Access to the game's master account
* **Deployment Status**: Track wallet deployment status

#### Network Integration

Access to network configuration and setup results for interacting with the Starknet blockchain.

#### Game Setup

Provides access to all initialized game systems, components, and world configurations.

### Requirements

The hook must be used within a `DojoProvider` component and requires the following environment variables:

* `VITE_PUBLIC_MASTER_ADDRESS`
* `VITE_PUBLIC_MASTER_PRIVATE_KEY`
* `VITE_PUBLIC_ACCOUNT_CLASS_HASH`

### Return Value

The hook returns an object containing:

* `setup`: Complete Dojo context including game systems and components
* `account`: Account management functions and state
* `network`: Network configuration and setup results
* `masterAccount`: The master account instance

### Example

```tsx
function GameUI() {
  const { account } = useDojo();
  return (
    <div>
      <p>Current Account: {account.account.address}</p>
    </div>
  );
}
```

## Eternum provider

Wrapper around the DojoProvider, which itself is a wrapper around a generic Starknet provider, an API to easy interact
with your contract’s API via the RPC. Each layer of abstraction adds its own set of functionalities, with the Eternum
Provider mainly providing easy access to all the system calls that our systems expose (create\_army, etc…)

## Offchain messages

You can use offchain messages to store information in the indexer, but it is not persisted onchain. Some examples of use
cases for this are in-game messages. Refer to
[this code](https://github.com/BibliothecaDAO/eternum/blob/1490dfcf513d72f51e5a84138be743d774338caf/client/src/ui/modules/chat/InputField.tsx#L50)
for an example of how to use offchain messages

# State Management with Recs

Recs allow you to query the state of the world and subscribe to changes in the world. It is the recommended way to
manage state in the client.

```tsx
const structureAtPosition = runQuery([HasValue(Position, { x, y }), Has(Structure)]);
```

This line of code will run a query against the local state of the browser and return all the structures that are at the
position `{ x, y }`. This does not execute any call to Torii as the local state is already synced with the latest
updates.

This part of the code in `client/src/dojo/setup.ts` is where the local state is initialized and synced.

## Subscribing to changes

To subscribe to changes in the world, you can use the `useEntityQuery` hook. This hook will return the entity that
matches the query and update it if it changes.

```tsx
const allRealms = useEntityQuery([Has(Realm)]);
```

## Getting the value of your components

After you have run a query, you can get the value of your components using the `getComponentValue` function.

```tsx
const realm = getComponentValue(Realm, entityId);
```

The entityId is the poseidon hash of all the keys of the component you want to get. This can be an easier way to get
your component than using a query if you already know all the keys.

### Getting a component from an entity

If you have an entityId, you can get a component from it using the `getComponent` function.

```tsx
const realm = getComponentValue(Realm, getEntityIdFromKeys([entityId]));
```

The previous line of code is equivalent to:

```tsx
const entity = runQuery([Has(Realm), HasValue(Keys, [entityId])]);
const realm = getComponentValue(Realm, Array.from(entity)[0]);
```

# Extending the client

## Adding a new component

You will need to add your component to the `contractComponents.ts` file. This will ensure that the component is synced
with the state of the world and will provide the types for the component.

## Adding a new system

You will need to add your system logic to the `sdk/packages/eternum/src/provider/index.ts` file and then use it in the
`createSystemCalls.ts` file. This will ensure that the system is called with the correct arguments and will provide the
types for the system.

## Optimistic updates

You can use optimistic updates to update the local state without waiting for the transaction to be included in a block.
This is useful to provide a better user experience by updating the UI immediately.

```ts
private _optimisticDestroy = (entityId: ID, col: number, row: number) => {
	const overrideId = uuid();
	const realmPosition = getComponentValue(this.setup.components.Position, getEntityIdFromKeys([BigInt(entityId)]));
	const { x: outercol, y: outerrow } = realmPosition || { x: 0, y: 0 };
	const entity = getEntityIdFromKeys([outercol, outerrow, col, row].map((v) => BigInt(v)));
	this.setup.components.Building.addOverride(overrideId, {
		entity,
		value: {
		outer_col: outercol,
		outer_row: outerrow,
		inner_col: col,
		inner_row: row,
		category: "None",
		produced_resource_type: 0,
		bonus_percent: 0,
		entity_id: 0,
		outer_entity_id: 0,
		},
	});
	return overrideId;
};
```

You can use the `uuid` function to generate a unique overrideId. Remember to return the overrideId so you can later
delete it after the transaction is included in a block. It's good practice to remove the override, however because of a
delay between the transaction being included in a block and Torii syncing, you might have a split second where the
override is removed and the Recs being updated. This will cause your component (i.e. a building) to appear then
disappear for a second before reappearing.



---

file: docs/pages/development/collaborators.mdx
meta: {}

import Collaborators from "@/components/Collaborators";

# Collaborators

<Collaborators />



---

file: docs/pages/development/contracts.mdx
meta: {}

# Contracts

## Rules of thumb

* Note that every field you add in a model will raise the storage cost of each transaction that modifies the model.
* Try to make models as small as possible, and re-use existing models as much as possible, every model and system that
  you add raises the size of the CASM, and there is a limit to the size of a declared contract on Starknet.
* Keep systems stateless. Store your game state in models.
* When implementing a new game logic, you will need to keep in mind that the game already has physics implemented, such
  as weight, position, movement, speed, etc. If creating something that needs to have any of this logic, re-use
  components so everything stays logical.

## Models

### Keys

Use the `ID` type alias for keys that require a unique identifier.

### Model design

entity\_id: u32

### Implementations

Where possible make traits for the models so they are stateless for unit testing.

Always use generate trait where possible to minimise code.

```rust
#[generate_trait]
```

### Adding a model

```rust
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Structure {
    #[key]
    entity_id: ID,
    category: StructureCategory,
    created_at: u64
}
```

To test this model, you need to add it to the `contracts/src/utils/testing/world.cairo` file so it can be instantiated
in the tests.

## Event models

If you need some data to be available in the client, but it doesn't need to be stored onchain, you can use an event
model.

```rust
#[derive(Introspect, Copy, Drop, Serde)]
#[dojo::event]
#[dojo::model]
pub struct ExampleEvent {
    #[key]
    id: ID,
    #[key]
    event_id: EventType,
	my_data_field: u8
}
```

## Adding a system

Design systems like this in the directory

* SystemName
  * system\_name.cairo
  * tests.cairo

`system.cairo` should include the implementation of the system like this.

Things to note:

* Interface at top of File
* use of `super::IBuildingContract` to minimise imports and make it clear where the interface is defined.

```rust
#[dojo::interface]
trait IBuildingContract<TContractState> {
    fn create(
        entity_id: ID,
        building_coord: s1_eternum::models::position::Coord,
        building_category: s1_eternum::models::resource::production::building::BuildingCategory,
        produce_resource_type: Option<u8>
    );
}

#[dojo::contract]
mod production_systems {
    use s1_eternum::alias::ID;
    use s1_eternum::models::{
        resource::resource::{Resource, ResourceCost}, owner::Owner, hyperstructure::HyperStructure,
        order::Orders, position::{Coord, Position, PositionTrait, Direction},
        buildings::{BuildingCategory, Building, BuildingImpl},
        production::{Production, ProductionRateTrait}, realm::{Realm, RealmImpl}
    };

    #[abi(embed_v0)]
    impl BuildingContractImpl of super::IBuildingContract<ContractState> {
        fn create(
            world: IWorldDispatcher,
            entity_id: ID,
            building_coord: Coord,
            building_category: BuildingCategory,
            produce_resource_type: Option<u8>,
        ) {
        }
    }
}
```

To test this system, you need to add it to the `contracts/src/utils/testing/world.cairo` file so it can be instantiated
in the tests.



---

file: docs/pages/development/getting-started.mdx
meta: {
  "layout": "docs"
}

# Getting Started

<img src="/images/covers/eternum-documentation.png" alt="Eternum Development" className="w-full rounded-lg my-6" />

## Prerequisites

* [Dojo onchain game engine](https://book.dojoengine.org) v1.0.4
* [Node.js](https://nodejs.org/)
* [pnpm](https://pnpm.io/) v9.12.3
* [Bun](https://bun.sh/)

## Setup

Install Dojo via:

```bash
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:

```bash
npm install -g pnpm
```

Install project dependencies:

```bash
pnpm install
```

Build shared packages:

```bash
pnpm run build:packages
```

## Development Scripts

### Development

* `pnpm dev` - Start game development server
* `pnpm dev:docs` - Start documentation development server
* `pnpm dev:landing` - Start landing page development server

### Building

* `pnpm build` - Build game client
* `pnpm build:docs` - Build documentation
* `pnpm build:landing` - Build landing page
* `pnpm build:packages` - Build shared packages

### Testing & Linting

* `pnpm test` - Run all tests
* `pnpm lint` - Run linting
* `pnpm format` - Format code
* `pnpm 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:

```bash
# Start local game contracts
pnpm run contract:start:local
```

### Deploying to Sepolia

To deploy the contracts to Sepolia testnet, run these commands in order:

1. Deploy game contracts:

```bash
pnpm run game:migrate:sepolia
```

2. Deploy season pass contracts:

```bash
pnpm run seasonpass:deploy:sepolia
```

3. Deploy season resources contracts:

```bash
pnpm run seasonresources:deploy:sepolia
```

4. Update TOML configuration:

```bash
pnpm run toml:update:sepolia
```

5. Start the indexer:

```bash
pnpm run indexer:start:sepolia
```

6. Deploy game configuration:

```bash
pnpm run config:deploy:sepolia
```

## Environment Variables

For local development, create a file called `.env.local` in the client repository and add the following:

```bash
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-eternum-mobile.realms.world

```

This file is subject to change, please keep an eye on the repository for potential updates.

## Project Structure

* [Client](https://github.com/BibliothecaDAO/eternum/tree/main/client) - React apps built with Vite
  * [Game](https://github.com/BibliothecaDAO/eternum/tree/main/client/apps/game) - Main game client with Three.js
    interface
  * [Landing](https://github.com/BibliothecaDAO/eternum/tree/main/client/apps/landing) - Landing page
  * [Game Docs](https://github.com/BibliothecaDAO/eternum/tree/main/client/apps/game-docs) - Game documentation
  * [Balancing](https://github.com/BibliothecaDAO/eternum/tree/main/client/apps/balancing) - Game balancing tools
* [Contracts](https://github.com/BibliothecaDAO/eternum/tree/main/contracts) - Cairo/Dojo smart contracts
  * Game contracts
  * Season Pass contracts
  * Season Resources contracts
* [Packages](https://github.com/BibliothecaDAO/eternum/tree/main/packages) - Shared libraries
  * [Core](https://github.com/BibliothecaDAO/eternum/tree/main/packages/core) - Eternum SDK
  * [React](https://github.com/BibliothecaDAO/eternum/tree/main/packages/react) - React hooks and components
* [Config](https://github.com/BibliothecaDAO/eternum/tree/main/config) - Configuration and deployment scripts

## Core Dependencies

* [@dojoengine/react](https://www.npmjs.com/package/@dojoengine/react) - React integration for Dojo
* [@dojoengine/recs](https://www.npmjs.com/package/@dojoengine/recs) - Entity Component System
* [@cartridge/controller](https://www.npmjs.com/package/@cartridge/controller) - Game controller integration
* [Starknet.js](https://www.npmjs.com/package/starknet) v6.23.1 - StarkNet interaction
* [Vite](https://vitejs.dev/) - Frontend build tool

## Stack

<img src="/images/covers/08.png" alt="Eternum Technology Stack" className="w-full rounded-lg my-6" />

* [Contracts](/development/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](/development/client): our client is built using React with Typescript. We leverage Dojo by using DojoJS
* [Eternum SDK](/development/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](https://book.dojoengine.org/toolchain/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](https://github.com/dojoengine/dojo.js?tab=readme-ov-file#contributing-to-dojojs): 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...).



---

file: docs/pages/development/index.mdx
meta: {
  "layout": "docs"
}

# Development

* [Getting Started](/development/getting-started)
* [Client](/development/client)
* [Contracts](/development/contracts)
* [SDK](/development/sdk)
* [Collaborators](/development/collaborators)



---

file: docs/pages/development/llm.mdx
meta: {
  "title": "LLM"
}

# LLM

These docs are experted at [https://eternum-docs.realms.world/llm.txt](https://eternum-docs.realms.world/llm.txt) for
consumption by the LLM.



---

file: docs/pages/development/sdk.mdx
meta: {}

# SDK

## Compiling

From the root of the project, run:

```bash
pnpm i && pnpm run build:packages
```

## Structure

This 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.

Everything considered as client agnostic should be in there. The main reason for this separation is to be able to re-use
this logic in any other project that uses Typescript, e.g. new mobile client, data analytics app, etc.



---

file: docs/pages/mechanics/achievements.mdx
meta: {}

# Achievements & Quests

*WIP, update next week !*



---

file: docs/pages/mechanics/agents.mdx
meta: {}

# Agents

*WIP, update next week !*



---

file: docs/pages/mechanics/key-concepts.mdx
meta: {
  "title": "Key Concepts",
  "description": "The foundational mechanics of Eternum"
}

# 🔑 Key Concepts

<img src="/images/covers/07.png" alt="Eternum Key Concepts" className="w-full rounded-lg my-6" />

This section outlines the core mechanics and systems that form the foundation of Eternum's gameplay.

## Realms

* **Limited Assets**: 8,000 unique and irreplaceable Realms serve as the foundation of Eternum, each has the ability to
  freely mint a Season Pass.
* **Settling**: Players must burn a Season Pass to settle their Realm in the game world.
* **Starting Materials**: Each newly settled Realm begins with a set of starting materials.
* **Progression Path**: Realms can upgrade from Settlements → Cities → Kingdoms → Empires, unlocking additional
  buildable hexes and defensive army slots.
* **Resource Production**: Each Realm can produce 1-7 different resources based on the original Realms NFT metadata.
* **Wonders**: Realms with Wonders have a 20% production bonus and share this bonus with all Realms and Villages in a 12
  tile radius.
* **Hardcore Gameplay**: If a Realm’s defenses crumble, it can be claimed by another player—transferring gameplay rights
  to the conqueror.

## Villages

* **Accessible Entry**: Villages can be established around settled Realms, offering a simple entry system for new
  players
* **Scaling**: Up to 6 Villages per Realm, allowing for 48,000 Villages in Season 1
* **Limited Production**: Produce materials at 50% the rate of Realms and only have access to 1 resource type each
* **Parent Realm**: Each Village is tied to a parent Realm and will pay bridging fees if moving materials out of the
  game
* **Troop Restrictions**: Villages may only receive tokenized troops from their parent Realm, they cannot buy or be sent
  troops from any other source
* **Simple Progression**: Villages have a limited upgrade path from Settlement to City
* **Casual Gameplay**: Villages can be raided, but can’t be claimed by other players.

## Materials

* **Materials Categories**:
  * **Food**: (Wheat, Fish) - essential for production, troop movement, and construction.
  * **Resources**: 22 different resource types, distributed based on rarity across both Realms and Villages.
  * **Troops**: Units with unique properties that can be assigned to armies.
  * **Donkeys**: Required for moving materials around the world, essential for logistics.
  * **Labor**: A new material in S1, allows players to build and produce in 'simple mode', acquired through burning
    resources.
  * **Ancient Fragments**: Found in game, critical for the construction of Hyperstructures.
* **ERC20 Compatibility**: All materials (except Labor) can be traded freely and bridged out as ERC20 tokens through
  Realms.

## Buildings

* **Construction Modes**: Two building systems available - Standard (resource-efficient) and Simple (labor-focused).
* **Building Types**:
  * **The Keep**: Central structure automatically constructed when settling, provides baseline population capacity.
  * **Resource Buildings**: Specific buildings for each of the 22 resources, only requiring food to construct.
  * **Economic Buildings**: Includes Farms, Fishing Villages, Worker Huts, Storehouses, and Markets.
  * **Military Buildings**: Nine different buildings for producing three tiers of each troop type.
* **Placement & Population**: Buildings require buildable hexes and population capacity, with more unlocked as Realms
  and Villages are upgraded.

## Production

* **Production Modes**: Like buildings, production can be done in Standard (resource-intensive) or Simple (food and
  labor) mode.
* **Production Types**:
  * **Food**: The only resources (Wheat, Fish) that can be produced without inputs.
  * **Resources**: Require combinations of other resources (standard) or labor (simple).
  * **Labor**: Produced by burning resources in the Keep, used for simple mode construction and production.
  * **Troops**: Essential for exploration and warfare, with higher tiers requiring lower tier troops as inputs.
  * **Donkeys**: One-time-use transport, consumed after a single journey.

## World Map

* **Exploration System**: The world begins shrouded in mystery, with only the six Banks visible at season start;
  adjacent hexes are revealed when settling, and armies can explore to reveal new areas.
* **Biomes**: 16 unique biome types procedurally generated across the map, each affecting combat effectiveness and troop
  movement.
* **Movement & Stamina**: Armies move using stamina (regenerating at +20 per Eternum Day), with costs varying by biome
  and troop type; Knights, Crossbowmen, and Paladins each have different maximum stamina capacities.
* **Exploration Mechanics**: Exploring costs 30 stamina per hex and reveals that area permanently to all Lords;
  exploring armies may discover resources or encounter world structures and agent armies.

## Military

<img src="/images/covers/04.png" alt="Eternum Military" className="w-full rounded-lg my-6" />

* **Army Composition**: Armies consist of a single troop type and tier (Knights, Crossbowmen, or Paladins).
* **Troop Tiers**: T1, T2, and T3 troops with increasing combat strength.
* **Combat Factors**: Battles resolved based on army damage, stamina modifiers, and biome effects.
* **Army Types**:
  * **Field Armies**: Deploy onto the world map for exploration and conquest.
  * **Guard Armies**: Deployed to defense slots to protect structures.
* **Stamina System**: Armies recover +20 stamina daily, with 30+ stamina needed for full combat effectiveness.
* **Biome Effects**: Each troop type has advantages (+30% damage), disadvantages (-30% damage), or no change (0%) in
  specific biomes.
* **Raiding Mechanics**: Armies can attempt to steal resources from structures without defeating defenders.
  * Success depends on the raiding army's damage relative to the combined guard armies.
  * Undefended structures can be raided without casualties.

## Tribes

Tribes are player-formed organizations enabling cooperation and coordination. They can be made public (open to all) or
private (invitation only) and allow players access to tribe-only features. Tribes are an early form of social structures
within Eternum and rely on player-driven interactions including arrangements of alliances and declarations of war.

## Victory Conditions

Eternum's seasonal gameplay culminates in victory through the accumulation of victory points earned through the
construction and ownership of Hyperstructures. However, there are various achievement paths, with players earning
recognition and rewards for various actions within the Season.



---

file: docs/pages/mechanics/prize-pool.mdx
meta: {}

import { table } from "@/components/styles";

# 💰 Prize Pool

## Overview

In Season 1 of Eternum, there are four prize categories with a total of:

* 1,000,000 $LORDS tokens
* 100,000 $STRK tokens

> **Note:** All Season 1 prizes will be distributed manually by the development team (except for the agent rewards which
> are collected directly in-game). Future seasons will implement automated distribution through game contracts, aligning
> with decentralized gaming principles.

## Prize Categories

### 1. Victory Prizes

**Total: 300,000 $LORDS + 50,000 $STRK**

These prizes are awarded to top-performing tribes based on victory points. Additionally, 2.5% of all $LORDS bridging
volume is collected as a fee and added to the prize pool, further increasing the total rewards available.

#### How to Earn Victory Points

Players can earn victory points by:

* Contributing resources and labor to hyperstructure construction
* Holding shares in completed hyperstructures to accumulate emitted victory points

#### Distribution

Once a player triggers the end of the game (or the game contract breaks), a snapshot of tribes, their members, and the
victory point leaderboard is taken. Tribes will then be ranked by the cumulative number of victory points of their
players. The top 10 tribes receive prizes based on this allocation:

<div style={table.container}>
  <div style={table.wrapper}>
    <table style={table.table}>
      <thead style={table.tableHead}>
        <tr>
          <th style={table.headerCell}>Rank</th>
          <th style={table.headerCell}>Allocation</th>
        </tr>
      </thead>

      <tbody>
        <tr style={table.tableRow}>
          <td style={table.cell}>1st Place</td>
          <td style={table.cell}>30%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>2nd Place</td>
          <td style={table.cell}>18%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>3rd Place</td>
          <td style={table.cell}>12%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>4th Place</td>
          <td style={table.cell}>9%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>5th Place</td>
          <td style={table.cell}>7%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>6th Place</td>
          <td style={table.cell}>6%</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>7th & 8th Place</td>
          <td style={table.cell}>5% each</td>
        </tr>

        <tr style={table.tableRow}>
          <td style={table.cell}>9th & 10th Place</td>
          <td style={table.cell}>4% each</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

#### Individual Distribution

Within each tribe:

* Tribe Leader: 30% of tribal allocation (regardless of their victory points)
* Other Members: 70% split proportionally based on victory points contribution to the tribal total

### 2. Achievement Prizes

**Total: 300,000 $LORDS**

Players earn achievement points by completing quests—tracked inside your Cartridge profile, and accessible via your
Cartridge wallet in-game. At the end of the season, this prize pool will be split proportionally amongst all players
based on the number of achievement points they have accumulated.

> **Note:** Achievement details, requirements, and point allocations will be withheld until the game begins to prevent
> planned farming and extractive behaviors. Check the [Achievements section](/mechanics/achievements) for updates when
> this information becomes available.

### 3. Daydreams Agent Prizes

**Total: 250,000 $LORDS + 25,000 $STRK**

#### Agent Rewards

Each agent on the world map carries 10-35 $LORDS, obtainable through:

* Collaboration (persuasion via chat)
* Combat victory

#### Special Achievement

25,000 $STRK will be distributed to the first 100 players who complete the 'Nexus-6' achievement by defeating 10 agent
armies.

### 4. Eternum Arts & Emissaries Prizes

**Total: 150,000 $LORDS + 25,000 $STRK**

Awarded to players or groups making exceptional cultural, artistic, or creative contributions to Eternum. These awards
can be given during or after the game at the developers' discretion.

> **Note:** For more information, join our [Discord community](https://discord.gg/KJff5Ecp).

## Unused Prize Distribution

If any prizes remain unallocated at the end of the game and prize distribution phase:

* Unused $LORDS will be distributed through the veLORDS protocol
* Unused $STRK will be retained by developers for future use



---

file: docs/pages/mechanics/tribes.mdx
meta: {}

# 👥 Tribes

Tribes are player-formed organizations enabling cooperation and coordination. They can be made public (open to all) or
private (invitation only) and allow players access to tribe-only features. Tribes are an early form of social structures
within Eternum and rely on player-driven interactions including arrangements of alliances and declarations of war.

## Formation & Membership

* Any player can create a tribe
* Set tribe name
* Set to public or private
* If private, send invites to player

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/create-guild.gif" alt="Create Guild" />

  <em>Flow to create tribe</em>
</div>



---

file: docs/pages/mechanics/victory.mdx
meta: {}

import { ETERNUM_CONFIG } from "@/utils/config";
import {
  HyperstructureInitializationShardsTable,
  HyperstructureConstructionCostTable,
  HyperstructurePointsTable,
  getTotalHyperstructureCompletionPoints,
  HYPERSTRUCTURE_POINT_MULTIPLIER,
} from "@/components/HyperstructureTable";
import { formatNumberWithCommas } from "@/utils/formatting";

# 👑 Victory

<img src="/images/covers/07.png" alt="Troops Moving Across Eternum" className="w-full rounded-lg my-6" />

## Victory Points

Ultimate victory in Eternum is measured by Victory Points (VP), earned exclusively through Hyperstructures. When a
single player’s total VP reaches the season-defined threshold, they unlock the ability to End Season, immediately
halting all further gameplay actions and cementing the final standings. Thus, the race to build, seize, and defend
Hyperstructures is the decisive path that ultimately closes the chapter on each season of Eternum.

## Activating Foundations

Each Hyperstructure is unique, requiring varying quantities of all 22 resources (and Labor) for completion. To activate
a Hyperstructure Foundation, all **{
  formatNumberWithCommas(ETERNUM_CONFIG().hyperstructures.hyperstructureInitializationShardsCost.amount)} Ancient
Fragments** must be deposited into the structures's balance, and then the owner of the mine must explicitly activate the
foundation to begin construction. Upon activation, the exact quantity required for each resource is randomly determined
within predefined minimum and maximum ranges shown below:

<HyperstructureInitializationShardsTable />

<HyperstructureConstructionCostTable />

*Note: In addition to these resources, all Hyperstructures require a fixed contribution of 50,000,000 units of labor to
complete construction.*

## Construction Victory Points

The Lord initiating the Hyperstructure construction determines whether contributions can be made by all Lords (public)
or restricted to members of their tribe (private). Contributions may be made directly from Realms or Villages without
requiring donkeys for transport. As Lords contribute to the Hyperstructure, they are awarded with a proportional
allocation of Victory Points. A total of **{formatNumberWithCommas(getTotalHyperstructureCompletionPoints())}** are
available to claim throughout the construction process.

## Accumulation Victory Points

Separately, and in addition to the victory points awarded at completion, the owner of the Hyperstructure begins to
accumulate
**{formatNumberWithCommas(Number(ETERNUM_CONFIG().hyperstructures.hyperstructurePointsPerCycle)/HYPERSTRUCTURE_POINT_MULTIPLIER)}
victory points** for every second the structure remains under their control. These accumulating victory points can be
shared among multiple Lords through a customizable share split, allowing the owner to distribute glory and reward
cooperation. If a Hyperstructure is claimed by another Lord, future accumulated victory points are redirected to the new
owner, who may similarly decide on sharing arrangements.

## Total Victory

Victory points earned through construction contributions or accumulation cannot be lost once awarded. The first player
to reach
**{formatNumberWithCommas(Number(ETERNUM_CONFIG().hyperstructures.hyperstructurePointsForWin)/HYPERSTRUCTURE_POINT_MULTIPLIER)}
total victory points** unlocks the ability to select the ‘End Season’ option, concluding the current game season.

<HyperstructurePointsTable />



---

file: docs/pages/mechanics/world-structures.mdx
meta: {}

# 💠 World Structures

## Hyperstructures

Hyperstructures are colossal edifices constructed atop ancient foundations hidden across Eternum, representing
monumental achievements and symbols of dominance in the game world. Lords must uncover and claim Hyperstructure
Foundations through exploration and combat, then invest substantial quantities of resources, labor, and ancient
fragments to reconstruct these majestic towers. Successfully completing and controlling Hyperstructures is the primary
path to victory in Eternum, making them ultimate strategic targets for ambitious Lords and powerful tribes alike.

<img src="/images/buildings/construction/hyperstructure.png" width="800" />

### Hyperstructure Foundations

These ancient, indestructible platforms are primarily scattered within the ring of Banks that surround the centre of the
map. There is a chance of discovering a Hyperstructure Foundation each time an army explores an unrevealed hex,
calculated using the following formula:

```
Discovery Chance = (0.975^x × y) - (z × 0.001)
```

Where:

* **x** = the number of hexes from the centre of the map
* **y** = the base chance of finding a Hyperstructure Foundation on the central hex (4%)
* **z** = the number of Hyperstructure Foundations already discovered

For example, if you're exploring a hex 100 tiles from the center and 5 foundations have already been discovered:

```
Discovery Chance = (0.975^100 × 4) - (5 × 0.001)
                 = (0.079 × 4) - 0.005
                 = 0.316 - 0.005
                 = 0.311 or 31.1%
```

The result of this function means that Hyperstructure Foundations are generally only able to be found within 300 tiles
of the centre of the map. As more are found, the chance of finding another diminishes and makes it even less likely to
find one further from the centre. Lords are therefore incentivised to explore early in the season to discover these key
components for victory.

Hyperstructure Foundations and Hyperstructures both have four defense slots to deter attacks from rival Lords. However,
like other world structures they are not able to maintain any field armies.

## Fragment Mines

Fragment Mines are rare, ancient nodes scattered throughout the unexplored hexes of Eternum. They produce valuable
ancient fragments, a vital resource needed for constructing Hyperstructures. Once discovered by an exploring field army,
a Fragment Mine must first be claimed by defeating its resident bandit forces. Only then can Lords begin extracting the
mysterious shards hidden within. Each mine contains a finite number of ancient fragments and will permanently cease
production when depleted.

<img src="/images/buildings/construction/fragment-mine.png" width="800" />

The chance of discovering a Fragment Mine when exploring an unrevealed hex is static at 1 in 150, or 0.67%. Mines can
contain between 300,000 and 3 million ancient fragments in incremental amounts (i.e. 300k, 600k, 900k…). It will take
some time for the full amount of ancient fragments to be produced by the structure, and the more that the mine contains,
the longer it will take. Lords will need to ensure that their mines are adequately defended from rivals, however they
only have one defense slot to support a guard army.

## Quest Tiles

*WIP, update next week !*



---

file: docs/pages/overview/bridging.mdx
meta: {}

import { Callout } from "vocs/components";

# Bridging in Materials

*WIP, update next week !*



---

file: docs/pages/overview/controller.mdx
meta: {}

import { importantNote } from "@/components/styles";

***

title: Cartridge Controller description: Using the Cartridge Controller in Eternum

***

# Cartridge Controller

The Cartridge Controller is a gaming-focused smart contract wallet that makes Web3 gaming accessible and transactionless
via Session Keys. You must have a controller to play Eternum. To find out more about the controller, read their
documentation [here](https://docs.cartridge.gg/controller/overview).

<img src="/images/screenshots/controller.png" alt="Controller" width="300" className="mx-auto" />

## Using the Controller in Eternum

If you are playing with a Village, you can play Eternum purely using the controller, However, to use Season Passes and
**$LORDS**, you will need to transfer them to your controller from Starknet using your ArgentX or Braavos wallet.

To use the controller, you can either log in or sign up when starting Eternum. To create a controller, simply input a
username and sign up.

<img src="/images/screenshots/controller-signup.png" alt="Controller" width="300" className="mx-auto" />

There are multiple ways to securely sign up:

* **Passkey**: Passkeys are a modern and secure way to authenticate users without passwords. They use public key
  cryptography and are stored by platform authenticators such as Face ID, Touch ID, or password managers like Bitwarden
  or 1Password.
* **Metamask**: Connect using your MetaMask wallet.
* **Rabby**: Connect using your Rabby wallet.
* **Discord**: Connect using your Discord account.
* **Wallet Connect**: Connect using a wide range of wallets.

<div style={importantNote.container}>
  <h3 style={importantNote.title}>⚠️ IMPORTANT NOTE</h3>

  <p style={importantNote.content}>
    If you are choosing Passkey on a Windows PC that does not have Bluetooth functionality, you will need to use a
    password manager to set up your controller. There is a known issue in which Windows will ask for a Windows Hello or
    external security key (USB) that wasn't used in the controller setup, preventing you from being able to sign in.
  </p>
</div>

Once this is complete, you will be able to 'Create Session'. This enables all of the game functions in a transactionless
session.

## Transfer Season Pass to Controller

Transfer a season pass to your controller easily [here](https://empire.realms.world/season-passes). Connect your
controller by selecting the controller icon located at the top of the page and select the passes to transfer.

<div className="flex justify-center">
  <img src="/images/logos/controller-icon.png" alt="Controller Icon" width="60" />
</div>

## Controller Key Features

### Simple and Secure

* Passwordless authentication using Passkeys for one-click onboarding
* Self-custodial embedded wallets that put players in control
* Built-in security features to protect player assets

### Designed for Seamless Gameplay:

* Session keys eliminate transaction popups during gameplay
* Secure transaction delegation lets games submit actions on behalf of players
* Free transactions through the Cartridge Paymaster so players focus on playing

### Supported Platforms and Passkey Backup

Passkeys are well-supported across modern platforms. You can use them with device authenticators directly or pair them
with a mobile device using the QR flow. For those without device authenticators, several password managers like
Bitwarden (free), 1Password, and Dashlane support Passkeys.

#### Backing Up Your Passkey

* Apple devices: Passkeys are backed up along with your keychain in iCloud.

* Android devices: Passkeys are backed up with your Google account.

* Windows devices: Passkeys are created and managed as part of your Windows account.

#### Using Controller Across Devices

Currently, Controller availability across devices depends on how the Passkey was created. Some platforms automatically
synchronize them across devices for seamless use. For cross-platform usage (e.g., Apple and Android), synchronization
might not be available. For now, we recommend using a Password Manager or the QR flow to support this configuration.
Multi-credential support is coming soon to enhance device compatibility.

Should you have any issues with the controller or require support, you can join the Cartridge Discord
[here](https://discord.gg/cartridge).



---

file: docs/pages/overview/disclaimer.mdx
meta: {}

import { formatNumberWithSpaces } from "@/utils/formatting";
import { ETERNUM_CONFIG } from "@/utils/config";
import { Callout } from "vocs/components";
import { HYPERSTRUCTURE_POINT_MULTIPLIER } from "@/components/HyperstructureTable";

# Disclaimer and Risk Acknowledgment

<Callout type="danger">
  Important Disclaimer – Please Read Carefully <br />
  By participating in Eternum, you fully acknowledge and accept the following terms and conditions.
</Callout>

## Immutable Contracts

Eternum is governed entirely by **immutable** smart contracts. Once deployed, the game’s rules and mechanics **cannot be
altered, updated, or reversed** by the developers, the DAO, or any other party. These smart contracts have **not** been
audited. Players should fully understand the implications of interacting with the system and assess the risks involved.

## Risk of Loss

All transactions and gameplay actions in Eternum are **final**. There are no mechanisms for refunds, reversals, or
compensation. You acknowledge the **risk of loss of funds** and accept that you bear sole responsibility for any
financial impact incurred.

A season of Eternum concludes when a single player achieves the required
**{formatNumberWithSpaces(Number(ETERNUM_CONFIG().hyperstructures.hyperstructurePointsForWin)/HYPERSTRUCTURE_POINT_MULTIPLIER)}**
Victory Points and clicks the "End Season" button. At this point:

### ⚠️ SEASON END CRITICAL INFORMATION

When the season ends, **ALL in-game actions are DISABLED** except:

* transfer materials
* deposit resource arrivals
* retrieve LP positions
* cancel market orders
* bridge materials out of the game

1. **48-Hour Withdrawal Window (starts immediately when "End Season" is clicked)**

   * Starting from the exact moment the season ends, you have **48 hours** to bridge out **ALL $LORDS** tokens and
     bridgeable materials from your Realms' balance

2. **After 48 Hours**

   * Any remaining **$LORDS** tokens and **Materials** will be **permanently locked**
   * These assets **CANNOT** be recovered under any circumstances

3. **Score Registration**
   * Players have **4 days** to register their scores
   * Registration is **MANDATORY** to be eligible for prizes
   * While registration has a deadline, prize claiming does not

Please refer to the documentation for detailed instructions on the bridging process during active gameplay.

## No Recourse

By participating in Eternum, you waive all rights to claims or recourse against the developers, the DAO, or any other
associated entities for any losses or disputes arising from your participation in the game.

## Acknowledgment of Terms

Participation in Eternum constitutes your agreement to these terms, as well as all other terms and conditions outlined
in the game’s documentation.



---

file: docs/pages/overview/entry.mdx
meta: {
  "title": "Game Entry & Participation",
  "description": "How to join and participate in Eternum seasons"
}

# Game Entry & Participation

## Season Access

### Realms NFT Holder Entry <img src="/images/ring_pass.png" alt="Season entry" width="300" className=" float-right" />

Realms NFT holders have the exclusive benefit of free entry into each season of Eternum through the minting of Season
Passes. Each Season Pass is unique to the Realm it was minted from and allows the Season Pass holder to initiate a
settling transaction to enter the game. To do this, Lords must first transfer the Season Pass to their Cartridge Wallet.

* Mint your pass [here](https://empire.realms.world/mint)

### Non-Realm Holder Entry

#### Marketplace

Should a Realm NFT holder decide not to use their Season Pass, they can transfer it or sell it on the
[Season Pass Marketplace](https://empire.realms.world/trade), providing avenues for non-Realm holders to acquire Season
Passes to participate in the game.

#### Villages

Villages are modest outposts that can be established around settled Realms, offering an accessible entry point into
Eternum. Villages have some restrictions, but offer a low-cost taste of Eternum gameplay to newcomers while also acting
as an avenue for established players to expand their production. Each Realm can support up to six surrounding Villages,
allowing for up to 48,000 Villages in Season 1.

For detailed information about Villages, including settling mechanics, resource production, and progression paths, visit
our [Villages guide](/mechanics/realm-and-villages/villages).

### Continuous Play

As long as you maintain in-game Realm or Village ownership, you can actively participate without additional entry fees.
Engage in the market using **$LORDS** tokens and enjoy uninterrupted gameplay until the end of the season.

### Realm Control Mechanics

⚔️ **Takeover System**

Settled Realms can be conquered within a Season, transferring control to the conqueror. Gameplay rights are restored at
the start of the next Season, as the Realm NFT owner will be able to mint a new Season Pass for the new Season.

🛡️ **Village Security**

Unlike Realms, Villages cannot be conquered by other players, making them an ideal choice for casual players seeking a
lower-risk gameplay experience. Villages can still participate in most gameplay activities - producing resources,
training troops, and engaging in trade - but at 50% the rate of Realms. This security, combined with their accessibility
and limited progression path from Settlement to City, makes Villages perfect for new players looking to learn the game
mechanics without the constant threat of conquest.



---

file: docs/pages/overview/introduction.mdx
meta: {
  "title": "Introduction to Eternum",
  "description": "Understanding the World of Eternum"
}

# Welcome to Eternum

<img src="/images/covers/01.png" alt="Eternum Landscape" className="w-full rounded-lg my-6" />

## The Lords Have Arrived

Across treacherous open seas and endless horizons, the legendary Galleon has finally arrived upon the lands of Eternum,
bearing the brave and ambitious souls known as Lords. Having journeyed for years, driven by dreams of power, glory, and
untold riches, these Lords have finally set foot upon their destination—a mysterious landscape ripe with ancient secrets
and unclaimed territories. Now, as the mists clear, each Lord must forge their own path in this land of promise and
peril.

## Establish Your Foothold

In Eternum, your task begins by settling a Realm or Village—a seat of power from which your destiny unfolds. Select your
strategic position upon the vast, unexplored, procedurally generated world map and secure vital materials to fuel your
expansion. Grow your influence through shrewd economic choices, military strategy, and diplomatic maneuvering, nurturing
your humble settlement into a mighty empire.

Yet, strength alone is insufficient, for Eternum is fraught with dangers—bandits roam unchecked and rival Lords covet
your lands. Armies must be raised, resources guarded, and alliances carefully chosen. Only through wise leadership and
vigilant defense can your Realm flourish and endure.

## Find Your Glory

Scattered throughout Eternum are the foundations of ancient Hyperstructures—colossal relics from an ancient civilization
far surpassing all known powers. Some unknown, cataclysmic event once destroyed all of these structures and plunged the
land into darkness and disorder. Lords who successfully reclaim, rebuild, and control these Hyperstructures will assert
their dominance over the vast continent, with one player eventually claiming ultimate victory.

However, Eternum's expansive world offers glory beyond mere conquest; whether through trade mastery, military prowess,
diplomatic excellence, or simply the joy of exploration, every Lord has the freedom to find their own path to greatness.

## Core Pillars

Eternum is built on three core pillars:

* **Player‑Driven Economy** – Every resource harvested and trade executed originates from player choices. Collective
  actions shape supply, demand, and market prices across Eternum.
* **Strategic Depth** – Success hinges on efficient production, calculated territorial expansion, and well‑timed
  military engagements. Foresight and adaptability separate thriving empires from conquered realms.
* **Community Governance** – Power grows through tribes, alliances, and diplomatic pacts. Coordinated groups can tip
  regional conflicts and shift the balance of power continent‑wide.

## Game Features

<img src="/images/covers/02.png" alt="Eternum Game Features" className="w-full rounded-lg my-6" />

Eternum offers high-stakes gameplay across defined seasons, set on an infinite, procedurally generated hexagonal map.
Players can pursue total victory or explore freely, with a focus on diplomacy, resource management, and tactical
decisions.

### Game Progression

* **Early Game**: Establish your Realm, build infrastructure, and secure resources.
* **Mid Game**: Expand influence, forge alliances, and develop military capabilities.
* **End Game**: Engage in epic battles, large-scale diplomacy, and resource warfare.

### Core Elements

* **Seasons** – Freestanding campaigns with fresh rules and victory conditions; in-game assets can be bridged forward,
  however, allowing committed Lords to carry hard‑won progress between chapters.
* **World Map** – An infinite, procedurally generated hex grid dotted with Banks, Fragment Mines, and Hyperstructure
  Foundations, facilitating exploration and conflict.
* **Resources & Economy** – 22 tokenized resources—plus food, labor, donkeys, and troops—are traded with a player owned
  and operated economy.
* **Military Power** – Raise armies and battle strategically—considering stamina, troop tiers and biome effects, to
  seize territory and capture the Realms of your rivals.
* **Social Structure** – Forge tribes and alliances to pool resources, coordinate conquests, and shape regional politics
  through diplomacy or decisive force.

## Vision

Explore our
[detailed vision document](https://github.com/BibliothecaDAO/world-guide/blob/main/realms-world-guide-v1.0.0.pdf)

## Eternum as a Platform

Eternum lays the foundation for future development with open architecture, community extensions, and a focus on
innovation. It serves as a benchmark for onchain gaming capabilities.



---

file: docs/pages/overview/links.mdx
meta: {
  "title": "Quick Links",
  "description": "Essential links for Eternum"
}

# Quick Links

## Play & Learn

* [Play Eternum](https://eternum.realms.world/) - Start your journey
* [GitHub](https://github.com/BibliothecaDAO/eternum) - Explore the code
* [Season Pass](https://empire.realms.world/) - Mint your season pass
* [Season Pass Marketplace](https://element.market/starknet) - Buy your Season Pass on Element
* [Realms Marketplace](https://market.realms.world/) Buy a Realm NFT

## Community

* [Realms World](https://realms.world/) - The DAO behind Eternum
* [Discord](https://discord.gg/realmsworld) - Join our discord
* [Twitter](https://x.com/LootRealms) - Follow the community
* [Twitter](https://x.com/RealmsEternum) - Follow for Eternum updates



---

file: docs/pages/overview/lords.mdx
meta: {}

# $LORDS Token

![LORDS Token](/images/resources/37.png)

$LORDS is the native token of the Realms Autonomous World. It serves as the primary currency within the Eternum
ecosystem, enabling economic activity and resource movement throughout the game.

## Token Details

* **Name**: LORDS
* **Network**: Starknet
* **Contract Address**:
  [0x0124aeb495b947201f5fac96fd1138e326ad86195b98df6dec9009158a533b49](https://starkscan.co/token/0x0124aeb495b947201f5fac96fd1138e326ad86195b98df6dec9009158a533b49)
* **Total Supply**: 300,000,000 LORDS

## $LORDS in Eternum

* **Trading Currency**: $LORDS serves as the primary currency for trading within Eternum's Automated Market Maker (AMM)
  and the peer-to-peer Orderbook, allowing Lords to facilitate trades and manage their economic interactions.

* **Transport System**: $LORDS are essential for producing donkeys, the backbone of Eternum's transport system,
  effectively acting as the "gas" token required for facilitating all in-game logistics and resource transfers.

## How to get $LORDS

### In Eternum

Within Eternum, Lords can obtain $LORDS through various methods:

* Selling surplus materials through the in-game AMM or Orderbook
* Defeating or negotiating with AI agents
* Discovering special quest tiles scattered throughout the Eternum world
* Achieving objectives in other Realms Ecosystem games

### On Starknet

Outside of gameplay, $LORDS can be acquired on the Starknet network through decentralized exchanges (DEXs).

#### Recommended Exchanges

| Exchange                                                                          | Compatibility                     | Notes                                                                                                                             |
| --------------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [Ekubo](https://app.ekubo.org/?outputCurrency=LORDS\&amount=1\&inputCurrency=ETH) | ✅ Supports Cartridge Controller   | Swap directly with your game wallet                                                                                               |
| [Avnu](https://app.avnu.fi/en/eth-lords)                                          | ❌ No Cartridge Controller support | Requires an [Argent](https://x.com/argentHQ) or [Braavos](https://x.com/myBraavos) wallet first, then transfer to your controller |

#### Step-by-Step Guide

For new users, follow this [comprehensive guide](https://x.com/lordcumberlord/status/1920650310621495350) that covers:

1. Setting up a Braavos wallet
2. Bridging ETH to Starknet via Orbiter
3. Swapping ETH for STRK and LORDS
4. Creating a Cartridge Controller (if needed)
5. Transferring LORDS to your game wallet



---

file: docs/pages/overview/resource-addresses.mdx
meta: {}

import { ResourceAddresses } from "@/components/ResourceAddresses";

# Resource Addresses

<ResourceAddresses />



---

file: docs/pages/overview/world-physics.mdx
meta: {}

import { Biomes } from "@/components/Biomes";

# 🌪️ World Physics

<img src="/images/covers/08.png" alt="Troops Moving Across Eternum" className="w-full rounded-lg my-6" />

In Eternum, every action is governed by onchain physics—immutable rules encoded directly onto the blockchain, ensuring
fairness, transparency, and absolute consistency for all Lords. Here, code is law; no exceptions exist outside the
boundaries set by these protocols.

## Seasons

Welcome to Season 1. Eternum, in its current form, comes and goes in seasonal launches. Each season marks a special time
of iteration and advancement in this new form of onchain gaming and may be likened to the movement of tides. Once a
season launches, the tide flows out and the Lords arrive to build their castles in the sand. Nothing, not even the
developers, can stop or alter the course of a season once launched, and players are free to take any action that the
rules of the game allow. Once a Lord accumulates the requisite Victory Points, they unlock the ability to end the
season—signalling the tide to come back in and put an end to the Lords' fun… until next season.

## Time

Time within a season is measured in Eternum Days, and each is precisely one hour in length. One day ends and the next
begins at the top of every real-world hour.

## Materials

In the world of Eternum, everything holds tangible, tokenized value—be it food, labor, resources, troops, or even the
trusty donkeys required for transport. These fungible tokens are generated within Eternum, but can be bridged in and out
of the game through Realms or Banks and traded on external marketplaces. All materials have an associated weight, which
determines the amount that can be stored and the number of donkeys required to move the goods from place to place.

Note: This document will use 'materials' to refer to all tangible assets - i.e. food, resources, ancient fragments,
labor, troops, and donkeys. This is not to be confused with 'resources', which specifically refers to the 22 resources
ranging from wood through to dragonhide. Tokens such as $LORDS and $STRK are not considered materials.

## Cost of Production

With the exception of food, nothing in Eternum is produced for free; every unit of production demands an input—food,
labor, resources, or some combination thereof. Lords must consider these costs and effectively balance trade to ensure
they can survive the season.

## Travel

Transporting materials across the vast lands of Eternum takes time… and donkeys. Every transfer of materials between
locations relies exclusively on these speedy and dependable creatures. These donkeys are single-use, consumed upon
completing their journey, making continuous acquisition vital for maintaining trade routes and strategic flexibility.

Moving tokenized troops through the donkey network may be fast, but to dominate your enemies and ensure security of your
lands, troops must be deployed to an army. Once troops are deployed, they cannot be retokenized, and are doomed to their
fate within this season of Eternum. Once troops are deployed to the world map, their mobility is governed by stamina,
limiting the distance they can travel and the number of actions they can perform. Travelling between hexes or initiating
an attack expends valuable stamina points, but they are partially replenished each Eternum Day.

## Hexes

Eternum unfolds across an infinite, procedurally-generated, hexagonal-tile world map. This represents the physical space
of the world and defines spawn locations, biome distribution, and distances between Realms, Villages, and other world
structures. This is the layer in which armies explore, fight, raid and capture, and is explorable in the 'World' view.

Zooming in, each Realm or Village hex is broken up into smaller hexes which define the local area and building placement
(hexes within hexes!). Here in the 'Local' view, Lords can plan out their building placement and closely manage their
population, supply chain, and production.

## Biomes

Each hexagonal tile on the world map possesses a distinct biome. Each troop type responds uniquely to these varied
terrains, gaining or losing combat efficiency and stamina based on their affinity with different biomes. Successful
Lords must master biome knowledge to exploit strategic advantages or avoid costly missteps.

<Biomes />

## The Known World

Initial scouting reports have revealed some key details about the world:

* Six ancient Banks have been located, distributed evenly in a ring around the central point. These structures are
  perfectly situated and designed to facilitate trade in this new world. Sufficiently prepared Lords may be able to
  capture these lucrative structures, but will likely make themselves a target in the process.

* An unknown number of Hyperstructure Foundations are scattered around the unexplored world. These are rare, key
  locations that must be claimed by Lords in order to rebuild the ancient Hyperstructures that are critical to achieving
  victory. They are more likely to be found in the central regions of the map, and as each subsequent Hyperstructure
  Foundation is discovered, the likelihood of finding another one in the world diminishes.

* Hundreds of mines are also strewn across the landscape. Prospectors have theorized that these mines are hotspots for
  finding ancient fragments needed to reconstruct key sections of the Hyperstructures.

* Bandits roam throughout the lands and have established lairs in each of the key locations described above. The newly
  arrived Lords will need to overcome these lawless brigands to bring order and control back to Eternum.

* Mysterious hooded figures lurk in the mist, offering to play a strange card game with any who wish to try their luck.



---

file: docs/pages/mechanics/military/armies.mdx
meta: {}

import { RealmDefenseSlotsTable, WorldStructureDefenseSlotsTable } from "@/components/DefendingArmies";
import { ETERNUM_CONFIG } from "@/utils/config";
import { formatNumberWithCommas } from "@/utils/formatting";

# ⚔️ Armies

<img src="/images/covers/06.png" alt="Eternum World Map" className="w-full rounded-lg my-6" />

In Season 1, individual armies consist of a single troop type and tier—streamlining combat strategy and simplifying
interactions on the world map. Each hex can host only one army, so Lords must carefully manage their positioning and
engagement opportunities.

Each Realm and Village has a limited number of guard and field armies The number of armies can be increased by upgrading
the Realm / Village level as explained in the [Realms](/mechanics/realm-and-villages/realm) section. Each military
building constructed on a Realm or Village also increases total field armies by 1 (up to a maximum of
**+{ETERNUM_CONFIG().troop.limit.explorerMaxPartyCount-4}**). Lords can deploy armies from the Military tab in the Local
view. The maximum size of an army is
**{formatNumberWithCommas(ETERNUM_CONFIG().troop.limit.explorerAndGuardMaxTroopCount)}**.

### Field Armies

Field armies are used to project force on the world map, explore unknown territories, patrol borders, defend key areas,
or march against your enemies. These armies are deployed onto one of the six hexes surrounding their parent Realm on the
world map. If all hexes adjacent to the Realm are occupied, a field army cannot be deployed. Once deployed, these armies
occupy a hex and traverse the world map based on the conditions outlined in the World Map & Movement section.

Lords may direct their field armies to attack another army or structure on any adjacent hex by selecting the army with
left-click, then right-clicking the target hex. When attacking a structure, the field army will engage in combat against
any guard armies present.

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/create-explorer.gif" alt="Create Army" />

  <em>Flow to create field army in the client</em>
</div>

### Guard Armies

Guard armies do not appear on the world map; instead, they occupy defense slots visible in the Military tab of the Local
view. When in the World view, Lords can observe the defensive capabilities of any structure by selecting a hex and
opening up the Details tab.

Unlike Realms and Villages, world structures have a static number of defence slots:

<WorldStructureDefenseSlotsTable />

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/create-guard.gif" alt="Create Army" />

  <em>Flow to create guard in the client</em>
</div>

When attacked, guard armies are targeted sequentially starting from the outermost occupied slot. If a guard army is
destroyed, the slot that it occupied becomes unavailable for reinforcement for
**{Math.floor(ETERNUM_CONFIG().troop.limit.guardResurrectionDelay / 3600)} hours**. Once all guard armies are defeated,
the structure becomes vulnerable to being claimed by an adjacent field army (with the exception of Villages, which
cannot be claimed). Lords can also direct their guard armies to launch attacks against adjacent hexes by selecting their
structure on the worldmap, then right-clicking the target hex.

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/attack-from-structure.gif" alt="Attack field army" />

  <em>Attack field army with structure</em>
</div>



---

file: docs/pages/mechanics/military/damage.mdx
meta: {}

# 💥 Damage

import { DamageCalculation } from "@/components/DamageCalculation";

## Damage Overview

Damage is defined as the number of casualties dealt by one army against the other in an instance of combat. When combat
is initiated (i.e. one army attacks another), damage for both the attacking and defending army is calculated based on
the number of troops, troop tier, stamina, and biome bonuses. Damage is then simultaneously inflicted by both sides.
Battles can last multiple rounds (requiring multiple combat instances) depending on the relative strength and number of
troops involved. Armies with higher-tier troops deal significantly more damage. However, careful management of troop
numbers, stamina, and biome positioning can enable lower-tier armies to overcome stronger opponents.

<DamageCalculation />



---

file: docs/pages/mechanics/military/raiding.mdx
meta: {}

import { ETERNUM_CONFIG } from "@/utils/config";
import { RAIDABLE_RESOURCES } from "@bibliothecadao/types";
import { resource } from "@/components/styles";
import { RaidableResources } from "@/components/RaidableResources";
import { importantNote } from "@/components/styles";

# 💰 Raiding

Raiding allows field armies to attempt theft of valuable resources directly from an adjacent target structure, without
first having to battle through enemy guard armies. Lords can direct their armies to complete this action by selecting
the 'raid' action when attacking an enemy structure.

![Raiding interface showing an army preparing to raid a structure](/screenshots/raiding.png)

## Raid Requirements

Before attempting a raid, your army must meet the following requirements:

* Have at least **{ETERNUM_CONFIG().troop.stamina.staminaAttackReq}** stamina
* Be adjacent to the target structure
* Structure must contain raidable resources

## Raidable Materials

Raidable materials are stolen based on rarity, with the most valuable taken first. Rarer materials are prioritized
during raids:

<RaidableResources />

<div style={importantNote.container}>
  <h3 style={importantNote.title}>⚠️ IMPORTANT NOTE</h3>
  <p style={importantNote.content}>No materials are safe from pillagers, $LORDS tokens can be raided as well</p>
</div>

## Raid Success

The success chance of a raid is determined by the following conditions:

| Condition                                                                  | Raid Success Chance                           |
| -------------------------------------------------------------------------- | --------------------------------------------- |
| Raiding army's total damage \< **50%** of combined guard armies' damage    | **0%**                                        |
| Raiding army's total damage > **200%** of combined guard armies' damage    | **100%**                                      |
| Raiding army's damage between **50%** and **200%** of guard armies' damage | Scales proportionally from **0%** to **100%** |
| No guard armies present                                                    | **100%** (automatic success)                  |

Upon a successful raid, resources are transferred directly to the raiding army's inventory up to its carrying capacity.
It is only possible to steal food, resources, and ancient fragments from a raid, tokens such as $LORDS and $STRK can
only be stolen from another player by claiming a Realm into which tokens have been bridged or transferred.

## Damage in Raids

At the conclusion of a raid, regardless of whether it was successful or not, damage is calculated for both the raiding
army and the guard armies. This damage is significantly reduced by a raid damage modifier, simulating the concept of a
pillaging and looting event as opposed to a full-scale battle. The raid damage modifier reduces damage to
**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of that which would be applied in an attack action.

Damage from a raiding action is calculated according to the following rules:

* The raiding army troop total is split evenly across each guard army.
* A standard combat damage calculation is then applied to each combat instance.
* Each damage number is multiplied by the raid damage modifier before casualties are applied.

### Example:

Consider **1000** raiders attacking a structure with two occupied guard slots:

* Slot 1: **400** troops
* Slot 2: **600** troops

The raiding army is split into two groups of **500** troops, each attacking one guard slot. Assume that the damage
calculations result in the following:

* Raiding army deals **180** damage to Slot 1 and **150** damage to Slot 2 = **330** total damage
* Guard armies deal **120** damage from Slot 1 and **200** damage from Slot 2 = **320** total damage.

Applying the raid damage modifier, actual losses become:

* Guards: Slot 1 loses **36** troops (**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of 180), Slot 2
  loses **30** troops (**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of 150).
* Raiders: Lose **64** troops total (**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of 320).

## Raid Outcomes

After a raid attempt, one of two outcomes will occur:

1. **Successful Raid**

   * Resources are transferred to your army's inventory
   * Resources are limited by your army's carrying capacity
   * Both armies suffer reduced casualties (**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of normal
     combat damage)
   * Your army's stamina is reduced by **{ETERNUM_CONFIG().troop.stamina.staminaAttackReq}**

2. **Failed Raid**
   * No resources are stolen
   * Both armies still suffer reduced casualties (**{ETERNUM_CONFIG().troop.damage.damageRaidPercentNum/100}%** of
     normal combat damage)
   * Your army's stamina is still reduced by **{ETERNUM_CONFIG().troop.stamina.staminaAttackReq}**

The outcome is determined by comparing your army's total damage output against the combined damage output of all guard
armies present. If no guard armies are present, the raid automatically succeeds.



---

file: docs/pages/mechanics/military/stamina-and-biomes.mdx
meta: {}

import { BiomeCombat } from "@/components/BiomeCombat";

# ⚡ Stamina & Biome Effects

## Stamina

Stamina is a vital resource governing the mobility and effectiveness of armies. Each deployed army possesses a maximum
stamina value determined by its troop type and tier as explained above. Field armies expend stamina when moving,
exploring unknown hexes, or engaging in combat against other armies and structures. Guard armies only expend stamina
when attacking armies in hexes adjacent to their structure. During combat, stamina impacts army combat effectiveness:

### Attacking Army (the army initiating combat)

Attacks require a minimum of **30 stamina**, so armies with less than 30 stamina cannot initiate an attack. Each
additional stamina point above this threshold grants a **1%** damage bonus, up to a maximum of **+30%** damage at **60
stamina**. Additional stamina spend is not optional, so attacking armies will use all available stamina up to a maximum
of **60** for any one attack. If the attacking army destroys the defending army, they gain **+30 stamina**.

### Defending Army (the army being attacked)

Defending armies rely on having stamina available to maintain full combat effectiveness. When attacked, defending armies
incur a **1%** damage reduction for every stamina point below **30**. For example, if an army is attacked while they
have **10 stamina**, they would deal **-20%** damage to the attacking army. The maximum penalty is **-30%** damage if
stamina is completely depleted. Successfully defending an attack does not deplete stamina. Lords should manage their
armies' stamina carefully, ensuring they retain enough reserves to remain effective against unexpected attacks.

## Biomes (Combat Effects)

The combat effectiveness of different troop types is impacted by the biome on which the defending army is located when
engaging in battle. Armies can gain either a combat advantage (**+30%** damage), disadvantage (**-30%** damage), or no
effect, depending on their affinity with a particular biome. To summarise these combat modifiers for each troop type:

⚔️️ ️️️**Knights** excel in forests, leveraging cover and mobility, but suffer reduced effectiveness in deserts,
beaches, and snow-covered regions where their heavy armour and weapons can make it difficult to move on the soft ground
cover. Knights are equally advantaged, disadvantaged or not affected across all biome types.

🏹 **Crossbowmen** benefit from open seas and unstable terrains (such as beaches and snow), where they can remain static
and make the most of their ranged capabilities. However, they will be disadvantaged in flat, open terrain with no cover
or opportunity for concealment. Crossbowmen are the least advantaged, but also the least disadvantaged by biome
modifiers of the three troop types.

🛡 ️**Paladins** dominate open, flat terrain where mounted units thrive, but are hindered in dense forests and on open
water where their mounted capabilities are negated. They are the most advantaged, but also the most disadvantaged troop
type. In combination with the biome effects on stamina use, Paladins are less versatile than other Knights or
Crossbowmen, but are devastatingly effective in the right situations.

**Note: The scorched biome applies +30% damage to all troop types, representing the additional casualties sustained from
battling in an inhospitable environment.**

<BiomeCombat />



---

file: docs/pages/mechanics/military/troop-tiers.mdx
meta: {}

import { TroopTiers, TroopTierDamageStats } from "@/components/TroopTiers";
import { MaxStaminaTable } from "@/components/TroopMovementTable";

# 🛡️ Troop Tiers

Troops in Eternum come in three distinct tiers: T1, T2, and T3. Tier 1 (T1) represents basic troops, while T2 and T3
troops are more advanced, offering significantly increased combat strength and stamina.

Higher-tier troops are produced by constructing specialized buildings that require rare resources and lower-tier troops
as inputs:

* Two T1 troops combine to produce one T2 troop
* Two T2 troops combine to produce one T3 troop

Each troop tier provides escalating advantages in terms of damage output and stamina.

<TroopTiers />

<TroopTierDamageStats />

<MaxStaminaTable />



---

file: docs/pages/mechanics/realm-and-villages/buildings.mdx
meta: {}

import BuildingCard from "../../../components/BuildingCard";
import { formatNumberWithCommas } from "@/utils/formatting";
import { CapacityConfig } from "@bibliothecadao/types";
import { ETERNUM_CONFIG } from "@/utils/config";

# 🪓 Buildings

## Standard vs. Simple

Season 1 offers two building systems. Lords can switch between standard and simple building modes at any time by
clicking the toggle at the top of the construction tab.

![Simple Mode Production](/gifs/simple-mode.gif)

Note: Some buildings only require food to construct. Farms, Fishing Villages and Resource Buildings have the same
construction cost in both standard and simple building modes.

### Standard Mode

This is the classic Eternum experience. Construction requires a combination of labor and a particular set of resources
as building materials. Standard mode is more complex as it involves a greater number of materials in storage, however it
is far more efficient overall. This building mode is generally designed for those with multiple Realms and/or Villages
working with economies of scale.

### Simple Mode

This mode allows players to utilize Labor, a new material for Season 1, as the singular input for construction. Simple
mode greatly improves accessibility and simplifies gameplay overall, but is much less efficient in both time and
materials. This would be the preferred system for players with smaller holdings and limited access to a variety of
resources.

## Placement & Population

### Placement

The construction tab can be accessed in the Local view. Buildings can be constructed on any buildable hex of a Realm or
Village, provided the owner has the requisite materials and population capacity. Buildable hexes are defined by the
upgrade level (i.e. Settlement, City, Kingdom, or Empire) and are visible as hexes with patches of bare, prepared earth.
Most buildings can be constructed in either simple or standard mode, which toggled at the top of the construction tab.

![Building Placement](/gifs/construction.gif)

### Population

Population is the total population utilised by the currently constructed production buildings on a Realm or Village,
while the population capacity is the maximum available population with which to construct production buildings. Worker
Huts can be built to increase population capacity, while all other buildings require population capacity to be available
in order to construct. Lords must balance their construction to ensure there is enough population capacity available to
construct their desired production buildings.

## Building Types

### The Keep

Settling any Realm or Village will automatically construct a structure in the centre of your buildable hexes, known as
the Keep. This structure represents your seat of power and the central point of governance, and facilitates key
functions such as Realm/Village upgrades and Labor production. This building cannot be destroyed and provides a baseline
population capacity of 5.

<BuildingCard
  title="Labor Camp"
  image="/images/buildings/construction/castleZero.png"
  buildingType={25}
  description={[
  "Produces Labor resource",
  "Provides a baseline population capacity of 5",
  "Available in both simple and standard building modes",
]}
/>

### Resource Buildings

There is a specific resource building for each of the 22 resources in the game, so Lords will require separate resource
buildings if they wish to produce more than one type of resource. These buildings only require food to construct and
have the same requirements in simple and standard mode.

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(230px, 1fr))', gap: '0.75rem' }}>
  <BuildingCard
    title="Lumber Camp"
    image="/images/buildings/construction/lumber_mill.png"
    buildingType={5}
    description={[
  "Produces Wood resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes"
]}
  />

  <BuildingCard
    title="Stone Quarry"
    image="/images/buildings/construction/mine.png"
    buildingType={3}
    description={[
  "Produces Stone resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Coal Mine"
    image="/images/buildings/construction/mine.png"
    buildingType={4}
    description={[
  "Produces Coal resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Copper Mine"
    image="/images/buildings/construction/forge.png"
    buildingType={6}
    description={[
  "Produces Copper resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Obsidian Flows"
    image="/images/buildings/construction/mine.png"
    buildingType={8}
    description={[
  "Produces Obsidian resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Silver Mine"
    image="/images/buildings/construction/forge.png"
    buildingType={10}
    description={[
  "Produces Silver resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Ironwood Grove"
    image="/images/buildings/construction/lumber_mill.png"
    buildingType={7}
    description={[
  "Produces Ironwood resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Cold Iron Foundry"
    image="/images/buildings/construction/forge.png"
    buildingType={13}
    description={[
  "Produces Cold Iron resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Gold Mine"
    image="/images/buildings/construction/forge.png"
    buildingType={9}
    description={[
  "Produces Gold resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Hartwood Sanctuary"
    image="/images/buildings/construction/lumber_mill.png"
    buildingType={17}
    description={[
  "Produces Hartwood resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Diamond Mine"
    image="/images/buildings/construction/mine.png"
    buildingType={16}
    description={[
  "Produces Diamond resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Sapphire Mine"
    image="/images/buildings/construction/mine.png"
    buildingType={22}
    description={[
  "Produces Sapphire resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Ruby Mine"
    image="/images/buildings/construction/mine.png"
    buildingType={15}
    description={[
  "Produces Ruby resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Deep Crystal Cave"
    image="/images/buildings/construction/mine.png"
    buildingType={14}
    description={[
  "Produces Deep Crystal resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Ignium Harvester"
    image="/images/buildings/construction/forge.png"
    buildingType={18}
    description={[
  "Produces Ignium resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Ethereal Silica Harvester"
    image="/images/buildings/construction/mine.png"
    buildingType={23}
    description={[
  "Produces Ethereal Silica resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="True Ice Harvester"
    image="/images/buildings/construction/mine.png"
    buildingType={20}
    description={[
  "Produces True Ice resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Twilight Quartz Mine"
    image="/images/buildings/construction/mine.png"
    buildingType={19}
    description={[
  "Produces Twilight Quartz resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Alchemical Workshop"
    image="/images/buildings/construction/forge.png"
    buildingType={12}
    description={[
  "Produces Alchemical Silver resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Adamantine Mine"
    image="/images/buildings/construction/forge.png"
    buildingType={21}
    description={[
  "Produces Adamantine resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Mithral Forge"
    image="/images/buildings/construction/forge.png"
    buildingType={11}
    description={[
  "Produces Mithral resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Dragonhide Harvester"
    image="/images/buildings/construction/dragonhide.png"
    buildingType={24}
    description={[
  "Produces Dragonhide resource",
  "Requires 2 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />
</div>

### Economic Buildings

These buildings define the utility of a Realm or Village, including food production, donkey production, population
capacity, and storage capacity. All of these buildings can be constructed in either standard or simple mode, but have
varying costs and population requirements:

\[economic building table, including population cost / population capacity increase (Worker Hut) / storage capacity
increase (Storehouse)]

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(230px, 1fr))', gap: '0.75rem' }}>
  <BuildingCard
    title="Worker's Hut"
    image="/images/buildings/construction/workers_hut.png"
    buildingType={1}
    description={[
  "Increases population capacity by 5",
  "Available in both simple and standard building modes"
]}
  />

  <BuildingCard
    title="Storehouse"
    image="/images/buildings/construction/storehouse.png"
    buildingType={2}
    description={[
  "Increases storage capacity by {formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.Storehouse]/1000 )} kg for each material",
  "Requires 2 population to be constructed",
  "Available in both simple and standard building modes",
]}
  />

  <BuildingCard
    title="Market"
    image="/images/buildings/construction/market.png"
    buildingType={27}
    description={[
  "Produces Donkeys for transportation",
  "Requires 3 population to be constructed",
  "Available in both simple and standard building modes",
]}
  />

  <BuildingCard
    title="Farm"
    image="/images/buildings/construction/farm.png"
    buildingType={37}
    description={[
  "Produces Wheat (food) resource",
  "Requires 1 population to be constructed",
  "Same construction cost in both simple and standard modes",
]}
  />

  <BuildingCard
    title="Fishing Village"
    image="/images/buildings/construction/fishing_village.png"
    buildingType={38}
    description={[
  "Produces Fish (food) resource",
  "Requires 1 population to be constructed",
  "Same construction cost in both simple and standard modes"
]}
  />
</div>

### Military Buildings

Your military buildings are essential for training up armies to defend your territories and project your might. There
are three 'tiers' of each of the three troop types, but a different building is required to produce each troop tier. As
such, there are a total of 9 military buildings in the game.

Note: Only T1 troop buildings can be constructed in both standard and simple mode. T2 and T3 military buildings are only
available for construction in standard mode.

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(230px, 1fr))', gap: '0.75rem' }}>
  <BuildingCard
    title="Footman Barracks (T1)"
    image="/images/buildings/construction/barracks.png"
    buildingType={28}
    description={[
  "Produces T1 Footman units",
  "Requires 3 population to be constructed",
  "Available in both simple and standard building modes"
]}
  />

  <BuildingCard
    title="Knight Quarters (T2)"
    image="/images/buildings/construction/barracks.png"
    buildingType={29}
    description={[
  "Produces T2 Knight units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode",
]}
  />

  <BuildingCard
    title="Guardian Sanctum (T3)"
    image="/images/buildings/construction/barracks.png"
    buildingType={30}
    description={[
  "Produces T3 Royal Guardian units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode",
]}
  />

  <BuildingCard
    title="Archery Range (T1)"
    image="/images/buildings/construction/archery.png"
    buildingType={31}
    description={[
  "Produces T1 Archer units",
  "Requires 3 population to be constructed",
  "Available in both simple and standard building modes",
]}
  />

  <BuildingCard
    title="Crossbow Garrison (T2)"
    image="/images/buildings/construction/archery.png"
    buildingType={32}
    description={[
  "Produces T2 Crossbowman units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode",
]}
  />

  <BuildingCard
    title="Hunting Den (T3)"
    image="/images/buildings/construction/archery.png"
    buildingType={33}
    description={[
  "Produces T3 Beast Hunter units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode",
]}
  />

  <BuildingCard
    title="Horseman Stables (T1)"
    image="/images/buildings/construction/stable.png"
    buildingType={34}
    description={[
  "Produces T1 Horseman units",
  "Requires 3 population to be constructed",
  "Available in both simple and standard building modes",
]}
  />

  <BuildingCard
    title="Paladin Sanctuary (T2)"
    image="/images/buildings/construction/stable.png"
    buildingType={35}
    description={[
  "Produces T2 Paladin units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode",
]}
  />

  <BuildingCard
    title="Dragon Pit (T3)"
    image="/images/buildings/construction/stable.png"
    buildingType={36}
    description={[
  "Produces T3 Dragon Rider units",
  "Requires 3 population to be constructed",
  "Only available in standard building mode"
]}
  />
</div>

### Same Building Cost Increase

Building multiple buildings of the same type will cost progressively more each time. The cost increase is calculated
using the following formula:

```
Cost = Base Cost + (Base Cost × 0.5 × (N-1)²)
```

Where:

* **Base Cost** is the initial cost of the building (from the tables above)
* **N** is the number of the same buildings already constructed

For example, if you build a second building of the same type (N=2), the cost will be:

```
Cost = Base Cost + (Base Cost × 0.5 × (2-1)²)
     = Base Cost + (Base Cost × 0.5 × 1)
     = Base Cost × 1.5
```

Note: Buildings need to be exactly the same type for this rule to apply. For example, building a Stone Quarry after a
Lumber Camp (both being resource buildings) would not be subject to this cost increase.



---

file: docs/pages/mechanics/realm-and-villages/realm.mdx
meta: {}

import { StartingResources, StructureType } from "@/components/StartingResources";
import { StartingMilitary } from "@/components/StartingMilitary";
import { RealmDefenseSlotsTable } from "@/components/DefendingArmies";
import { BuildableHexes } from "@/components/BuildableHexes";
import { RealmLeveling } from "@/components/RealmLeveling";
import { importantNote } from "@/components/styles";

# 🏰 Realms

The 8,000 Realms are the foundation of Eternum, each uniquely destined to shape the fate of this vast continent. As
limited and irreplaceable strongholds, these Realms serve as the primary playing pieces of the game. Each Realm settled
in Eternum can produce between one and seven different resources, depending on the metadata of the original Realm NFT
and its associated Season Pass. This metadata also aligns each Realm to one of sixteen ancient Orders, however the
meaning of this alignment has been lost to the mist… for now.

<img src="/images/buildings/construction/castleOne.png" width="800" style={{ margin: "0 auto", transform: "scale(1.2)" }} />

### Settling

To settle a Realm, Lords must first burn a Season Pass, which gives them the ability to select the location of their
homeland from an array of locations scattered across the map. For Season 1, there is a seven-day settling period before
the game starts, allowing players to organise and position themselves before a move can be made. Realms can still be
settled after this period, however the earlier in the season that Lords can establish their holdings, the greater their
production potential and overall experience.

<img src="/gifs/settle-realm.gif" alt="Settling a Realm" width="800" className="mx-auto" />

![Realm Settling Screen](/screenshots/settling.png)

<div style={importantNote.container}>
  <h3 style={importantNote.title}>⚠️ IMPORTANT NOTE</h3>

  <p style={importantNote.content}>
    When the game starts, all structures are immune to attacks and raids for 24 hours. Once the first day of gameplay
    has concluded, there are no more instances of immunity, all Realms and Villages settling into the game after this
    time will need to rely on their starting defences and consider their starting locations carefully. Lords entering
    the game after the immunity period are advised to make use of the spectator mode to scout for relatively safe
    spawning locations before initiating a settling transaction.
  </p>
</div>

### Starting Resources

<StartingResources structureType={StructureType.Realm} />

### Starting Military

Each Realm starts with the majority of the starting troops deployed to the first defense slot as a guard army. A small
number of troops remain within the Realm's storage to be deployed as a field army should the Realm Lord wish to explore
beyond their walls. Troops can be transferred from the guard army to the field army using the troop transfer process
explained in the [Movement & Exploration](/mechanics/worldmap-movement/movement) section. The specific type of military
unit is determined by your Realm's biome, and is strategically chosen to have a combat advantage in that particular
environment.

<StartingMilitary amount={5000} structureType={StructureType.Realm} />

### Realm Progression

Realms can grow from a Settlement into a City, then to a Kingdom, and finally an Empire. Each upgrade level unlocks
additional buildable hexes and defensive army slots, allowing for the expansion of your economy and strengthening of
your defences. Each progression requires specific materials, outlined in the table below:

<RealmLeveling />

<BuildableHexes />

<RealmDefenseSlotsTable />



---

file: docs/pages/mechanics/realm-and-villages/villages.mdx
meta: {}

import ResourceProbability from "@/components/ResourceProbability";
import { StartingResources, StructureType } from "@/components/StartingResources";
import { StartingMilitary } from "@/components/StartingMilitary";

# 🛖 Villages

Beyond the limited number of sacred Realms lies the humble yet vital Village—small settlements established on hexes that
surround a settled Realm. These modest outposts offer a more accessible entry into Eternum, serving as gateways for new
settlers and loyal subjects. Additionally, they can act as supplementary playing pieces for more serious players who
wish to maximise their potential. Each settled Realm can have up to six Villages surrounding it, allowing up to 48,000
Villages in Season 1!

<img src="/images/buildings/construction/village.png" width="800" style={{ margin: "0 auto", transform: "scale(1.2)" }} />

### Settling

Villages are settled by minting a Village token. Aspiring settlers can choose to place their Village next to a specific
Realm by entering the asset ID of a settled Realm, or let fate guide them to a random Realm's outskirts - either way,
the Realm that they spawn adjacent to becomes that Village's 'parent' Realm. Players may also choose which of the six
possible hexes they spawn on by selecting a compass direction.

<img src="/screenshots/villages.png" alt="Village Settling Screen" width="600" className="mx-auto" />

<span style={{ fontSize: "0.9rem", display: "block", textAlign: "center" }}>
  *Three villages settled next to a realm*
</span>

### Starting Resources

<StartingResources structureType={StructureType.Village} />

### Starting Military

Each Village starts with the majority of the starting troops deployed to the first defense slot as a guard army. A small
number of troops remain within the Village’s storage to be deployed as a field army should the Village Lord wish to
explore beyond their walls. Troops can be transferred from the guard army to the field army using the troop transfer
process explained in the [Movement & Exploration](/mechanics/worldmap-movement/movement) section. The specific type of
military unit is determined by your Village's biome, and is strategically chosen to have a combat advantage in that
particular environment.

<StartingMilitary amount={1000} structureType={StructureType.Village} />

### Resource Roll

When minting a Village, a random number is rolled to determine the single resource that it can produce.

<ResourceProbability />

### Limitations

Villages produce food, resources, troops, donkeys, and labor at 50% the rate of Realms. They can receive and purchase
food, labor, donkeys and resources without restriction, but can only receive troops from their parent Realm - this
limitation is in place to prevent players from spawning a Village on their rival's Realm and 'teleporting' troops there
by using the donkey network.

### Village Progression

Villages have a limited progression path and may only upgrade once from Settlement to City. The cost and benefits of
this progression is the same as that of a Realm.



---

file: docs/pages/mechanics/realm-and-villages/wonders.mdx
meta: {
  "title": "Wonders",
  "description": "The Wonders of Realms Eternum"
}

# ✨ Wonders

Of the 8,000 Realms, 50 are distinguished by the presence of Wonders—unique and magical places of power that confer
special benefits, making them highly desirable playing pieces that may put a target on their owner's back.

In Season 1, Wonder Realms grant a 20% production bonus not only to themselves but also to all Realms and Villages
located within 12 tiles. This bonus means the Wonder Realm itself, the surrounding Realms (up to six), and all Villages
settled around these seven Realms produce food, resources, troops, labor, and donkeys at 120% efficiency compared to
standard Realms, using the same inputs.

Key Notes:

* Production rates are not increased by this bonus, more is produced overall for the same amount of input.
* These bonuses do not stack. There is no benefit to settling multiple wonders in a limited range.

<br />

<img src="/images/buildings/construction/wonder.png" width="800" style={{ margin: "0 auto", display: "block", maxWidth: "100%" }} />

<br />



---

file: docs/pages/mechanics/resources/automation.mdx
meta: {}

# Resource Automation

Resource automation allows players to set up continuous production processes within their realms, converting existing
resources or labor into other desired resources. This system helps manage resource generation efficiently without
constant manual intervention.

## Overview

The automation system works by processing "orders" that you define for each of your realms. These orders specify what
resource you want to produce (or what resource you want to convert to labor), the method of production, a target amount,
and a priority.

**Key Features:**

* **Order-Based**: Define specific production tasks.
* **Priority System**: Control the sequence of execution for multiple orders.
* **Multiple Production Types**: Choose how resources are generated.
* **Realm-Specific**: Automation is configured on a per-realm basis.
* **Browser Dependent**: Automation processes run in your browser; the game tab must remain open for automation to
  function.

## How It Works

The automation system periodically checks and processes active orders for each realm.

1. **Processing Interval**: Orders are evaluated approximately every 10 minutes.
2. **Order Prioritization**: For each realm, orders are sorted by their priority number (1 being the highest).
3. **Balance Check**: Before executing an order, the system checks if the realm has sufficient input resources or labor
   as per the recipe. If not, the order is skipped for that cycle.
4. **Recipe-Based Production**: Production follows predefined recipes from the game's configuration, detailing the
   inputs and outputs.
5. **Cycle Calculation**:
   * The system determines the maximum number of production cycles possible based on available inputs.
   * If a target amount is set, production will not exceed this amount.
6. **Transaction**: If all conditions are met, a blockchain transaction is initiated to perform the production.

## Production Types

There are three types of production automation:

1. **Standard (Resource-to-Resource)**:
   * Converts one or more input resources into a different output resource.
   * Example: Using Wood and Stone to produce Tools.
2. **Simple (Labor-to-Resource)**:
   * Utilizes Labor from the realm to produce a specific resource.
   * Example: Using Labor to harvest Food.
3. **Resource-to-Labor**:
   * Converts a specified resource into Labor for the realm.
   * Example: Burning Food to generate Labor.

## Managing Automation Orders (UI)

You can manage automation orders through the "Automation" tab within a Realm's interface.

### Adding a New Order

1. Click the "Add New Automation" button.
2. Configure the following:
   * **Production Type**:
     * `Standard (Resource-based)`
     * `Simple (Labor-based)`
     * `Resource to Labor`
   * **Priority (1-9)**:
     * Set the execution priority. `1` is the highest priority, `9` is the lowest. Orders with lower numbers are
       processed first.
   * **Resource to Produce / Resource Input for Labor**:
     * If "Resource to Labor" is selected, choose the resource you want to consume to generate Labor.
     * Otherwise, select the resource you want the automation to produce. (Note: Certain resources like Fish and Wheat
       cannot be automated for direct production via this UI).
     * The UI may show the input resources required for a "Resource-to-Resource" recipe.
   * **Target Amount / Target Labor Amount**:
     * Set the total quantity of the resource (or Labor) you want to produce.
     * **Infinite**: Check this box if you want the order to run continuously without a specific target cap.
3. Click "Add Automation".

### Viewing Orders

Existing orders are displayed in a table with the following columns:

* **Priority**: The order's priority.
* **Resource**:
  * For "Resource to Labor": Shows `Input Resource -> Labor`.
  * For "Labor to Resource": Shows `Labor -> Output Resource`.
  * For "Resource to Resource": Shows `Input Resources -> Output Resource`.
  * Icons for each resource are displayed.
* **Target**: The target amount (or "Infinite").
* **Produced**: The amount produced by this order so far.
* **Type**: The production type (e.g., "Resource To Resource", "Labor To Resource", "Resource To Labor").
* **Actions**: Allows you to "Remove" the order.

### Removing an Order

Click the "Remove" button next to an order in the table to delete it.

## Important Considerations

* **Browser Must Be Open**: Automation processing occurs in your browser. If you close the game tab or your browser,
  automation will stop.
* **Resource Availability**: Orders will only execute if the required input resources are available in the realm at the
  time of processing.
* **Transaction Costs**: Each successful automation cycle that results in production will involve a blockchain
  transaction, which incurs network transaction fees.
* **Processing Time**: Due to the 10-minute processing interval and potential network conditions, there might be a delay
  before an order is executed or its results are visible.



---

file: docs/pages/mechanics/resources/bridging.mdx
meta: {}

import { EfficiencyTable } from "@/components/EfficienyTable";

# 🌀 Bridging (Portals)

Portals provide Lords with the ability to bridge materials into and out of Eternum, connecting the in-game economy with
the Starknet infrastructure layer. Portals are mysterious and unstable devices, so they tend to burn up most of the
materials sent through. However, there is evidence that the power of the Hyperstructures can increase the stability of
Portals throughout Eternum. As Lords manage to reestablish these mighty structures throughout the land, the efficiency
of bridging in and out of Eternum improves for all.

<EfficiencyTable />

Each Realm comes equipped with a Portal. Realm Lords are able to bridge materials both into and out of their Realms
directly. Villages, however, have more limited bridging capabilities—they can bridge materials out of Eternum, but not
in. This is in line with their existing restrictions on receiving troops from external sources. They are also limited to
utilizing the Portal belonging to their parent Realm, for which the Realm owner collects a 5% fee on all materials and
tokens bridged out of the game.



---

file: docs/pages/mechanics/resources/production.mdx
meta: {}

import {
  StandardTroopProduction,
  SimpleTroopProduction,
  SimpleResourceProduction,
  StandardResourceProduction,
  LaborProduction,
  DonkeyProduction,
} from "@/components/ResourceProduction";

# ⚒️ Production

## Standard vs. Simple

As is the case for building construction, Lords can choose between standard and simple production systems when deciding
how they wish to produce their materials. This can be done by selecting the appropriate panel when making an order in
the production screen.

![Simple Mode Production](/gifs/labor-production.gif)

*Note: Production works a little differently in Season 1 compared to Season 0. Instead of streaming resources unit by
unit and producing an output for as long as you have the requisite inputs, Lords must now commit the full material
requirements to the production order upfront. The output is then produced at a given rate per second.*

### Standard Mode

The classic Eternum system—every resource and troop production order requires food and a combination of other resources
as inputs. As with buildings, standard mode is the more complex but efficient way to produce materials.

### Simple Mode

Simple mode reduces the requirements for a production order to food and labor. This is, once again, less efficient in
both time and resources—but it allows Lords to produce resources on their Realm or Village even if they don't have
access to the input resources required in standard mode.

## Materials Production

### Food

The rich and fertile lands of Eternum produce two staple food sources, Wheat and Fish. These are the only materials that
can be produced without inputs, so once a Farm or Fishing Village has been constructed, they can produce food
indefinitely.

### Resources

The 22 resources found in Eternum are the backbone of the world economy. Producing one resource requires the input of
two other resources (standard mode), or labor (simple mode). Resources are also the main components in building
construction, troop production and Hyperstructure contributions - so mastery of these assets is key to success and
security.

<SimpleResourceProduction />

<StandardResourceProduction />

### Labor

Labor is a new mechanic in Season 1 that has been introduced to simplify and supplement gameplay. It is the primary
input for buildings and production in simple mode, but is also required in standard mode for building construction,
Realm upgrades and Hyperstructure contribution.

Labor is produced by permanently burning resources in the central structure of a Realm or Village. This creates a steady
stream of Labor at a fixed rate. Each of the 22 resources can be burned to produce Labor at varying efficiency,
dependent on rarity. The amount of resources burned per second to produce Labor at the fixed rate is as follows:

<LaborProduction />

### Troops

Troops are essential for exploration, defending your lands and conquering your enemies. Every Lord will be required to
procure troops, either through production or purchase, to ensure they remain a relevant force throughout the game. In
Season 1, two new troop tiers have been introduced, each requiring a combination of food, rare resources, and troops of
the previous tier as input for production.

Note: Only T1 troops can be produced in both standard and simple mode. T2 and T3 troops can only be produced in standard
mode.

<SimpleTroopProduction />

<StandardTroopProduction />

### Donkeys

The humble steeds that move all materials around Eternum must themselves be produced in a market building. Donkeys are
one-time-use and consumed after a single journey, so Lords will need to procure a steady supply of donkeys, either
through production or purchase, to ensure that they can sustain their supply chains, trade with other players, and buy
and sell from the Banks. Since donkeys are the 'gas' of this onchain world, they consume $LORDS - the native token of
the ecosystem - during production.

<DonkeyProduction />



---

file: docs/pages/mechanics/resources/resources.mdx
meta: {}

import RarityResourceTable from "@/components/RarityResourceTable";
import ResourceIcon from "@/components/ResourceIcon";
import TroopsLimitTable from "@/components/TroopsLimitTable";
import { ResourcesIds } from "@bibliothecadao/types";

# 🪵 Materials

# Materials Overview

Materials encompass all transportable assets in Eternum, including:

* **Food**: Essential wheat and fish that fuel production and troop movement
* **Resources**: The 22 distinct resource types that can be produced on Realms based on their metadata
* **Troops**: Military units (Knights, Crossbowmen, Paladins) that can be assigned to armies
* **Donkeys**: One-time-use transport units required for moving materials across the world
* **Labor**: A special material that enables "simple mode" construction and production
* **Ancient Fragments**: Rare materials found in-game that are critical for Hyperstructure construction

While all materials can be transported, only specific resources can be produced by Realms based on their inherent
properties. Most materials (except Labor) can be bridged out as ERC20 tokens.

## Resources

Resources are the foundation of **Eternum**'s economy. Each of the 22 resources plays a vital role in the game's
ecosystem, from basic production to advanced military operations. All in-game resources can be traded freely and bridged
out as ERC20 tokens.

![Produce from building](/gifs/produce-from-building-click.gif)

## Material Categories

#### Material Tiers

Resources are distributed across the 8,000 Realms based on rarity, creating natural scarcity and trade opportunities.

<RarityResourceTable />

### Basic Materials

#### Food

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Wheat" id={ResourcesIds.Wheat} />

  <ResourceIcon name="Fish" id={ResourcesIds.Fish} />
</div>

Food is the cornerstone of your realm's economy:

* Produced without additional resource inputs
* Required for most production chains
* Essential for maintaining troops and construction

<div style={{ margin: "1.5rem 0", borderTop: "1px solid #4d3923" }} />

### Strategic Materials

#### Military

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Knight" id={ResourcesIds.Knight} />

  <ResourceIcon name="Crossbowman" id={ResourcesIds.Crossbowman} />

  <ResourceIcon name="Paladin" id={ResourcesIds.Paladin} />
</div>

<TroopsLimitTable />

Military units have unique properties:

* They can be traded as resources
* Cannot be converted back to tradeable form once deployed to an army
* Once deployed, they can still be transferred between armies if they are located on adjacent hexes and are of the same
  type and tier

<div style={{ margin: "1.5rem 0", borderTop: "1px solid #4d3923" }} />

#### Transport (Donkeys)

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Donkey" id={ResourcesIds.Donkey} />
</div>

Essential for logistics:

* Required for transferring and trading materials
* Consumed after a single use

<div style={{ margin: "1.5rem 0", borderTop: "1px solid #4d3923" }} />

### Special Materials

#### **$LORDS** Currency

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Lords" id={ResourcesIds.Lords} size="xl" />
</div>

**$LORDS** is Eternum's economic backbone:

* Used as the currency for all market transactions
* Bridgeable to external networks
* Required to produce donkeys

#### Labor

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Labor" id={ResourcesIds.Labor} />
</div>

Labor is a fundamental production material:

* New Season 1 mechanic
* Can be produced by any Realm or Village
* Introduces ‘simple mode’ which reduces the complexity of resource and troop production
* Required to construct most buildings
* Produced by burning resources, with rarer resources yielding more labor

#### Ancient Fragments

<div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginBottom: "0.75rem" }}>
  <ResourceIcon name="Ancient Fragments" id={ResourcesIds.AncientFragment} />
</div>

Strategic end-game material:

* Only found in world map Fragment Mines
* Required to commence the construction of Hyperstructures
* Cannot be produced



---

file: docs/pages/mechanics/resources/storage.mdx
meta: {}

import { WeightTable } from "@/components/WeightTable";
import { formatNumberWithCommas } from "@/utils/formatting";
import { divideByPrecision } from "@/utils/resources";
import { CapacityConfig, ResourcesIds } from "@bibliothecadao/types";
import { ETERNUM_CONFIG } from "@/utils/config";

# 🏺 Storage System

Your available storage limits the amount of materials your Realm or Village can hold. Effective management of your
storage capacity is essential for successful development. Each Realm and Village begins with a base capacity of
**{formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.Storehouse]/1000)} kg**. You'll need to
construct storehouses to expand your storage capabilities.

## Material Weights

Materials in Eternum have different weights that affect storage:

<WeightTable />

## Storehouses <img src="/images/buildings/construction/storehouse.png" alt="Storehouse" width="300" className="float-right" />

Expand your storage capacity to support your growing realm:

* **Capacity**: Each storehouse adds
  {formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.Storehouse]/1000 )}kg of storage capacity.

* **Expansion**: Build additional storehouses to increase total storage.

* **Danger**: When storage is full new production is wasted

## World Structure Storage

All world structures have set storage capacities **(that cannot be expanded through the use of storehouses)**. These
capacities are as follows:

| Structure Type | Storage Capacity                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| Hyperstructure | {formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.HyperstructureStructure]/1000)} kg |
| Bank           | {formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.BankStructure]/1000)} kg           |
| Fragment Mine  | {formatNumberWithCommas(ETERNUM_CONFIG().carryCapacityGram[CapacityConfig.FragmentMineStructure]/1000)} kg   |

## Storage Management Tips

> 💡 **Best Practices**
>
> * Check storage levels regularly
> * Build new storehouses before reaching capacity
> * Pause production when storage is nearly full
> * Plan material usage to maximize storage efficiency



---

file: docs/pages/mechanics/resources/transfers-and-trade.mdx
meta: {}

import { importantNote } from "@/components/styles";

# 📜 Transfers & Trade

## Transport

### Transfers

Throughout the season, Lords will face the need to transfer materials from place to place around the world map, whether
it be to their own Realms and Villages, or other structures like Banks, Hyperstructures, and Fragment Mines. Lords have
two primary options for initiating transfers:

* **Detailed Transfer**: Players can use the comprehensive transfer menu accessible from the Trade tab. This allows
  transfers of multiple types of materials simultaneously, to any structure on the map—including those belonging to
  other players.

![Detailed Transfer](/gifs/transfer-all.gif)

* **Quick Transfer**: Alternatively, Lords can swiftly transfer resources between their own structures using the
  resources sidebar, ideal for managing internal logistics and maintaining supply chains.

![Quick Transfer](/gifs/transfer-own.gif)

### The Donkey Network

When a transfer is initiated, donkeys travel through the invisible and immutable donkey network. This is the key
infrastructure upon which all material transport takes place, facilitating trade between players and Banks. One donkey
is capable of carrying up to 500 kg of materials, so the number of donkeys required for a transfer depends on the total
weight of the materials being moved. Once a transfer is initiated, it cannot be cancelled, and the journey will take
some time depending on the distance to the destination structure. Upon arrival, transferred materials and donkeys must
be manually claimed via the 'Resource Arrivals' tab before they become available for use.

<div style={importantNote.container}>
  <h3 style={importantNote.title}>⚠️ IMPORTANT NOTE</h3>

  <p style={importantNote.content}>
    In Season 1, resource arrivals are restricted by 'gates' to assist in reducing the load that resource arrival
    entities have on the game. As donkeys arrive at their destination bearing their various goods, they need to wait
    until the start of a new Eternum Day for the structure's arrival gate to open before they can enter and be claimed
    by the owning Lord. For example, if a transfer arrives at 2:56 p.m. the owner of the structure will only need to
    wait until 3:00 p.m. for the transfer to become claimable, however if the transfer arrives at 3:02 p.m., the goods
    won't be claimable until the next Eternum Day starts (4 p.m.).
  </p>
</div>

## Banks & Marketplaces

### Banks

<div style={{ display: "flex", justifyContent: "center", margin: "2rem 0" }}>
  <img src="/images/buildings/construction/bank.png" alt="Bank Building" style={{ maxWidth: "100%", height: "auto", borderRadius: "8px" }} />
</div>

Six ancient Banks stand evenly distributed around, and equidistant from, the centre of the map.

At the start of the game, each Bank is occupied by powerful groups of bandits. Lords who conquer a Bank become the
beneficiary of any fees from the Automated Market Maker (AMM) trades that they facilitate. Although Banks collect fees
independently, they collectively share liquidity, ensuring consistent and stable trading conditions throughout Eternum.
Realms and Villages automatically utilize their nearest Bank when trading through the AMM.

### AMM (Automated Market Maker)

The Automated Market Maker (AMM) is a decentralized trading protocol facilitated by the six Banks, allowing for
instantaneous and trustless trades 24/7—the DeFi of Eternum. Trades executed via the AMM automatically utilize the
closest Bank, directing trade fees specifically to that Bank's owner. Lords can further benefit from the AMM by
contributing materials and $LORDS to liquidity pools, earning a share of the fees generated from subsequent swaps. Lords
should be aware of the relatively high fees for using the AMM and consider the Orderbook for other trading options
first.

### Orderbook

Complementing the AMM, the Orderbook is a peer-to-peer marketplace, allowing Lords to place precise buy or sell orders
at chosen quantities and prices. This traditional method of trading incurs lower fees and offers Lords strategic
control, enabling them to manage market conditions to their advantage and set OTC orders for friends and allies.



---

file: docs/pages/mechanics/worldmap-movement/movement.mdx
meta: {}

import TroopMovementTable from "@/components/TroopMovementTable";
import { BiomeStamina } from "@/components/BiomeStamina";

# 🧭 Movement & Exploration

<img src="/images/covers/04.png" alt="Troops Moving Across Eternum" className="w-full rounded-lg my-6" />

## Stamina

Troops in Eternum are deployed onto the world map as armies. Army movement and actions across the map are governed by
stamina, a critical resource Lords must carefully manage.

Stamina is expended whenever an army moves between hexes, explores previously unrevealed areas, or launches an attack
against enemy forces. Each of these actions has a specific stamina cost, making strategic planning essential to
maximizing an army's effectiveness. Armies regenerate stamina at a consistent rate of +20 stamina per Eternum Day. Each
troop type possesses different maximum stamina capacities, outlined in the table below:

<TroopMovementTable />

Lords should remain cautious about fully depleting the stamina of their armies, as forces with low stamina may find
themselves severely disadvantaged if attacked by enemy forces.

## Movement

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/moving-army.gif" alt="Moving Army" />

  <em>Moving armies in the client</em>
</div>

Armies in Eternum can move freely into any adjacent, unoccupied hex. A hex is considered occupied if it contains a
Realm, Village, another army, or a world structure such as a Bank, Fragment Mine, or Hyperstructure. Armies may also
move to more distant hexes, provided there is a continuous path of adjacent, unoccupied hexes leading to the
destination, and the army has sufficient stamina available for the entire journey.

The amount of stamina consumed when moving into a hex depends on both the biome of that hex and the type of troops
within the army. The table below details biome-specific stamina costs for each troop type:

<BiomeStamina />

## Exploring

When an army is positioned adjacent to an unexplored hex, Lords may choose to send that army forth to uncover what lies
hidden. Exploring an unknown hex always costs 30 stamina and will reveal that hex to all Lords, permanently expanding
the known boundaries of the world.

If the newly explored hex contains a world structure or an agent army, the exploring army will automatically be pushed
back to the hex from which they started without any additional stamina penalty. Additionally, during exploration, armies
gather any valuables they encounter, receiving a stack of randomly selected resources directly into their inventory. If
an army becomes overloaded, they will not be able to undertake further exploration, but can continue to travel on
previously-explored hexes. Armies can return to a structure to offload the materials, or drop them to free up space.
Note that any materials discarded in the field will be permanently lost (burned).

Given the possibility of encountering hostile agent armies during exploration, Lords should ensure that their exploring
armies are well-prepared and capable of defending themselves in unexpected combat situations.

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/explore.gif" alt="Explore" />

  <em>Explore in the client</em>
</div>

## Troop Transfers

Lords may transfer troops from one army to another, provided that they are on adjacent hexes, the same troop type, and
the same tier. To transfer troops from one army to another, or to a structure, the player first needs to select its army
on the worldmap using left-click, then right-click on the target and select the Transfer -> Transfer Troops tab.
Transferring troops from one army to another with lower stamina makes no change to the stamina of either army.
Transferring from an army with lower stamina to an army with higher stamina will reduce the higher-stamina army to equal
that of the lower stamina army.

<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
  <img src="/gifs/transfer-troops.gif" alt="Transfer Troops" />

  <em>Transfer troops in the client</em>
</div>



---

file: docs/pages/mechanics/worldmap-movement/worldmap.mdx
meta: {}

# 🗺️ The World Map

<img src="/images/covers/05.png" alt="Eternum World Map" className="w-full rounded-lg my-6" />

## An Unexplored World

At the beginning of each season, Eternum lies entirely unexplored, shrouded in mystery and opportunity. The only
exceptions are the six ancient Banks, whose location and surrounding hexes are known and visible from the outset. They
can be seen when settling and when observing the world view, each equidistant from the centre of the map and from one
another.

When Lords settle a Realm, the six hexes directly adjacent to the Realm hex and the six possible village locations are
automatically revealed if they haven't already been explored. Beyond these instances, the world remains cloaked by the
mist, waiting for ambitious Lords to send forth their armies to explore. Once a hex is explored, the state of the hex
(i.e. the biome and whether it contains a world structure or army) is permanently revealed to all Lords.

## Biomes

Each hex is assigned one of 16 biome types, each with unique aesthetics and strategic implications. These biomes are
procedurally generated across the world map following specific rules that dictate their distribution, ensuring a
coherent yet varied world, with certain biomes naturally occurring more or less frequently than others.

Biomes impact both combat effectiveness and troop movement. Each troop type—Knights, Crossbowmen, and Paladins—can
potentially be advantaged or disadvantaged in battle depending on the biome in which combat takes place; this is
explained in more detail in the [Military section](/mechanics/military/stamina-and-biomes). Additionally, biomes have
the potential to enhance or impede army maneuvers, as the various biomes impact the stamina consumption of each troop
type differently as they move between hexes—this is explained further in the
[Movement & Exploration](/mechanics/worldmap-movement/movement) section below.