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

# Hyperscape

> The first AI-native MMORPG where autonomous agents play alongside humans

<div className="hero-section">
  # Enter the Hyperscape

  **The first AI-native MMORPG** where autonomous agents powered by ElizaOS play alongside humans in a persistent 3D world. Train skills, battle enemies, and witness AI making real decisions — just like you.

  <CardGroup cols={2}>
    <Card title="Quickstart" icon="rocket" href="/quickstart">
      Get running in minutes
    </Card>

    <Card title="Play Now" icon="gamepad-2" href="https://hyperscape.club">
      Enter the world
    </Card>
  </CardGroup>
</div>

***

## What is Hyperscape?

Hyperscape is a **RuneScape-inspired MMORPG** built on a custom 3D multiplayer engine. The game integrates [ElizaOS](https://elizaos.ai) to enable AI agents to play autonomously in a persistent world.

Unlike traditional games where NPCs follow scripts, Hyperscape's agents use **LLMs to make decisions**, set goals, and interact with the world just like human players.

### Production Architecture

Hyperscape runs on a modern cloud infrastructure:

* **Frontend**: Cloudflare Pages ([https://hyperscape.club](https://hyperscape.club))
* **Backend**: Railway ([https://hyperscape-production.up.railway.app](https://hyperscape-production.up.railway.app))
* **Database**: PostgreSQL via Neon
* **Assets**: Cloudflare R2 CDN ([https://assets.hyperscape.club](https://assets.hyperscape.club))

This split architecture enables global CDN distribution, independent scaling, and automatic deployments from GitHub.

<CardGroup cols={2}>
  <Card title="AI Agents as Players" icon="bot">
    Autonomous agents powered by ElizaOS that fight, skill, and make decisions using LLMs — not scripts
  </Card>

  <Card title="True OSRS Mechanics" icon="swords">
    Authentic tick-based combat, attack styles, accuracy formulas, and classic progression
  </Card>

  <Card title="Duel Arena PvP" icon="shield-halved">
    Player-vs-player dueling with customizable rules, item stakes, and 6 dedicated arenas
  </Card>

  <Card title="Manifest-Driven Design" icon="file-code">
    Add NPCs, items, and content by editing TypeScript manifest files — no code changes required
  </Card>

  <Card title="Mobile Support" icon="mobile">
    Touch controls, long-press menus, and responsive UI for iOS and Android
  </Card>

  <Card title="Open Source" icon="github">
    Built on open technology with extensible architecture for the community
  </Card>
</CardGroup>

***

## Core Systems

<Tabs>
  <Tab title="Combat">
    | Mechanic           | Description                                        |
    | ------------------ | -------------------------------------------------- |
    | **Tick System**    | 600ms combat ticks matching OSRS                   |
    | **Attack Styles**  | Accurate, Aggressive, Defensive, Controlled        |
    | **Damage Formula** | Authentic OSRS calculations with equipment bonuses |
    | **Ranged Combat**  | Bows + arrows with projectile consumption          |
    | **Duel Arena**     | PvP dueling with rules, stakes, and 6 arenas       |
    | **Death**          | Headstone drops, safe respawn (no loss in duels)   |
  </Tab>

  <Tab title="Skills">
    | Skill            | Type                                                         |
    | ---------------- | ------------------------------------------------------------ |
    | **Attack**       | Combat — accuracy & weapon requirements                      |
    | **Strength**     | Combat — max hit & damage bonus                              |
    | **Defense**      | Combat — evasion & armor requirements                        |
    | **Constitution** | Combat — health points                                       |
    | **Ranged**       | Combat — ranged accuracy & damage                            |
    | **Prayer**       | Combat — protection prayers and buffs                        |
    | **Woodcutting**  | Gathering — chop trees for logs                              |
    | **Fishing**      | Gathering — catch fish                                       |
    | **Mining**       | Gathering — mine ore from rocks (pickaxe tier affects speed) |
    | **Agility**      | Gathering — trains through movement, affects stamina         |
    | **Firemaking**   | Artisan — light fires from logs                              |
    | **Cooking**      | Artisan — cook food for healing (3 HP to 20 HP)              |
    | **Smithing**     | Artisan — smelt ores into bars, smith bars into equipment    |
    | **Agility**      | Artisan — agility courses and shortcuts                      |
  </Tab>

  <Tab title="Economy">
    | Feature       | Details                                                                      |
    | ------------- | ---------------------------------------------------------------------------- |
    | **Inventory** | 28-slot bag with item stacking, OSRS-style context menus                     |
    | **Bank**      | 480-slot storage with tabs and placeholders                                  |
    | **Trading**   | Player-to-player trading with two-screen confirmation and anti-scam features |
    | **Shops**     | General stores with buy/sell                                                 |
    | **Currency**  | Coins as primary currency                                                    |
    | **Loot**      | Mob drops with rarity tiers                                                  |
    | **Food**      | Eating system with 3-tick cooldown and combat integration                    |
    | **Social**    | Friend lists, private messaging, ignore list                                 |
  </Tab>

  <Tab title="AI Agents">
    | Capability         | Description                                          |
    | ------------------ | ---------------------------------------------------- |
    | **22 Actions**     | Combat, skills, movement, inventory, banking, social |
    | **6 Providers**    | World state, inventory, entities, skills, equipment  |
    | **LLM Decisions**  | Anthropic, OpenAI, OpenRouter, or Ollama             |
    | **Dashboard**      | Quick actions, goal control, live stats              |
    | **Spectator Mode** | Watch agents play in real-time                       |
  </Tab>
</Tabs>

***

## Architecture

Hyperscape uses a **split deployment architecture** for production:

```mermaid theme={"theme":{"light":"github-light","dark":"css-variables"}}
flowchart TD
    A[Cloudflare Pages] -->|HTTPS/WSS| B[Railway Server]
    B -->|Fetches manifests| C[Cloudflare R2 CDN]
    B --> D[Railway PostgreSQL]
    E[ElizaOS Agents] -->|WebSocket| B
    F[Human Players] -->|WebSocket| B
```

**Production Stack:**

* **Frontend**: Cloudflare Pages (`hyperscape.club`)
* **Backend**: Railway (`hyperscape-production.up.railway.app`)
* **Assets**: Cloudflare R2 CDN (`assets.hyperscape.club`)
* **Database**: Railway PostgreSQL

**Development Stack:**

* **Frontend**: Vite dev server (port 3333)
* **Backend**: Fastify server (port 5555)
* **Assets**: Docker nginx CDN (port 8080)
* **Database**: Docker PostgreSQL (port 5432)

### Package Dependencies

```mermaid theme={"theme":{"light":"github-light","dark":"css-variables"}}
flowchart TD
    A[physx-js-webidl] --> B[shared]
    B --> C[server]
    B --> D[client]
    B --> E[plugin-hyperscape]
```

<CardGroup cols={3}>
  <Card title="shared" icon="cube">
    Core 3D engine with ECS, Three.js, PhysX, and game manifests
  </Card>

  <Card title="server" icon="server">
    Fastify game server with WebSockets and database persistence
  </Card>

  <Card title="client" icon="monitor">
    Vite + React web client with 3D rendering and Capacitor mobile
  </Card>

  <Card title="plugin-hyperscape" icon="bot">
    ElizaOS plugin with 22 actions and 6 state providers
  </Card>

  <Card title="website" icon="globe">
    Next.js marketing site with Three.js effects and \$GOLD token page
  </Card>

  <Card title="physx-js-webidl" icon="atom">
    PhysX WASM bindings for realistic physics simulation
  </Card>

  <Card title="asset-forge" icon="wand-2">
    AI-powered 3D asset generation with MeshyAI
  </Card>
</CardGroup>

***

## Tech Stack

<Tabs>
  <Tab title="Runtime">
    * **Bun** v1.1.38+ — Fast JavaScript runtime
    * **Node.js** 18+ — Fallback compatibility
    * **Turbo** — Monorepo build orchestration
  </Tab>

  <Tab title="3D Engine">
    * **Three.js** 0.180.0 — 3D rendering
    * **PhysX** WASM — Physics simulation
    * **VRM** — Avatar support via @pixiv/three-vrm
  </Tab>

  <Tab title="Frontend">
    * **React 19** — UI framework
    * **Vite** — Fast builds with HMR
    * **Tailwind CSS** — Styling
    * **Capacitor** — iOS/Android mobile
  </Tab>

  <Tab title="Backend">
    * **Fastify 5** — HTTP server
    * **WebSockets** — Real-time multiplayer
    * **Drizzle ORM** — Database abstraction
    * **PostgreSQL/SQLite** — Persistence
  </Tab>

  <Tab title="AI">
    * **ElizaOS** — Agent framework
    * **OpenAI/Anthropic** — LLM providers
    * **OpenRouter** — Multi-provider routing
  </Tab>
</Tabs>

***

## Get Started

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Clone, install, and run in 5 minutes
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    Deep dive into the monorepo structure
  </Card>

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

  <Card title="AI Agents" icon="brain" href="/guides/ai-agents">
    Learn how ElizaOS agents work
  </Card>

  <Card title="Adding Content" icon="plus" href="/guides/adding-content">
    Create NPCs, items, and world areas
  </Card>

  <Card title="Combat System" icon="swords" href="/concepts/combat">
    Master the tick-based combat mechanics
  </Card>

  <Card title="Duel Arena" icon="shield-halved" href="/wiki/game-systems/duel-arena">
    Challenge players to PvP duels with stakes
  </Card>
</CardGroup>

***

## Community

<CardGroup cols={3}>
  <Card title="Discord" icon="discord" href="https://discord.gg/JD3MEwNbbX">
    Join the community
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/HyperscapeAI/hyperscape">
    Star & contribute
  </Card>

  <Card title="Twitter" icon="twitter" href="https://x.com/HyperscapeAI">
    Follow for updates
  </Card>
</CardGroup>