Wiki

In-depth technical documentation for Hyperscape

Welcome to the Hyperscape Wiki

This wiki provides comprehensive technical documentation for Hyperscape, an AI-powered RuneScape-style MMORPG built on a custom 3D multiplayer engine. Every page is verified against the actual source code.

This documentation is generated from source code analysis. All code references link to actual files in the Hyperscape repository.

---

Quick Navigation

Engine Architecture

ECS architecture, Three.js integration, PhysX physics, and the core World system

Game Systems

Combat, skills, economy, inventory, and all gameplay mechanics

AI Agents

ElizaOS integration, actions, providers, and autonomous gameplay

Data Manifests

NPCs, items, world areas, and manifest-driven content

---

Repository Structure

The Hyperscape monorepo contains 7 packages managed by Turbo:

hyperscape/
├── packages/
│   ├── shared/              # Core 3D engine (ECS, Three.js, PhysX)
│   ├── server/              # Game server (Fastify, WebSockets, PostgreSQL)
│   ├── client/              # Web client (Vite, React 19)
│   ├── plugin-hyperscape/   # ElizaOS AI agent plugin
│   ├── physx-js-webidl/     # PhysX WASM bindings
│   ├── asset-forge/         # AI asset generation (MeshyAI, GPT-4)
│   └── docs-site/           # Docusaurus documentation
├── world/                   # World configuration and manifests
└── assets/                  # Shared game assets

Build Dependency Graph

Packages must build in this order due to dependencies:

The first build takes 5-10 minutes due to PhysX WASM compilation. Subsequent builds use cache.

---

Tech Stack

Runtime

Technology	Version	Purpose
Bun	v1.1.38+	JavaScript runtime and package manager
Turbo	Latest	Monorepo build orchestration
Node.js	18+	Fallback compatibility

3D Engine

Technology	Version	Purpose
Three.js	0.180.0	3D rendering
PhysX	WASM	Physics simulation
VRM	@pixiv/three-vrm	Avatar format support

Backend

Technology	Version	Purpose
Fastify	5.x	HTTP server
WebSockets	@fastify/websocket	Real-time multiplayer
PostgreSQL	Via Neon	Production database
SQLite	Local	Development database
Drizzle ORM	Latest	Database abstraction

Frontend

Technology	Version	Purpose
React	19.2.0	UI framework
Vite	Latest	Build tool with HMR
Capacitor	Latest	iOS/Android mobile builds
styled-components	Latest	Component styling

AI

Technology	Purpose
ElizaOS	AI agent framework
OpenAI	GPT-4o for generation
Anthropic	Claude for decisions
OpenRouter	Multi-provider routing
MeshyAI	3D model generation

---

Port Allocation

All services use unique ports to avoid conflicts:

Port	Service	Environment Variable	Started By
3333	Game Client	VITE_PORT	bun run dev
3400	AssetForge UI	ASSET_FORGE_PORT	bun run dev:forge
3401	AssetForge API	ASSET_FORGE_API_PORT	bun run dev:forge
3402	Docusaurus	(hardcoded)	bun run docs:dev
4000	ElizaOS Dashboard	(internal)	bun run dev:ai
4001	ElizaOS API	ELIZAOS_PORT	bun run dev:ai
5555	Game Server	PORT	bun run dev

---

Development Commands

Core Development

# Install dependencies
bun install

# Build all packages (required before first run)
bun run build

# Development mode with hot reload
bun run dev

# Start game server (production mode)
bun start

# Build individual packages
bun run build:shared    # Core engine (build first)
bun run build:client    # Web client
bun run build:server    # Game server

# Development mode for specific packages
bun run dev:shared      # Shared with watch
bun run dev:client      # Client with HMR
bun run dev:server      # Server with restart

# Core game + ElizaOS agents
bun run dev:elizaos

# Everything: game + AI + AssetForge
bun run dev:all

# iOS
npm run ios             # Build, sync, open Xcode
npm run ios:dev         # Sync and open

# Android
npm run android         # Build, sync, open Android Studio
npm run android:dev     # Sync and open

# Capacitor sync
npm run cap:sync        # Both platforms

---

Wiki Sections

Engine Architecture

Deep dive into the Hyperscape 3D engine:

• Engine Overview — Architecture and core concepts
• Entity Component System — Entities, components, and systems
• Networking — WebSocket protocol, packets, sync
• Database Schema — PostgreSQL persistence with Drizzle
• Event System — 500+ typed events

Game Systems

All gameplay mechanics:

• Systems Overview — How game systems work
• Combat System — Tick-based OSRS-style combat
• Skills System — 9 trainable skills with XP curves
• Movement — Tile-based navigation and pathfinding

AI Agents

ElizaOS integration:

• AI Overview — How AI agents play
• Actions Reference — 21 available agent actions
• Providers Reference — 7 state providers

Data Manifests

Content definitions:

• Data Overview — Manifest-driven design
• NPC Data Structure — Enemy definitions, aggro, drops
• Item Data Structure — Weapons, armor, tools, resources

Technical Reference

• Constants Reference — Combat, movement, timing values