Quickstart

Get Hyperscape running locally in minutes

Prerequisites

Before you begin, ensure you have:

• Bun v1.3.14 or higher
• Git LFS for large file support (game assets)
• Docker for CDN and PostgreSQL
• Privy account for authentication (recommended)
• WebGPU-compatible browser (Chrome 113+, Edge 113+, Safari 18+)

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.

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 game

   Production mode:

   bun start
   

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

   Development mode (with hot reload):

   bun run dev
   

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

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.

Running with AI Agents

To run the game with ElizaOS AI agents:

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.

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

Running Streaming Duel Arena

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

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:

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:

# 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

The betting stack has been moved to a separate repository: HyperscapeAI/hyperbet. The duel oracle remains in Hyperscape for verifiable outcome publishing.

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

# 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

Architecture

Learn about the monorepo structure

Development

Set up your development workflow