Package Overview

Overview of all packages in the Hyperscape monorepo

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

Package	Version	Description
@hyperscape/shared	0.13.0	Core engine
@hyperscape/server	0.13.0	Game server
@hyperscape/client	0.13.0	Web client (includes UI toolkit)
@hyperscape/plugin-hyperscape	1.0.0	ElizaOS plugin
@hyperscape/website	0.13.0	Marketing website
3d-asset-forge	1.0.0	Asset 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

Requirement	Version
Node.js	≥22.11.0
Bun	≥1.1.38

License

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