### Install and Run Dev Server Manually

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/client.mdx

Manually install dependencies and start the development server. This method provides more control over the setup process.

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

--------------------------------

### Install and Run Docs Locally (Repo Root)

Source: https://github.com/bibliothecadao/eternum/blob/next/docs/README.md

Use these commands from the repository root to install dependencies and start the documentation development server.

```bash
pnpm install
pnpm dev:docs
```

--------------------------------

### Minimal Game Agent Setup

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/game-agent/docs/ARCHITECTURE.md

This example demonstrates the basic setup for creating a game agent. It requires implementing the GameAdapter interface, initializing the agent with a model and data directory, and starting the ticker loop. Ensure to handle cleanup on process exit.

```typescript
import { createGameAgent } from "@bibliothecadao/game-agent";
import type { GameAdapter, WorldState, GameAction } from "@bibliothecadao/game-agent";
import { getModel } from "@mariozechner/pi-ai";

// 1. Implement GameAdapter for your game
class MyGameAdapter implements GameAdapter {
  async getWorldState(): Promise<WorldState> {
    // Fetch game state from your game
    return {
      tick: this.currentTick,
      timestamp: Date.now(),
      entities: await this.fetchEntities(),
      resources: new Map([
        ["gold", 1000],
        ["wood", 500],
      ]),
    };
  }

  async executeAction(action: GameAction) {
    // Execute action on chain
    const tx = await this.gameContract.execute(action.type, action.params);
    return { success: true, txHash: tx.hash };
  }

  async simulateAction(action: GameAction) {
    // Dry-run simulation
    return {
      success: true,
      outcome: {
        /* predicted result */
      },
    };
  }
}

// 2. Create agent
const adapter = new MyGameAdapter();
const model = getModel("anthropic", "claude-sonnet-4-5-20250929");

const game = createGameAgent({
  adapter,
  dataDir: "./agent-data",
  model,
  tickIntervalMs: 60_000,
});

// 3. Start tick loop
game.ticker.start();

// 4. Cleanup on exit
process.on("SIGINT", async () => {
  await game.dispose();
  process.exit(0);
});
```

--------------------------------

### Install and Run Docs Locally (Docs App Folder)

Source: https://github.com/bibliothecadao/eternum/blob/next/docs/README.md

Alternatively, navigate to the docs app folder and run these commands to install dependencies and start the development server.

```bash
cd client/apps/game-docs
pnpm install
pnpm run dev
```

--------------------------------

### Development Setup and Commands

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/react/README.md

Commands for setting up the development environment, installing dependencies, building the package, and running in development mode with watch.

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Development mode with watch
pnpm dev
```

--------------------------------

### Install Dojo and Project Dependencies

Source: https://github.com/bibliothecadao/eternum/blob/next/README.md

Follow these steps to set up your development environment, including installing Dojo, Node.js, pnpm, and Bun, then cloning the repository and installing project dependencies.

```bash
curl -L https://install.dojoengine.org | bash

# 2. Install pnpm
npm install -g pnpm

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

# 4. Build shared packages
pnpm run build:packages

# 5. Start development server
pnpm dev
```

--------------------------------

### Run Axis from Source

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/install-and-run.mdx

Clones the repository, installs dependencies, builds necessary packages, and starts the onchain agent. Ensure you have Node.js 22+ and Bun installed.

```bash
git clone https://github.com/bibliothecadao/eternum.git
```

```bash
cd eternum && pnpm install
```

```bash
pnpm --dir packages/types build
```

```bash
pnpm --dir packages/torii build
```

```bash
pnpm --dir packages/provider build
```

```bash
pnpm --dir packages/client build
```

```bash
pnpm --dir packages/game-agent build
```

```bash
cd client/apps/onchain-agent
```

```bash
cp .env.example .env
```

```bash
pnpm dev
```

--------------------------------

### Fleet Setup and Run

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/onchain-agent/README.md

Authenticates multiple worlds using password authentication and starts headless Axis agents for each, assigning a random API port to each agent.

```bash
axis auth --all --method=password --username=me --password=secret --json > /tmp/auth.json
for world in $(jq -r '.[].world' /tmp/auth.json); do
  axis run --headless --world="$world" --api-port=$((3000+RANDOM%1000)) &
done
```

--------------------------------

### Install Dependencies and Build Packages

Source: https://github.com/bibliothecadao/eternum/blob/next/CONTRIBUTING.md

Run these commands from the repository root to install dependencies and build all packages.

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

--------------------------------

### Install SDK

Source: https://github.com/bibliothecadao/eternum/blob/next/docs/agora.md

Install the Agora SDK using pnpm.

```APIDOC
## Install

```bash
pnpm add @bibliothecadao/amm-sdk
```
```

--------------------------------

### Install Dependencies with Bun or npm

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/collectibles/DEPLOYMENT_GUIDE.md

Navigate to the deployment directory and install project dependencies using either Bun or npm.

```bash
# Navigate to deployment directory
cd contracts/collectibles/ext/scripts/deployment

# Install dependencies
bun install

# or with npm
npm install
```

--------------------------------

### Install @bibliothecadao/react

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/react/README.md

Install the package using pnpm. Ensure you have the necessary peer dependencies installed.

```bash
pnpm add @bibliothecadao/react
```

--------------------------------

### Run Eternum Client Dev Server

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/client.mdx

Use this script to easily start the development server for the React client. Ensure you have the project dependencies installed.

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

--------------------------------

### Run Axis from Source

Source: https://github.com/bibliothecadao/eternum/blob/next/client/public/llm.txt

Clones the Eternum repository, installs dependencies, builds necessary packages, and then runs the onchain-agent application. Ensure you copy the example .env file to .env before running.

```bash
git clone https://github.com/bibliothecadao/eternum.git
cd eternum && pnpm install

pnpm --dir packages/types build
pnpm --dir packages/torii build
pnpm --dir packages/provider build
pnpm --dir packages/client build
pnpm --dir packages/game-agent build

cd client/apps/onchain-agent
cp .env.example .env
pnpm dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/heavy-load/README.md

Installs project dependencies using Bun.

```bash
bun install
```

--------------------------------

### Start Callback Server for Authentication

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/worlds-and-auth.mdx

If your VPS has a public endpoint, you can start a callback server to handle the authentication redirect process.

```bash
axis auth my-world --callback-url=http://my-host:3000
```

--------------------------------

### Start Game Development Server

Source: https://github.com/bibliothecadao/eternum/blob/next/client/public/llm.txt

Starts the development server for the game client. Use this for active game development.

```bash
pnpm dev
```

--------------------------------

### Install Eternum Torii SDK

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/torii/readme.md

Install the Eternum Torii SDK using pnpm.

```bash
pnpm add @bibliothecadao/torii
```

--------------------------------

### Install Dojo

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/getting-started.mdx

Installs the Dojo onchain game engine. Ensure you have Node.js and pnpm installed.

```bash
curl -L https://install.dojoengine.org | bash
```

--------------------------------

### Install Dependencies

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/provider/readme.md

Install project dependencies using pnpm.

```bash
# Install dependencies
pnpm install
```

--------------------------------

### Start Local Game Contracts

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/getting-started.mdx

Deploys and starts the game contracts in a local environment. Ensure your .env.local file is configured.

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

--------------------------------

### Install Sharp for Image Compression

Source: https://github.com/bibliothecadao/eternum/blob/next/scripts/README-image-compression.md

Install the Sharp library as a development dependency for advanced image compression capabilities.

```bash
pnpm add -D sharp
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/README.md

Use this command to install project dependencies.

```bash
pnpm install
```

--------------------------------

### Install Eternum SDK

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/core/readme.md

Install the Eternum SDK package using pnpm.

```bash
pnpm add @bibliothecadao/eternum
```

--------------------------------

### Start Game Client Development Server

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game/AGENTS.md

Start the game client development server on a fixed host and port. Use the appropriate command based on your local Node.js version.

```bash
# If local node is already >=20.19
PATH="/Users/os/Library/pnpm:$PATH" pnpm --dir client/apps/game dev --host 127.0.0.1 --port 4173

# If local node is older (common in CI/agents), force a compatible runtime:
npx -y node@20.19.0 $(which pnpm) --dir client/apps/game dev --host 127.0.0.1 --port 4173
```

--------------------------------

### Basic Provider Setup

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/provider/readme.md

Initializes the Eternum Provider with necessary configuration details.

```APIDOC
## Basic Provider Setup

### Description
Initializes the Eternum Provider with necessary configuration details.

### Code
```typescript
import { EternumProvider } from "@bibliothecadao/provider";

// Initialize the provider
const provider = new EternumProvider(katanaManifest, rpcUrl, vrfProviderAddress);
```
```

--------------------------------

### Install Agora SDK

Source: https://github.com/bibliothecadao/eternum/blob/next/docs/agora.md

Install the Agora SDK using pnpm. This command adds the necessary package to your project dependencies.

```bash
pnpm add @bibliothecadao/amm-sdk
```

--------------------------------

### Install Dependencies and Build Package

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/dojo/readme.md

Commands for installing project dependencies and building the Eternum Dojo package during development.

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build
```

--------------------------------

### Fleet Pattern Example

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/headless-and-api.mdx

Example script for deploying multiple Axis instances in headless mode across different worlds.

```APIDOC
## Fleet Pattern

```bash
axis auth --all --json > /tmp/auth.json

for world in $(jq -r '.[].world' /tmp/auth.json); do
  axis run --headless --world="$world" --api-port=$((3000 + RANDOM % 1000)) &
done
```
```

--------------------------------

### Quick Start Interactive Mode

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/install-and-run.mdx

Sets up the environment variable for an API key and starts the Axis agent in interactive mode. This mode will discover worlds and open a browser for authentication.

```bash
echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.eternum-agent/.env
```

```bash
axis
```

--------------------------------

### Install and Run Axis

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/overview.mdx

Installs the Axis CLI using a curl script and sets up the ANTHROPIC_API_KEY environment variable. Run `axis` to start the agent.

```bash
curl -fsSL https://github.com/bibliothecadao/eternum/releases/latest/download/install-axis.sh | bash
echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.eternum-agent/.env
axis
```

--------------------------------

### Generate Coordinates for Two-Player Map Setup

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/game/ext/formulas/blitz_hex_map.html

Generates starting coordinates for a two-player map, with different layouts for side 0 and other sides.

```javascript
generateCoordsTwoPlayer() { const mapCenter = Coord.center(); if (this.side === 0) { const a1 = mapCenter.neighborAfterDistance(Direction.West, 8); const a2 = mapCenter.neighborAfterDistance(Direction.West, 4).neighborAfterDistance(Direction.SouthWest, 2); const a3 = mapCenter.neighborAfterDistance(Direction.West, 4).neighborAfterDistance(Direction.NorthWest, 2); return [a1, a2, a3]; } // Exact current Cairo behavior: side >= 1 uses the "else" branch. const b1 = mapCenter.neighborAfterDistance(Direction.East, 8); const b2 = mapCenter.neighborAfterDistance(Direction.East, 4).neighborAfterDistance(Direction.SouthEast, 2); const b3 = mapCenter.neighborAfterDistance(Direction.East, 4).neighborAfterDistance(Direction.NorthEast, 2); return [b1, b2, b3]; }
```

--------------------------------

### Run All Prefactory Deploy Steps

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/game/ContractDeployment.md

Execute all pre-factory deployment steps including game migration, ABI copying, and configuration syncing with a single command. Replace `<network>` with your target network (e.g., `local`, `sepolia`).

```bash
pnpm run prefactory:deploy:<network>
```

--------------------------------

### Build and Deploy Factory

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/factory/README.md

Install the Dojo toolchain and then build and migrate the factory contract.

```bash
sozo -P <PROFILE> build
sozo -P <PROFILE> migrate
```

--------------------------------

### Run Development Server with pnpm

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/README.md

Execute this command to start the development server for the documentation site.

```bash
pnpm run dev
```

--------------------------------

### Example: Lock Token for Staking Rewards

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/collectibles/SMART_CONTRACTS_DOCUMENTATION.md

Illustrates locking a collectible NFT for a staking pool to earn rewards. The lock is defined by a pool identifier and a start timestamp. Rewards are distributed based on lock duration.

```cairo
// Admin creates staking pool
lock_admin.lock_state_update('staking_pool_q1_2024', 1706659200);

// Users stake their NFTs for rewards
lock.token_lock(collectible_id, 'staking_pool_q1_2024');

// NFTs locked for entire quarter
// Rewards distributed based on locked duration
```

--------------------------------

### Example: Lock Token for Governance Voting

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/collectibles/SMART_CONTRACTS_DOCUMENTATION.md

Shows how to lock governance tokens for a specific voting period. This prevents tokens from being sold during the vote, ensuring holder commitment. The lock is associated with a proposal ID and a start timestamp.

```cairo
// Admin creates voting period
lock_admin.lock_state_update('dao_proposal_vote_15', 1704067200);

// Voters lock tokens to participate
lock.token_lock(governance_token_id, 'dao_proposal_vote_15');

// Prevents vote selling during voting period
```

--------------------------------

### Run Docs Development Server

Source: https://github.com/bibliothecadao/eternum/blob/next/CONTRIBUTING.md

Start the local development server for the documentation site to preview changes.

```bash
pnpm dev:docs
```

--------------------------------

### Build for Production with pnpm

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/README.md

Run this command to build the documentation site for production deployment.

```bash
pnpm run build
```

--------------------------------

### Deploy World with Factory

Source: https://github.com/bibliothecadao/eternum/blob/next/contracts/factory/README.md

Initiate the world deployment process by calling the factory's deploy entrypoint. Repeat the call until the world is fully registered, as governed by max_actions. Track progress using the FactoryDeploymentCursor model.

```bash
# First transaction
sozo -P <PROFILE> execute factory deploy sstr:<WORLD_NAME> <VERSION>
```

```bash
# Repeat until the world is fully registered
sozo -P <PROFILE> execute factory deploy sstr:<WORLD_NAME> <VERSION>
```

```bash
sozo -P <PROFILE> model get FactoryDeploymentCursor <VERSION>
```

--------------------------------

### Batch Config Deployments with Immediate Entrypoints

Source: https://github.com/bibliothecadao/eternum/blob/next/config/README.md

Batch all configuration transactions while forcing specific entrypoints to execute immediately as normal transactions before the final multicall.

```bash
# Batch all, but execute selected entrypoints immediately
CONFIG_BATCH=1 CONFIG_IMMEDIATE_ENTRYPOINTS="set_world_config,set_blitz_previous_game" bun run index.ts
```

--------------------------------

### Build Documentation

Source: https://github.com/bibliothecadao/eternum/blob/next/client/public/llm.txt

Builds the project's documentation.

```bash
pnpm build:docs
```

--------------------------------

### Install Eternum Provider

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/provider/readme.md

Install the Eternum Provider package using pnpm.

```bash
pnpm add @bibliothecadao/provider
```

--------------------------------

### Install Eternum Types

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/types/readme.md

Install the Eternum types package using pnpm.

```bash
pnpm add @bibliothecadao/types
```

--------------------------------

### Install Axis Agent

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/axis/install-and-run.mdx

Installs the Axis agent using a curl script. You can pin a specific version by setting the VERSION environment variable. Verify the installation by checking the agent's version.

```bash
curl -fsSL https://github.com/bibliothecadao/eternum/releases/latest/download/install-axis.sh | bash
```

```bash
VERSION=v0.1.0 bash
```

```bash
axis --version
```

--------------------------------

### Basic Provider Setup

Source: https://github.com/bibliothecadao/eternum/blob/next/packages/provider/readme.md

Initialize the Eternum Provider with the katana manifest, RPC URL, and VRF provider address.

```typescript
import { EternumProvider } from "@bibliothecadao/provider";

// Initialize the provider
const provider = new EternumProvider(katanaManifest, rpcUrl, vrfProviderAddress);
```

--------------------------------

### EternumClient Initialization and Usage

Source: https://context7.com/bibliothecadao/eternum/llms.txt

Demonstrates how to create and connect to the EternumClient, which serves as the main entry point for interacting with the game's onchain systems. It also shows how to listen for transaction events and disconnect.

```APIDOC
## EternumClient — High-Level Headless Client

`EternumClient` is the recommended top-level entry point. It wires the view layer, transaction domain namespaces, a provider, and a Torii SQL API together. Constructed asynchronously via `EternumClient.create(config)`.

```typescript
import { EternumClient } from "@bibliothecadao/client";
import manifest from "./manifest.json";
import { Account } from "starknet";

// Create the client (dynamically imports provider + torii internally)
const client = await EternumClient.create({
  manifest,
  rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet",
  toriiUrl: "https://api.cartridge.gg/x/eternum/torii",
  cacheUrl: "https://api.cartridge.gg/x/eternum/torii/sql",
  vrfProviderAddress: "0x...",       // optional; omit to disable VRF
  cacheTtlMs: 5000,                  // view cache TTL (default 5 s)
  cacheMaxSize: 1000,
  logger: console,
});

// Connect an account for transaction signing
const account = new Account(provider, "0xYourAddress", "0xYourPrivateKey");
client.connect(account);

// Listen to provider lifecycle events
const unsub = client.on("transactionComplete", ({ transaction_hash, type }) => {
  console.log("tx confirmed:", transaction_hash, type);
});

console.log("connected:", client.isConnected); // true

// Disconnect (e.g., on logout)
client.disconnect();
unsub();
```
```

--------------------------------

### Install pnpm

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/getting-started.mdx

Installs the pnpm package manager globally. This is required for managing project dependencies.

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

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game/AGENTS.md

Install all workspace dependencies using pnpm. This command should be run from the repo root.

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### Run Development Servers and Tools

Source: https://github.com/bibliothecadao/eternum/blob/next/CONTRIBUTING.md

Common development commands for running the game, docs site, linting, and tests.

```bash
pnpm dev
pnpm dev:docs
pnpm lint
pnpm test
```

--------------------------------

### Run React Dev Server

Source: https://github.com/bibliothecadao/eternum/blob/next/client/public/llm.txt

Use these commands to start the development server for the React client. Ensure you have the necessary environment variables set.

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

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

--------------------------------

### Example Markdown Summary Output

Source: https://github.com/bibliothecadao/eternum/blob/next/scripts/README.md

An example of the markdown summary generated by the script, detailing repository activity.

```markdown
# Eternum Weekly Code Summary

**Period:** December 14, 2024 - December 21, 2024

## 📊 Overview

- **Total Commits:** 47
- **Active Contributors:** 8
- **Files Modified:** 156
- **Packages Updated:** 6

## 👥 Contributors

1. **alice** - 15 commits
2. **bob** - 12 commits
3. **charlie** - 8 commits

## 📦 Package Activity

- **client**: 20 commits, 45 files modified
- **packages/core**: 12 commits, 23 files modified
- **contracts**: 8 commits, 15 files modified
```

--------------------------------

### Start Indexer for Sepolia

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/game-docs/docs/pages/development/getting-started.mdx

Starts the indexer service for the Sepolia testnet. This is necessary for tracking contract events.

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

--------------------------------

### Install Axis with Custom Directories

Source: https://github.com/bibliothecadao/eternum/blob/next/client/apps/onchain-agent/INSTALL.md

Override default installation directories for the agent using BIN_DIR and INSTALL_DIR variables.

```bash
curl -fsSL https://github.com/bibliothecadao/eternum/releases/latest/download/install-axis.sh | \
  VERSION=v0.1.0 BIN_DIR="$HOME/.local/bin" INSTALL_DIR="$HOME/.local/share/eternum-agent" bash
```

--------------------------------

### Build Process Integration for Image Compression

Source: https://github.com/bibliothecadao/eternum/blob/next/scripts/README-image-compression.md

Recommended steps to integrate image compression into the build process, including analysis, dry run, and final compression before building the project.

```bash
pnpm run images:analyze
pnpm run images:compress:dry-run
pnpm run images:compress
pnpm run build
```