日本語 · GitHub · Sample gallery · Guide to examples and samples
Build 3D applications with light, materials, and motion using JavaScript and WebGPU.
webg is a self-contained library that combines PBR, environment lighting, water surfaces and caustics, CPU/GPU physics simulation, animation, particles, and sound.
You can move from high-level application development to direct control of Render Passes, Compute Passes, and WGSL while using the same scenes and models.
Rotary Tablet Machine — Explore how the dies and punches rotate past stationary cams and rollers through filling, compression, and ejection. Run the sample · Explanation and code
Click an image to run the sample in a WebGPU-enabled browser. Each sample’s explanation page guides you through its implementation and the APIs it uses.
![]() PBR and environment lighting See how metallic and roughness change a material's appearance. Explanation and code |
![]() Transparency, refraction, and absorption Glass refraction and background blur controlled by roughness. Explanation and code |
![]() Water surfaces and caustics Wave-driven reflection and refraction, with caustics applied to selected objects. Explanation and code |
![]() Procedural materials Generate wood, brick, stone, and gravel patterns at physical scale. Explanation and code |
![]() CPU/GPU physics simulation Compare rigid-body motion and contact with the same initial conditions. Explanation and code |
![]() A small 3D game Combine selection, movement, combat, animation, and particles. Explanation and code |
Physically based rendering (PBR) uses base color, metallic, roughness, specular reflection, and emission to represent materials under direct light and image-based lighting (IBL). High dynamic range (HDR) environment maps, glTF 2.0 core materials, and procedural environments are available. Deferred rendering for opaque objects and forward rendering for translucent objects share a GGX reflection model and linear-HDR color processing.
Transparent materials support refractive index, thickness, color absorption, and roughness-dependent background blur.
ComputeEffectPipeline connects shadows, screen-space ambient occlusion (SSAO), screen-space reflections (SSR), fog, depth of field (DoF), bloom, tone mapping, and other effects.
The high-level PbrRenderer can also configure lighting, environments, and screen effects together.
WaterBody configures the water region, wave mixing, wavelength, speed, refractive index, and color absorption.
Water-surface reflection and refraction, and caustics—the light concentrated by waves onto the waterbed and objects—are calculated from the same wave field.
Register opaque Shape or Node receivers and adjust the intensity for each object.
The surface and caustics can be switched independently. Turning both off releases water-specific GPU resources and returns to the regular PBR pipeline. The core water surface supports finite horizontal water regions viewed from above. Caustics use an approximation that projects vertically directed light from a reference plane onto 3D objects. The aquarium sample also includes its own water-surface rendering for underwater viewpoints. The scope of each effect is described in the water sample documentation.
Generate wood, brick, tile, stone, and other materials from dimensions in meters.
Color, height, and normals are handled separately, with presets for rounded stones, mixed stones and gravel, and gravel alone.
Combining ProceduralMaterials with physical-scale UVs produces patterns suited to the size of each object.
Build meshes with Shape, create basic geometry with Primitive, load external models such as glTF/GLB, and instantiate models multiple times.
Node hierarchies, multiple materials, skinning, and keyframe animation connect to the same scene.
The CPU-based PhysicsSpace and the GPU-based ComputePhysicsSpace, which updates rigid bodies with Compute Shaders, are available.
They support contact between boxes, spheres, capsules, and fixed planes, along with gravity, friction, rotation, sleeping, and joint constraints.
| Selection criterion | CPU engine | GPU engine |
|---|---|---|
| Application structure | Integrate with Node operations and JavaScript game logic | Update and render many rigid bodies on the GPU |
| Access to state | Use CPU state for queries and contact events | Explicitly read back GPU state when needed |
| Rendering integration | Use the position and orientation of PhysicsNode |
Render directly from GPU state or synchronize it to Nodes |
Choose based on object count, shape, update frequency, and the information your CPU-side logic needs. samples/compute_physics compares the CPU and GPU engines with the same initial conditions. samples/karakuri demonstrates an application combining editing and simulation.
Connect keyframes, interpolation, animation state transitions, GPU particles, and cloth updates to rendering. Mouse, touch, pen input, camera controls, click selection, HUDs, and control panels use a common application foundation. Sound synthesis, background music, and sound effects are available through the Web Audio API.
If you are new to webg, use the guide to examples and samples to find an example close to what you want to build.
book/examples/ contains small runnable examples for individual chapters; samples/ contains reference applications combining multiple features.
WebgApp, Space, Node, and Shape. See high_level.createWebgSceneApp() and SceneDefinition. See project_app.PbrRenderer and ComputeEffectPipeline. See the PBR integration example.ComputePass and run GPU computation before rendering. See compute_particles.WebgApp brings together GPU initialization, scenes, cameras, input, UI, and the update/render loop.
WebgSceneApp builds models, materials, PBR, and physics from SceneYAML/JSON application definitions.
You can follow the lower-level Render API, Compute API, and WGSL as needed to control execution order and GPU resources directly.
git clone https://github.com/jun-mizutani/webg.git
cd webg
python3 -m http.server 8000
Open http://localhost:8000/samples/index.en.html in your browser.
Serve the repository over HTTP and retain its directory structure for ES Modules and asset loading.
The library itself can be used through relative JavaScript imports.
The English book is available in book.en/. Its entry guide maps application goals to runnable examples, code to read, and checks to make. The companion browser guide provides the same navigation in the browser.
The chapters progress from minimal rendering through application structure, models, interaction, physics, PBR, and GPU processing. Each chapter links its explanation to runnable examples in book/examples/ and larger applications in samples/.
The documentation helps both people and coding AI agents find relevant examples and APIs. When asking an AI to implement an application, provide Appendix A for coding AI agents and an example close to the goal. For migration from webg 1.0/2.0, see Appendix B.
Use a WebGPU-enabled browser and GPU, and run applications on localhost or HTTPS.
Available features and performance depend on the browser, OS, GPU, and driver.
GPU timing measurements require timestamp-query support.
compute_benchmark measures PBR rendering, lighting, reflections, transparency composition, and other stages under the same scene conditions.
headless_tests/ contains automated tests for API and data contracts; unittest/ contains browser applications for visual checks.
node headless_tests/run_all.js
MIT License · Jun Mizutani · Author’s website