voxelize 3.0.0

A fast multiplayer voxel engine.
Documentation

Town, a production world built on Voxelize

Why Voxelize

Voxelize powers persistent, multiplayer voxel worlds that run in any modern browser. No installs, no plugins.

  • Build custom blocks: register any blocks of any shape, size, and material. Blocks can also hold custom metadata through block entities.
  • Create custom entities: pigs, cows, sheeps, any entities you can imagine. They can roam around and interact with blocks and players.
  • Realtime multiplayer: authoritative server with entity, chat, and event synchronization out of the box.
  • Any world generation: define your own world generation and generate infinitely large worlds.

Architecture

Both the server and the client are extremely optimized for performance and scalability. The server is written in Rust, and the client is written in TypeScript.

┌───────────────────────────────┐                      ┌───────────────────────────────┐
│   Browser client (TS)         │      WebSocket       │   Authoritative server (Rust) │
│                               │◄────────────────────►│                               │
│   @voxelize/core (Three.js)   │  @voxelize/protocol  │   voxelize (ECS worlds)       │
│   physics-engine · raycast    │  @voxelize/transport │   voxelize-mesher (meshing)   │
│   voxelize-wasm-mesher (WASM) │  (shared protobuf)   │   voxelize-core (voxel data)  │
└───────────────────────────────┘                      └───────────────────────────────┘
  • Rust authoritative server — voxelize runs ECS-driven worlds: chunk generation, physics, entities, and events all live server-side.
  • TypeScript / Three.js client — @voxelize/core renders worlds in the browser and stays in sync over WebSocket.
  • Shared protocol and transport — @voxelize/protocol defines the protobuf messages; @voxelize/transport moves them.
  • WASM meshing — voxelize-wasm-mesher compiles the server's mesher to WebAssembly, so client-side remeshing follows the same geometry rules as server-side meshing.
  • Headless agents — @voxelize/agent drives real browser clients headlessly for testing, measurement, and bots.

In Production

Town is a live, persistent multiplayer building world built on Voxelize, with custom textures, entities, and more.

Quick Start

Prerequisites: Rust, Node.js, pnpm, cargo-watch, wasm-pack, and protoc.

git clone https://github.com/voxelize/voxelize.git
cd voxelize

pnpm install   # install dependencies
pnpm proto     # generate protocol buffers
pnpm build     # build WASM mesher + all packages
pnpm demo      # run the demo server and client

Then open http://localhost:3000.

I strongly recommend using Voxelize as a submodule of the workspace you're building.

Packages

npm

Package Description
@voxelize/core The client engine: rendering, world sync, inputs, and utilities on Three.js
@voxelize/agent Headless puppeteer-backed agent SDK for Voxelize worlds
@voxelize/transport WebSocket transport for Voxelize protocol messages
@voxelize/protocol Shared protobuf message definitions
@voxelize/physics-engine Voxel-aware AABB physics with auto-stepping
@voxelize/raycast Voxel raycasting
@voxelize/debug In-game debug panels
@voxelize/aabb Axis-aligned bounding box math

Rust crates

Crate Description
voxelize The authoritative multiplayer server engine
voxelize-core Core types and utilities — the single source of truth for voxel data encoding
voxelize-mesher Chunk meshing logic
voxelize-wasm-mesher WebAssembly wrapper around the mesher for client-side use

Documentation

Development

Useful workspace commands:

pnpm watch        # rebuild TS packages and WASM mesher on change
pnpm test         # TypeScript tests (vitest)
pnpm test:rust    # Rust mesher and lighting tests
pnpm bench        # criterion benchmarks (mesher, lights)
pnpm check        # cargo check across all targets
pnpm lint         # eslint with autofix

Notes on faster local builds:

  • The server watch loop (pnpm demo:rs) builds with the release-dev profile: the same opt-level = 3 runtime performance as release, but with incremental compilation and minimal debug info for much faster edit-rebuild cycles. Published builds should keep using --release.
  • If you consume Voxelize as a submodule of a parent cargo workspace, cargo takes profiles from the parent's root Cargo.toml — copy the [profile.release-dev] block there to get the same fast iteration.
  • Rust >= 1.90 links with the fast bundled rust-lld on x86_64 Linux out of the box; see .cargo/config.toml for opt-in lld linking on other platforms and an opt-in sccache shared cache.

Community

Questions, showcases, and engine discussion happen on Discord. Issues and pull requests are welcome on GitHub.

License

MIT

Assets Used

Voxelize is an independent open-source project. It is not affiliated with, endorsed by, or connected to any commercial voxel game or its publishers.