threers
A drop-in three.js replacement for Rust and the browser, backed by wgpu. The same Rust core runs natively (winit) and as WebAssembly, with a JavaScript shim that exposes the familiar THREE.* API so existing three.js code can run with minimal changes.
Current version: 0.0.2 · Changelog
Table of contents
Features
- Scene graph (
Object3D,Scene, transforms, layers) - Buffer geometries, PBR materials, lights, shadows, fog
- Custom WGSL materials via
ShaderMaterial - wgpu renderer with post-processing (FXAA, bloom, SSAO, glitch, halftone, …)
- Loaders (glTF, OBJ, STL, HDR, …), animation, controls, helpers
- Headless offscreen render → tightly packed RGBA (
HeadlessRenderer, native) - Video export (
video) — frame sequence → ffmpeg; native GIF whennative-codecis on - Native codecs (
native-codec) — pure-Rust GIF (encode/decode), APNG, VP9/WebM, HEVC/MP4; wasm-safe - Opt-in mesh BVH (
mesh-bvh) — accelerated raycast / shapecast (three-mesh-bvh–compatible) - Opt-in CSG (
bvh-csg) — boolean ops onBufferGeometry(three-bvh-csg–compatible); Rust native + JS addon - Web:
web/threejs-shim.js+ wasm — drop-inTHREE.*replacement targeting three.js r165 - Native: winit examples for desktop development and debugging
Quick start
Native (desktop)
Requires Rust 1.75+, a working wgpu backend (Metal/Vulkan/DX12), and dev dependencies from Cargo.toml.
Optional: mesh-bvh / CSG
# BVH picking demo
# Hierarchy CSG (exact TriKey parity with JS three-bvh-csg@0.0.16)
// Cargo.toml: threers = { version = "0.0.2", features = ["bvh-csg"] }
use ;
let mut ev = new;
let mut a = new;
let mut b = new;
let _geom = ev.evaluate;
Headless render & video export
Native-only. HeadlessRenderer owns the wgpu device and an offscreen target; export_video pipes RGBA frames to ffmpeg (or the in-process GIF encoder when both features are enabled).
// Cargo.toml: threers = { version = "0.0.2", features = ["video"] }
use ;
let mut hr = builder.size.build.unwrap;
let opts = new.fps.codec;
// export_video(w, h, frame_count, &opts, |i| { /* advance scene */; hr.render_to_rgba(...) })
GIF without spawning ffmpeg:
// features = ["video", "native-codec"]
let opts = new
.fps
.codec
.transparent
.gif_colors;
Native codecs (GIF, APNG, VP9, HEVC)
Enable native-codec for dependency-free encoders (and a GIF decoder) that also build on wasm32:
// Cargo.toml: threers = { version = "0.0.2", features = ["native-codec"] }
use ;
let mut enc = new
.colors
.dither
.diff_rects
.palette_mode;
// enc.add_frame(&rgba, 1, 10);
let bytes = enc.finish;
let = decode_gif.unwrap;
See threers::codec module docs and tests/{gif,apng,webm,hevc_*}.rs for VP9/WebM, APNG, and HEVC usage.
Web (browser)
Build the wasm package and serve the repo root (or use the parity server below):
# Default (no mesh-bvh / CSG addon)
&&
# Or via the feature build scripts:
MESH_BVH=1 BVH_CSG=1
Then load web/examples/index.html or any page that imports /web/threejs-shim.js and calls initThreers('/web/pkg/threers_bg.wasm').
import THREE from '/web/threejs-shim.js';
await ;
const renderer = await THREE.;
// … same patterns as three.js
CSG in the browser (after BVH_CSG=1 build):
import from '/web/bvh-csg-addon.js';
;
Parity compare UI
Side-by-side three.js r165 vs threers wasm for 113 regression scenes:
Open http://localhost:8087/ — navigate scenes, toggle light/dark theme, view source (JS / TS / Rust tabs).
CI helpers: scripts/ci-mesh-bvh.sh, scripts/ci-bvh-csg.sh.
After changing Rust or wasm, rebuild and hard-refresh the browser (⌘⇧R) or click ↻ in the compare UI so cached wasm/shim are busted.
Project layout
src/ Rust library (scene graph, renderer, loaders, …)
codec/ Pure-Rust media codecs (`native-codec`)
video.rs Frame-sequence export (`video`, native)
renderer/ wgpu pipelines, post-fx, headless offscreen
materials/ PBR + ShaderMaterial
csg/ Rust CSG (`bvh-csg`) — Evaluator, Brush, hierarchy
mesh_bvh/ Rust BVH (`mesh-bvh`)
wasm.rs #[wasm_bindgen] exports (web only)
web/
threejs-shim.js THREE-compatible JS API over wasm
csg/ JS three-bvh-csg port (loaded when BVH_CSG=1)
mesh-bvh-*.js mesh-bvh addon / stub
pkg/ wasm-pack output (threers.js, threers_bg.wasm)
post-build.sh Patches wasm glue for Safari; generates .d.ts
tests/ Codec / video integration tests + parity/
examples/ Native demos (cube, headless_video, shader_material, …)
scripts/ Feature CI (mesh-bvh, bvh-csg)
CHANGELOG.md Release history
Architecture
┌─────────────────────────────────────────────────────────┐
│ Browser: three.js app code (or parity scene HTML) │
│ ↓ import │
│ web/threejs-shim.js ──► wasm WebRenderer / WebScene │
│ (+ optional mesh-bvh / bvh-csg addons) │
└──────────────────────────────┬──────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ Rust: Scene → Renderer (wgpu) → surface or RenderTarget │
│ Materials / lights / post-fx (EffectComposer) │
│ Optional: MeshBvh, CsgEvaluator │
│ Optional: HeadlessRenderer → video / native-codec │
└──────────────────────────────────────────────────────────┘
- Native path:
Renderer::new(device, queue, format)→render()/render_to(); orHeadlessRendererfor offscreen RGBA. - Web path:
WebRendererowns the wgpu surface for a<canvas>; render targets and post-fx are registered by integer id across the JS boundary. - Post-fx: A single WGSL module (
src/renderer/shader.rs) switches oneffect_kind(copy, FXAA, glitch, bloom, …). The JSEffectComposermirrors three.js pass order. - CSG: Rust
CsgEvaluatorfor native/tests; browser parity scenes use the JS port underweb/csg/with wasm BVH for splits. - Codecs:
native-codecencodes/decodes in-process (no ffmpeg);videoshells out to ffmpeg except for GIF when both features are enabled.
Development
| Task | Command |
|---|---|
| Native check | cargo build |
| With CSG | cargo build --features bvh-csg |
| Video + codecs | cargo build --features "video,native-codec" |
| CSG unit/parity tests | cargo test --features bvh-csg --lib csg |
| GIF codec tests | cargo test --features native-codec --lib codec::gif --test gif |
| Wasm release | wasm-pack build --target web --out-dir web/pkg && bash web/post-build.sh |
| Feature wasm | BVH_CSG=1 web/build.sh / MESH_BVH=1 web/build.sh |
| Parity scenes | cd tests/parity && node generate-scenes.js |
| Rust scene snippets (parity UI Rust tab) | cd tests/parity && node generate-rust-scenes.js |
| Regenerate shim types | node web/scripts/generate-shim-types.mjs (also runs in post-build) |
| Docs | cargo doc --features "video,native-codec" --open |
Status
Active development toward pixel parity with three.js r165 on the core parity scene set. Opt-in mesh-bvh and bvh-csg suites report 0% pixel diff on their dedicated manifests; hierarchy CSG also has exact ordered TriKey topology parity in Rust vs JS.
Some core scenes are approximate (PMREM, SSR, etc.) — the compare UI marks these and stores diff percentages in compare-results.json. See PLAN.md for feature roadmap notes and CHANGELOG.md for release history.
License
MIT