> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get Hyperscape running locally in minutes

## Prerequisites

Before you begin, ensure you have:

* [Bun](https://bun.sh) v1.1.38 or higher
* [Git LFS](https://git-lfs.com) for large file support (game assets)
* [Docker](https://docker.com) (optional, for CDN and PostgreSQL)
* [Privy](https://privy.io) account for authentication (optional)

<Tabs>
  <Tab title="macOS">
    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    brew install git-lfs
    git lfs install
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    apt install git-lfs
    git lfs install
    ```
  </Tab>
</Tabs>

## Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    git clone https://github.com/HyperscapeAI/hyperscape.git
    cd hyperscape
    bun install
    ```
  </Step>

  <Step title="Configure environment (optional)">
    Create `.env` files if you want persistent authentication:

    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    cp packages/client/.env.example packages/client/.env
    cp packages/server/.env.example packages/server/.env
    ```

    Set your Privy credentials:

    * `packages/client/.env`: Set `PUBLIC_PRIVY_APP_ID`
    * `packages/server/.env`: Set `PRIVY_APP_ID` and `PRIVY_APP_SECRET`
  </Step>

  <Step title="Build the project">
    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    bun run build
    ```

    <Info>First build takes 5-10 minutes due to PhysX WASM compilation. Subsequent builds are cached.</Info>
  </Step>

  <Step title="Start the CDN">
    The CDN serves game assets (models, textures, audio, manifests):

    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    bun run cdn:up
    ```

    This starts a Docker nginx container on port 8080. The server will fetch manifests from the CDN at startup.
  </Step>

  <Step title="Start the game">
    **Development mode (with hot reload):**

    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    bun run dev
    ```

    * Client: [http://localhost:3333](http://localhost:3333) (Vite HMR)
    * Server: `ws://localhost:5555/ws`
    * CDN: `http://localhost:8080`

    **Production mode:**

    ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
    bun start
    ```

    Open [http://localhost:5555](http://localhost:5555) in your browser.

    <Info>
      The server fetches manifests from `PUBLIC_CDN_URL` at startup. In development, it skips the fetch if local manifests exist.
    </Info>
  </Step>
</Steps>

<Warning>
  Without Privy credentials, the game runs in anonymous mode where users get a new identity on every page refresh. Characters will appear to vanish because they're tied to the old anonymous account.
</Warning>

## Play Online

You can play Hyperscape online without installing anything:

* **Production**: [hyperscape.club](https://hyperscape.club) - Stable release
* **Staging**: [staging.hyperscape.club](https://staging.hyperscape.club) - Latest features (may be unstable)

<Info>
  The staging environment is updated automatically when changes are merged to the `staging` branch. Use it to test new features before they reach production.
</Info>

## Running with AI Agents

To run the game with ElizaOS AI agents:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
bun run dev:ai
```

This starts both the game and ElizaOS runtime concurrently:

* Game server on port **5555**
* Client on port **3333**
* ElizaOS runtime on port **4001**

The AI agent will connect as a player and autonomously play the game using LLM-driven decision making.

<Info>
  Requires ElizaOS 1.7.0+ with an LLM provider (OpenAI, Anthropic, OpenRouter, or Ollama) configured in your environment variables.
</Info>

### AI Agent Features

* **THINKING+ACTION format** - Agents explain their reasoning before acting
* **Target locking** - Agents finish killing one mob before switching
* **Force flee** - Auto-flee at less than 25% health with threats nearby
* **Combat readiness** - Agents assess if they're prepared for combat
* **Goal templates** - Structured beginner flows (woodcutting, mining, combat)
* **Real-time thoughts** - Watch agent decision-making in the dashboard

## What Gets Started

| Service    | Port | Description                                                   |
| ---------- | ---- | ------------------------------------------------------------- |
| Client     | 3333 | Vite dev server with hot reload (dev mode)                    |
| Server     | 5555 | Game server (Fastify + WebSockets)                            |
| CDN        | 8080 | Asset server (Docker nginx) - serves models, audio, manifests |
| PostgreSQL | 5432 | Database (Docker, auto-started by server)                     |

<Info>
  The server fetches manifests from the CDN at startup. In production, manifests are served from Cloudflare R2. In development, the local CDN serves them from `packages/server/world/assets/`.
</Info>

## Quick Play Guide

1. **Start the game** - Your character spawns in Central Haven (starter town)
2. **Find green cubes** (goblins) - Click to attack
3. **Gain XP** - Level up Attack, Strength, Defense, Constitution, Prayer, Agility
4. **Collect loot** - Coins and equipment drops
5. **Visit shops** - Buy tools (hatchet, fishing rod, tinderbox, hammer)
6. **Train gathering skills** - Chop trees, mine ore, fish
7. **Train artisan skills** - Light fires, cook food, smelt bars, smith equipment
8. **Challenge players** - Visit the Duel Arena to challenge other players to PvP combat
9. **Press F5** - Toggle FPS debug panel to monitor performance

### Controls & Keybinds

| Key              | Action                                      |
| ---------------- | ------------------------------------------- |
| **Left-click**   | Primary action (attack, gather, eat, wield) |
| **Right-click**  | Context menu                                |
| **Shift-click**  | Drop item (inventory)                       |
| **F5** or **\\** | Toggle FPS debug panel                      |
| **WASD**         | Camera movement                             |
| **Mouse wheel**  | Zoom camera                                 |

## Commands Reference

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# From package.json scripts
# Production
bun start                 # Start game server (cd packages/server && bun run start)

# Development  
bun run dev               # All packages with hot reload
bun run dev:ai            # Game + ElizaOS agents (concurrently)
bun run dev:client        # Client only
bun run dev:server        # Server only
bun run dev:app           # Tauri desktop app
bun run dev:turbo         # Turbo-based dev (excludes asset-forge)
bun run dev:reset         # Clean rebuild and restart

# Build
bun run build             # Build all packages (with docs generation)
bun run build:shared      # Build core engine
bun run build:client      # Build web client
bun run build:server      # Build game server

# Mobile
bun run ios               # Run iOS simulator
bun run ios:dev           # iOS dev mode
bun run android           # Run Android emulator
bun run android:dev       # Android dev mode
bun run cap:sync          # Sync Capacitor assets

# CDN
bun run cdn:up            # Start Docker CDN (nginx)
bun run cdn:down          # Stop CDN

# Documentation
bun run docs:dev          # Start docs dev server
bun run docs:build        # Build documentation
bun run docs:generate     # Generate API docs (typedoc)

# Testing
bun run test              # Run all tests (Turbo)
bun run lint              # Run ESLint

# Cleanup
bun run clean             # Remove build artifacts
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/architecture">
    Learn about the monorepo structure
  </Card>

  <Card title="Development" icon="code" href="/guides/development">
    Set up your development workflow
  </Card>
</CardGroup>