Skip to main content

​
Monorepo Structure

Hyperscape is organized as a Turbo monorepo with 7 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)
├── asset-forge/         # AI asset generation (3d-asset-forge)
├── website/             # Marketing website (@hyperscape/website)
└── docs-site/           # Documentation (Docusaurus)

​
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, UI toolkit, and 3D rendering

plugin-hyperscape

ElizaOS integration for AI agents

website

Marketing website with Next.js and Three.js

asset-forge

AI-powered 3D asset generation

​
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 (includes UI toolkit)
@hyperscape/plugin-hyperscape1.0.0ElizaOS plugin
@hyperscape/website0.13.0Marketing website
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.1.38+). 
bun install             # Install all dependencies
bun run <script>        # Run package scripts
bun start               # Start production server

​
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.1.38

​
License

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