Installation

Set up Web Engine for local development. Build from source and run the Studio locally for full control and customization.

While Web Engine runs entirely in the browser with no installation required, local development gives you access to hot reloading, custom builds, the full monorepo structure, and the ability to contribute to the engine.

Prerequisites#

Before you begin, ensure you have the following software installed on your system:

Requirement	Version	Notes
Node.js	≥ 18.0.0	LTS version recommended for stability
pnpm	≥ 8.0.0	Required package manager (npm/yarn not supported)
Git	Latest	For cloning the repository and version control
Rust (optional)	Latest stable	Only needed for WASM module development

Why pnpm?

This project uses pnpm workspaces for efficient monorepo management. pnpm provides faster installs, better disk space usage, and strict dependency isolation. Using npm or yarn will not work correctly.

Installing pnpm#

If you don't have pnpm installed, you can install it globally using npm:

# Install pnpm globally
npm install -g pnpm
 
# Verify installation
pnpm --version
# Should output: 8.15.0 or higher

Alternatively, you can use Corepack (comes with Node.js 16.13+):

# Enable Corepack
corepack enable
 
# Install pnpm via Corepack
corepack prepare pnpm@8.15.0 --activate

Clone the Repository#

Clone the Web Engine repository from GitHub:

# Clone the repository
git clone https://github.com/web-engine/web-engine.git
 
# Navigate to the project directory
cd engine

Development Branch

The main branch contains the latest stable release. For bleeding-edge features, check out the develop branch:

git checkout develop

Install Dependencies#

Install all workspace dependencies across the monorepo:

# Install all dependencies (this may take a few minutes)
pnpm install

This command installs dependencies for all packages and applications in the monorepo, including:

@web-engine-dev/core - Engine runtime and ECS
@web-engine-dev/studio - Visual editor (Next.js)
@web-engine-dev/player - Standalone runtime (Vite)
@web-engine-dev/server - Multiplayer server (Colyseus)
And 10+ shared packages for logging, monitoring, asset pipeline, etc.

Build Core Packages#

Before running the Studio, build the core packages that it depends on:

# Build all core packages (recommended for first-time setup)
pnpm run build:packages
 
# This builds:
# - @web-engine-dev/env
# - @web-engine-dev/config
# - @web-engine-dev/core
# - @web-engine-dev/asset-pipeline
# - @web-engine-dev/game-ui
# - @web-engine-dev/logging
# - @web-engine-dev/monitoring

Alternatively, build individual packages if needed:

# Build a specific package
pnpm --filter @web-engine-dev/core build
 
# Build all packages (slower, includes apps)
pnpm run build

Run the Studio#

Start the Studio in development mode with hot module reloading:

# Start the Studio editor
pnpm --filter @web-engine-dev/studio dev
 
# The Studio will be available at:
# http://localhost:3000

Open your browser and navigate to http://localhost:3000. You should see the Project Hub where you can create or open projects.

First Launch

On first launch, the Studio may take longer to start as Next.js compiles the application. Subsequent starts will be much faster thanks to caching.

Running Other Applications#

The monorepo includes several other applications you can run:

Standalone Player#

The player is a lightweight runtime for playing exported games without the editor:

# Start the player
pnpm --filter @web-engine-dev/player dev
 
# Available at http://localhost:5173

Multiplayer Server#

Run the Colyseus multiplayer server for networked games:

# Start the multiplayer server
pnpm --filter @web-engine-dev/server dev
 
# Server runs on http://localhost:2567

Documentation Site#

Run the documentation site locally (you're reading it now!):

# Start the docs site
pnpm --filter @web-engine-dev/docs dev
 
# Available at http://localhost:3001

Landing Page#

Run the marketing/landing page:

# Start the landing page
pnpm --filter @web-engine-dev/landing dev
 
# Available at http://localhost:3002

Project Structure#

Understanding the monorepo structure will help you navigate the codebase:

engine/
├── apps/
│   ├── studio/         # Visual editor (Next.js 16, React 19)
│   ├── player/         # Runtime player (Vite, Three.js)
│   ├── server/         # Multiplayer server (Colyseus)
│   ├── docs/           # Documentation site (Next.js)
│   └── landing/        # Marketing site (Next.js)
├── packages/
│   ├── core/           # Engine runtime, ECS, systems (~50 components)
│   ├── wasm/           # Rust/WASM modules for performance
│   ├── asset-pipeline/ # Asset import, processing, optimization
│   ├── game-ui/        # UI components for in-game interfaces
│   ├── logging/        # Structured logging system
│   ├── monitoring/     # Performance monitoring and metrics
│   ├── config/         # Shared configuration and branding
│   ├── env/            # Environment detection utilities
│   └── build-config/   # Shared build and TypeScript configs
├── scripts/            # Build scripts and utilities
├── package.json        # Root package.json with scripts
├── pnpm-workspace.yaml # Workspace configuration
├── turbo.json          # Turborepo configuration
└── tsconfig.json       # Root TypeScript configuration

Verify Installation#

Run the test suite to verify everything is set up correctly:

# Run all tests across the monorepo
pnpm test
 
# Run tests for a specific package
pnpm --filter @web-engine-dev/core test
 
# Run end-to-end tests for Studio
pnpm --filter @web-engine-dev/studio test:e2e

If all tests pass, your installation is complete! You should be able to:

Open the Studio at http://localhost:3000
Create a new project from the Project Hub
See the 3D viewport, hierarchy, and inspector panels
Add entities and components to your scene
Enter Play Mode to test your scene

Troubleshooting#

Port Already in Use#

If the default port is already in use, you can specify a custom port:

# Run Studio on a custom port
PORT=4000 pnpm --filter @web-engine-dev/studio dev

Or edit apps/studio/package.json to change the default dev script.

WASM Module Errors#

If you see WASM-related errors, ensure you have Rust installed and build the WASM package:

# Install Rust toolchain (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
# Add wasm32 target
rustup target add wasm32-unknown-unknown
 
# Install wasm-pack
cargo install wasm-pack
 
# Build WASM package
pnpm --filter @web-engine-dev/wasm build

Too Many File Watchers (Linux)#

On Linux, you might hit the file watcher limit with this many packages. Increase it:

# Temporarily increase limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
 
# For permanent fix, add to /etc/sysctl.conf:
# fs.inotify.max_user_watches=524288

JavaScript Heap Out of Memory#

If you encounter heap memory errors during build, increase Node.js memory:

# Increase Node.js heap size
export NODE_OPTIONS="--max-old-space-size=4096"
 
# Then run your build command
pnpm run build:packages

Clean Install#

If you encounter persistent issues, try a clean install:

# Remove all node_modules and build artifacts
pnpm run clean
 
# Clear pnpm cache
pnpm store prune
 
# Reinstall dependencies
pnpm install
 
# Rebuild packages
pnpm run build:packages

Next Steps#

Now that you have Web Engine installed and running locally:

Follow the Quick Start guide to create your first scene
Complete the First Project tutorial to build a simple game
Explore the Editor Overview to learn the interface
Read about the ECS Architecture that powers the engine
Check out Scripting to add custom game logic

PreviousQuick StartGet started in 5 minutes NextFirst ProjectBuild your first game