zephyr3d

What is Zephyr3D

Zephyr3D is a 3D rendering engine for the browser, written in TypeScript. It gives you two
levels to work at, and a visual editor on top of both:

• Device API — a graphics abstraction over WebGL, WebGL2 and WebGPU, including a shader
  system where you write shaders in TypeScript and the engine generates GLSL or WGSL per backend.
• Scene API — a complete renderer built on the Device API: scene graph, PBR materials,
  clustered lighting, shadows, character rendering, terrain, water, animation and post-processing,
  organized behind a render graph.
• Editor — a browser-based visual editor, plus an Electron desktop build with local projects
  and an embedded MCP server for agent-driven automation.

FFT ocean wave simulation + buoyancy	Clipmap terrain runtime texturing + grass	Car PBR + IBL + reflections
Clustered lighting hundreds of dynamic lights	Transparency order-independent blending	Characters VRM, skinning, blend shapes

_{Click any image to run it live.}  ·  All demos →

Quick start

npm install --save @zephyr3d/base @zephyr3d/scene @zephyr3d/backend-webgl @zephyr3d/backend-webgpu

A lit sphere you can orbit around:

import { Vector3, Vector4 } from '@zephyr3d/base';
import {
  Scene, Application, LambertMaterial, Mesh,
  OrbitCameraController, PerspectiveCamera, SphereShape,
  DirectionalLight, getInput, getEngine
} from '@zephyr3d/scene';
import { backendWebGL2 } from '@zephyr3d/backend-webgl';

const myApp = new Application({
  backend: backendWebGL2,
  canvas: document.querySelector('#my-canvas')
});

myApp.ready().then(function () {
  const scene = new Scene();
  const light = new DirectionalLight(scene);
  light.lookAt(Vector3.one(), Vector3.zero(), Vector3.axisPY());

  const material = new LambertMaterial();
  material.albedoColor = new Vector4(1, 0, 0, 1);
  new Mesh(scene, new SphereShape(), material);

  scene.mainCamera = new PerspectiveCamera(scene, Math.PI / 3, 1, 100);
  scene.mainCamera.lookAt(new Vector3(0, 0, 4), Vector3.zero(), Vector3.axisPY());
  scene.mainCamera.controller = new OrbitCameraController();
  getInput().use(scene.mainCamera.handleEvent, scene.mainCamera);

  getEngine().setRenderable(scene, 0);
  myApp.run();
});

Real projects usually prefer WebGPU and fall back to WebGL — see
Basic Framework for backend selection, the HTML
scaffold and what each step does. Which packages you actually need depends on your case;
Installation has the breakdown.

Features

Rendering pipeline
Forward+ pipeline organized as a render graph with automatic resource pooling and history
buffers for temporal effects. Clustered lighting, Hi-Z, depth prepass,
GPU picking,
geometry instancing, render bundles,
multi-view rendering.

Materials and lighting
PBR (metallic-roughness and specular-glossiness), image-based
lighting, physical lighting units,
Lambert/Blinn/Unlit, MToon for stylized shading, and a mixin-based
system for custom materials.
Material blueprints author materials
as node graphs in the editor.

Character rendering
Skin with subsurface scattering profiles, eye material with socket occlusion, and hair as both
Kajiya-Kay and Marschner models with strand-level geometry expanded on the GPU.

Shadows
PCF (several variants), PCSS, ESM, VSM, SSM and DOM shadows, with cascaded shadow maps and
receiver bias control. Pick per light based on the quality/cost tradeoff you want.

Post-processing
TAA, SSGI, SSR, SSAO, bloom, motion blur, FXAA, tonemapping, color grading, and separate
subsurface-scattering passes for skin.

Transparency
Three order-independent transparency backends: A-buffer (WebGPU), dual depth peeling, and
weighted blended.

Terrain, sky and water
Clipmap terrain with runtime texturing and
grass layers, atmospheric sky, and
ocean water driven by FFT, Gerstner or FBM wave
generators.

Animation and simulation
Skeletal and keyframe animation with blending, masks and an action controller.
Inverse kinematics (CCD, FABRIK, two-bone),
joint dynamics, spring chains, GPU
cloth, GPU hair simulation,
morph targets and geometry caches.

Asset pipeline
glTF/GLB, FBX, Alembic and hair curve
importers, a
prefab system, virtual file
system, and
reference-counted resources.

The documentation covers these topic by topic — when to use each one,
how to tune it, and its backend limitations — rather than just listing properties.

Shaders in TypeScript

Rather than maintaining parallel GLSL and WGSL sources, you describe the shader once in
TypeScript:

const program = device.buildRenderProgram({
  vertex(pb) {
    this.$inputs.pos = pb.vec3().attrib('position');
    this.$inputs.uv  = pb.vec2().attrib('texCoord0');
    this.$outputs.uv = pb.vec2();

    this.xform = pb.defineStruct([pb.mat4('mvpMatrix')])().uniform(0);

    pb.main(function () {
      this.$builtins.position =
        pb.mul(this.xform.mvpMatrix, pb.vec4(this.$inputs.pos, 1));
      this.$outputs.uv = this.$inputs.uv;
    });
  },

  fragment(pb) {
    this.$outputs.color = pb.vec4();
    this.tex = pb.tex2D().uniform(0);

    pb.main(function () {
      this.$outputs.color = pb.textureSample(this.tex, this.$inputs.uv);
    });
  }
});

From this single source the engine emits WebGL1 GLSL (attributes/varyings, classic uniforms),
WebGL2 GLSL (std140 UBOs, explicit outputs), WGSL, and the matching WebGPU bind group layouts
with computed buffer layouts. Bindings and shader code stay in sync, and you avoid hand-written
variants that drift apart.

The Writing Shaders guide shows the generated output
side by side for each backend.

Editor

Try it in your browser →  · 
Download the desktop build →

The editor is itself built on the Scene and Device APIs. It covers scene editing, the content
browser, node-graph material blueprints, terrain sculpting and texturing, animation editing,
TypeScript scripting bound to scene entities, and a plugin API for custom tools and panels.

The desktop build (Electron) adds local project folders with persistent storage, an embedded
MCP server so AI agents can drive the editor directly, and a built-in LLM assistant. API keys are
stored locally, encrypted at rest.

Editor documentation: overview ·
quick start ·
desktop editor

Support

Zephyr3D is developed and maintained by one person in their free time — the engine, the editor,
the documentation and the demos are all unpaid work. If any of it has been useful to you,
sponsorship is what pays for hosting, CI and testing hardware, and buys focused blocks of time
for new features, performance work and documentation.

Ways to help that cost nothing, but matter just as much:

• Star the repo — it is the main signal that keeps the project visible.
• Ask and answer in Discussions — real
  usage questions shape the docs and the roadmap.
• Report what breaks, with a minimal reproduction if you can. For a rendering engine, a
  screenshot plus the backend and GPU you are on is worth a lot.
• Tell people when a demo or a write-up helped — that reach is how a project like this finds
  the people who end up sponsoring it.

For commercial use, integration help or a support arrangement, open a thread in
Discussions or write to
[email protected] so we can talk about what you need.

Packages

The engine is split so you install only what you use. Packages are versioned independently.

Backend differences

The engine targets three graphics APIs and falls back silently when a capability is missing, so
test on your actual targets rather than assuming that error-free code means a feature is active.

• WebGPU — the full feature set, including compute shaders. Required for A-buffer OIT, DOM
  shadows, GPU cloth and hair simulation, and terrain shading cache.
• WebGL2 — broad coverage, no compute shaders.
• WebGL1 — supported for compatibility, with reduced features (no float depth, limited
  terrain layers, no instancing in some paths).

Zephyr3D also defaults to a reverse-Z depth convention for better far-distance precision,
selected once at load time via the __ZEPHYR3D_REVERSE_Z__ build-time define. If you write custom
materials, use the depth constants exported from @zephyr3d/base (DEPTH_CLEAR_VALUE,
DEPTH_COMPARE_DEFAULT, ...) rather than hard-coding 0 or 1. Full details, including per-backend
behavior and the current limitation around oblique-clipped projections, are in
apps/doc/web/en/reverse-z.md.

Documentation

Documentation is available in English and
简体中文.

The published doc site currently lags this branch: guides for the render graph, character
materials, SSGI, physical lighting and the getting-started walkthrough exist under
apps/doc/web/{en,zh-cn}/ but are not yet deployed.

Status

Actively developed, maintained by one person. The engine is well past prototype — it drives its
own editor and a set of demos — but it has not reached 1.0 and APIs still change between minor
versions. Pin your versions.

It suits you if you are building custom tools or in-house editors, doing web rendering research,
or want to read a complete engine end to end. If you need long-term API stability guarantees
today, that is not something a project at this stage can promise.

Questions and design discussions are best raised in
Discussions; bugs and confirmed feature
requests belong in the issue tracker. If you want to send a pull request, read
CONTRIBUTING.md first — it explains where the project is and is not ready to
take outside code.

License

Released under the MIT License.