Quickstart

Get Hyperscape running locally in minutes

Prerequisites

Before you begin, ensure you have:

• Bun v1.1.38 or higher
• Git LFS for large file support (game assets)
• Docker (optional, for CDN and PostgreSQL)
• Privy account for authentication (optional)

macOS

brew install git-lfs
git lfs install

Linux

apt install git-lfs
git lfs install

Installation

1. Clone the repository

   git clone https://github.com/HyperscapeAI/hyperscape.git
   cd hyperscape
   bun install
   
2. Configure environment (optional)

   Create .env files if you want persistent authentication:

   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
3. Build the project

   bun run build
   

   First build takes 5-10 minutes due to PhysX WASM compilation. Subsequent builds are cached.
4. Start the CDN

   The CDN serves game assets (models, textures, audio, manifests):

   bun run cdn:up
   

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

5. Start the game

   Development mode (with hot reload):

   bun run dev
   

   • Client: http://localhost:3333 (Vite HMR)
   • Server: ws://localhost:5555/ws
   • CDN: http://localhost:8080

   Production mode:

   bun start
   

   Open http://localhost:5555 in your browser.

   The server fetches manifests from PUBLIC_CDN_URL at startup. In development, it skips the fetch if local manifests exist.

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.

Play Online

You can play Hyperscape online without installing anything:

• Production: hyperscape.club - Stable release
• Staging: staging.hyperscape.club - Latest features (may be unstable)

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

Running with AI Agents

To run the game with ElizaOS AI agents:

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.

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

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)

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

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

# 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

Architecture

Learn about the monorepo structure

Development

Set up your development workflow