Skip to main content

​
Monorepo Structure

Hyperscape is organized as a Turbo monorepo with core packages: 
packages/
├── shared/              # Core 3D engine (@hyperscape/shared)
├── server/              # Game server (@hyperscape/server)
├── client/              # Web client (@hyperscape/client)
├── plugin-hyperscape/   # ElizaOS AI plugin (@hyperscape/plugin-hyperscape)
├── physx-js-webidl/     # PhysX WASM bindings (@hyperscape/physx-js-webidl)
├── procgen/             # Procedural generation (@hyperscape/procgen)
├── asset-forge/         # AI asset generation + VFX catalog (3d-asset-forge)
├── duel-oracle-evm/     # EVM duel outcome oracle contracts
├── duel-oracle-solana/  # Solana duel outcome oracle program
├── contracts/           # MUD onchain game state (experimental)
└── website/             # Marketing website (@hyperscape/website)
Note: The betting stack (gold-betting-demo, evm-contracts, sim-engine, market-maker-bot) has been split into a separate repository: HyperscapeAI/hyperbet

​
Package Dependencies

asset-forge is independent and doesn’t depend on other packages.

​
Package Summary

shared

Core 3D engine with ECS, Three.js, PhysX, and networking

server

Game server with Fastify, WebSockets, and database

client

Web client with Vite, React, and 3D rendering

plugin-hyperscape

ElizaOS integration for AI agents

asset-forge

AI-powered 3D asset generation

website

Marketing website with Next.js 15 and React Three Fiber

​
Build Order

Due to dependencies, packages must build in order:
  1. physx-js-webidl (5-10 min first time, cached after)
  2. shared (depends on physx)
  3. All other packages (depend on shared)
Turbo handles this automatically with dependsOn: ["^build"].

​
Package Versions

PackageVersionDescription
@hyperscape/shared0.13.0Core engine
@hyperscape/server0.13.0Game server
@hyperscape/client0.13.0Web client
@hyperscape/plugin-hyperscape1.0.0ElizaOS plugin
3d-asset-forge1.0.0Asset generation

​
Package Commands

​
Build

bun run build           # Build all packages
bun run build:shared    # Build shared only
bun run build:client    # Build client only
bun run build:server    # Build server only

​
Development

bun run dev             # All packages with watch
bun run dev:shared      # Shared with watch
bun run dev:client      # Client with HMR (port 3333)
bun run dev:server      # Server with restart (port 5555)
bun run dev:elizaos     # With AI agents

​
Testing

npm test                # Run all tests (Playwright)

​
Package Manager

All packages use Bun as the package manager and runtime (v1.3.10+, updated from v1.1.38). 
bun install             # Install all dependencies
bun run <script>        # Run package scripts
bun start               # Start production server
bun run duel            # Start streaming duel stack

​
Workspaces

Defined in root package.json: 
{
  "workspaces": ["packages/*"]
}
Cross-package imports use workspace protocol: 
{
  "dependencies": {
    "@hyperscape/shared": "workspace:*",
    "@hyperscape/plugin-hyperscape": "workspace:*"
  }
}

​
Engine Requirements

RequirementVersion
Node.js≥22.11.0
Bun≥1.3.10
Vitest≥4.0.6 (for Vite 6 compatibility)

​
License

  • Core packages: GPL-3.0-only
  • plugin-hyperscape: MIT
  • asset-forge: MIT