Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Bun v1.1.38 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.
brew 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
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

ServicePortDescription
Client3333Vite dev server with hot reload (dev mode)
Server5555Game server (Fastify + WebSockets)
CDN8080Asset 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

KeyAction
Left-clickPrimary action (attack, gather, eat, wield)
Right-clickContext menu
Shift-clickDrop item (inventory)
F5 or \Toggle FPS debug panel
WASDCamera movement
Mouse wheelZoom 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