Hyperscape

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

Hyperscape is a RuneScape-inspired MMORPG built on a heavily modified and custom version of Hyperfy, an open-source 3D multiplayer engine. The game integrates ElizaOS 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.

What Makes Hyperscape Unique

• AI Agents as Players: Autonomous agents powered by ElizaOS that fight, skill, trade, and make decisions using LLMs
• True OSRS Mechanics: Authentic tick-based combat (600ms ticks), safespotting, tile-based movement, and classic progression systems
• Manifest-Driven Design: Add NPCs, items, and content by editing JSON files—no code changes required
• Spectator Mode: Watch agents play in real-time and observe their decision-making process
• Open Source: Built on open technology with extensible architecture

Core Features

Category	Features
Combat	Tick-based OSRS mechanics (600ms ticks), attack styles, accuracy formulas, death/respawn system
Skills	Woodcutting, Mining, Fishing, Cooking, Firemaking + combat skills with XP/leveling
Economy	480-slot bank, shops, item weights, loot drops
AI Agents	ElizaOS-powered autonomous gameplay, LLM decision-making, spectator mode
Content	JSON manifests for NPCs, items, stores, world areas—no code required
Tech	VRM avatars, WebSocket networking, PostgreSQL persistence, PhysX physics

Quick Start

Prerequisites:

• Bun (v1.1.38+)
• Git LFS - brew install git-lfs (macOS) or apt install git-lfs (Linux)
• Docker - Docker Desktop for macOS/Windows, or apt install docker.io on Linux
• Privy account (required for authentication)

git clone https://github.com/HyperscapeAI/hyperscape.git
cd hyperscape
bun install

Setup Environment Files

# Required: Copy both client and server env files
cp packages/client/.env.example packages/client/.env
cp packages/server/.env.example packages/server/.env

Configure Privy Authentication (required):

1. Create a free account at Privy Dashboard
2. Create an app and copy your App ID and App Secret
3. Set in packages/client/.env:

   PUBLIC_PRIVY_APP_ID=your-app-id
   

4. Set in packages/server/.env:

   PUBLIC_PRIVY_APP_ID=your-app-id
   PRIVY_APP_SECRET=your-app-secret
   

⚠️ 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.

Optional configs:

# AI agents (only if using bun run dev:ai)
cp packages/plugin-hyperscape/.env.example packages/plugin-hyperscape/.env

# Asset generation tools (only if using bun run dev:forge)
cp packages/asset-forge/.env.example packages/asset-forge/.env
# Edit and set OPENAI_API_KEY, MESHY_API_KEY

Run the Game

1. Start Docker - Open Docker Desktop (macOS/Windows) or start the daemon (sudo systemctl start docker on Linux)

2. Build the project (required first time):

   bun run build

3. Start the CDN (serves game assets):

   bun run cdn:up

4. Start the game:

   bun run dev          # Game only (client + server)
   # OR
   bun run dev:ai       # Game + AI agents (ElizaOS)

5. Open http://localhost:3333 in your browser.

PostgreSQL starts automatically via Docker when the server starts.

Project Structure

packages/
├── shared/              # Core 3D engine (ECS, Three.js, PhysX, networking)
├── server/              # Game server (Fastify, WebSockets, database)
├── client/              # Web client (Vite, React)
├── plugin-hyperscape/   # ElizaOS AI agent plugin
├── physx-js-webidl/     # PhysX WASM bindings
├── asset-forge/         # AI asset generation tools
└── docs-site/           # Documentation (Docusaurus)

Build order: physx-js-webidl → shared → everything else (handled automatically by Turbo)

Commands

Command	Description
bun run dev	Development mode with hot reload
bun run build	Build all packages
bun start	Start production server
bun test	Run test suite
bun run lint	Lint codebase

What bun run dev starts

Service	Port	Description
Client	3333	Vite dev server with hot reload
Server	5555	Game server (Fastify + WebSockets)
CDN	8080	Asset server (Docker nginx)
PostgreSQL	5432	Database (Docker)

Run specific services

bun run dev:client    # Client only (port 3333)
bun run dev:server    # Server only (port 5555)
bun run dev:ai        # Game + ElizaOS agents (adds port 4001)
bun run dev:forge     # AssetForge tools (ports 3400, 3401)
bun run docs:dev      # Documentation site (port 3402)
bun run dev:all       # Everything: game + AI + AssetForge

Docker services

bun run cdn:up        # Start CDN container (needed for bun start)
bun run cdn:down      # Stop CDN container

Database (Drizzle)

Run from packages/server/:

bunx drizzle-kit push      # Push schema changes to database
bunx drizzle-kit generate  # Generate migration files
bunx drizzle-kit migrate   # Run pending migrations

Assets

Game assets (3D models, textures, audio) source: HyperscapeAI/assets

Local Development: Assets are auto-downloaded during bun install (~200MB via Git LFS).

bun run assets:sync    # Pull latest assets from repo (local dev only)

Production/CI: Manifests are committed to the repo at packages/server/world/assets/manifests/.

Configuration

Required for local development:

• packages/client/.env - Set PUBLIC_PRIVY_APP_ID
• packages/server/.env - Set PUBLIC_PRIVY_APP_ID and PRIVY_APP_SECRET

Both must use the same Privy App ID from Privy Dashboard.

Optional configuration - see .env.example files for all options:

• packages/server/.env.example - Database, ports, LiveKit voice chat
• packages/client/.env.example - API URLs, Farcaster integration
• packages/asset-forge/.env.example - AI API keys (OpenAI, Meshy)
• packages/plugin-hyperscape/.env.example - ElizaOS agent config

Default Ports

Port	Service	Started By
5555	Game Server	bun run dev
3333	Client	bun run dev
8080	Asset CDN	bun run dev
3400	AssetForge UI	bun run dev:forge
3401	AssetForge API	bun run dev:forge
4001	ElizaOS API	bun run dev:ai
3402	Documentation	bun run docs:dev

Troubleshooting

Characters vanishing / not appearing on character select: This happens when Privy credentials are missing. Each page refresh creates a new anonymous user, orphaning your characters. Fix: Set PUBLIC_PRIVY_APP_ID in client .env and both PUBLIC_PRIVY_APP_ID + PRIVY_APP_SECRET in server .env.

Assets not loading (404 errors for models/avatars): The CDN container needs to be running. It starts automatically with bun run dev, but if you're running services separately:

bun run cdn:up

Database schema errors or stale data after pulling updates: Migrations only run once, so pulling new code won't fix an outdated database schema. Reset to fresh:

⚠️ Warning: This will delete all local data (characters, inventory, progress).

# Stop and remove postgres container
docker stop hyperscape-postgres 2>/dev/null; docker rm hyperscape-postgres 2>/dev/null

# Remove postgres volumes
docker volume rm hyperscape-postgres-data 2>/dev/null; docker volume rm server_postgres-data 2>/dev/null

# Remove any remaining hyperscape volumes
docker volume ls | grep -i hyperscape | awk '{print $2}' | xargs -r docker volume rm

# Verify volumes are gone
docker volume ls | grep -i hyperscape

# Restart with fresh database
bun run dev

Port conflicts:

lsof -ti:5555 | xargs kill -9   # Server
lsof -ti:3333 | xargs kill -9   # Client
lsof -ti:8080 | xargs kill -9   # CDN

Build errors:

bun run clean
rm -rf node_modules packages/*/node_modules
bun install
bun run build

No Docker? You need external services:

• Set DATABASE_URL in packages/server/.env to an external PostgreSQL (e.g., Neon)
• Set PUBLIC_CDN_URL in both server and client .env to your asset hosting URL

More Info

See CLAUDE.md for detailed development guidelines, architecture documentation, and coding standards.

License

MIT