> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai-mintlify-docs-update.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.3.14 or higher
* [Git LFS](https://git-lfs.com) for large file support (game assets)
* [Docker](https://docker.com) for CDN and PostgreSQL
* [Privy](https://privy.io) account for authentication (recommended)
* **WebGPU-compatible browser** (Chrome 113+, Edge 113+, Safari 18+)

<Warning>
  Hyperscape requires WebGPU for rendering. All shaders use Three.js Shading Language (TSL) which only compiles to WebGPU. Browsers without WebGPU support will show an error screen with upgrade instructions. **Note:** Safari 17 support was removed - Safari 18+ (macOS 15+) is now required.
</Warning>

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

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

## Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
    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":"tokyo-night"}}
    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":"tokyo-night"}}
    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 game">
    **Production mode:**

    ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
    bun start
    ```

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

    **Development mode (with hot reload):**

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

    * Client: [http://localhost:3333](http://localhost:3333) (Vite HMR)
    * Server: `ws://localhost:5555/ws`
  </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>

## Running with AI Agents

To run the game with ElizaOS AI agents:

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

This starts the game server plus the ElizaOS agent runtime. The AI agent will connect as a player and autonomously play the game.

<Info>
  You need ElizaOS configured with an LLM provider (OpenAI, Anthropic, or OpenRouter) in your environment variables.
</Info>

## Running Streaming Duel Arena

To run the complete streaming duel stack with AI vs AI combat:

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
bun run duel
```

This starts:

* Game server with streaming duel scheduler
* Duel matchmaker bots (AI agents fighting each other)
* RTMP bridge for multi-platform streaming (Twitch, Kick, X/Twitter)
* Local HLS stream for web playback

**Streaming Options:**

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
bun run duel --bots=8              # Start with 8 duel bots
bun run duel --skip-betting        # Skip betting app (stream only)
bun run duel --skip-stream         # Skip RTMP/HLS (betting only)
```

**RTMP Configuration:**
Set stream keys in `packages/server/.env`:

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
# ElizaCloud (recommended for AI agents)
ELIZAOS_CLOUD_API_KEY=your-elizacloud-api-key

# Streaming platforms
TWITCH_RTMP_STREAM_KEY=live_123456789_abcdefghij
KICK_STREAM_KEY=your-kick-stream-key
X_STREAM_KEY=your-x-stream-key

# Stream destinations auto-detected from configured keys
# Or explicitly set: STREAM_ENABLED_DESTINATIONS=twitch,kick,x
```

<Info>
  The betting stack has been moved to a separate repository: [HyperscapeAI/hyperbet](https://github.com/HyperscapeAI/hyperbet). The duel oracle remains in Hyperscape for verifiable outcome publishing.
</Info>

## 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, if started)    |

## Quick Play Guide

1. **Start the game** - Your character spawns in a starter town
2. **Find green cubes** (goblins) - Click to attack
3. **Gain XP** - Level up Attack, Strength, Defense, Constitution
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. **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":"tokyo-night"}}
# 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            # With AI agents
bun run dev:client        # Client only
bun run dev:server        # Server only
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>