Package Overview

Overview of all packages in the Hyperscape monorepo

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

Package	Version	Description
@hyperscape/shared	0.13.0	Core engine
@hyperscape/server	0.13.0	Game server
@hyperscape/client	0.13.0	Web client
@hyperscape/plugin-hyperscape	1.0.0	ElizaOS plugin
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.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

Requirement	Version
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