bevy_pbr

Physically based rendering. Materials, lighting, shadows, the deferred pipeline, environment maps, and clustered light culling. The largest pure-rendering crate at ~60 source files.

Purpose

bevy_pbr implements a physically based render pipeline for 3D meshes. It provides:

• StandardMaterial and the Material trait specialization for PBR.
• Light types (point, spot, directional) with clustered shading, plus shadows for each.
• Render passes — the forward and deferred prepass, the main 3D opaque/alpha-mask/transparent passes, the shadow pass, and the deferred lighting pass.
• Environment maps (skybox, irradiance, specular).
• Lightmaps, screen-space ambient occlusion (SSAO), screen-space reflections (SSR), volumetric fog, and other PBR-related effects.
• WGSL shader libraries (pbr_*.wgsl) shared across passes.

Directory layout

crates/bevy_pbr/src/
├── lib.rs                # PbrPlugin
├── pbr_material.rs       # StandardMaterial
├── light/                # PointLight, SpotLight, DirectionalLight
├── cluster/              # Clustered light culling
├── render/               # Render systems and shaders
│   ├── mesh.rs           # The big one (4,700 lines): mesh draw + GPU instance buffers
│   ├── prepass/          # Depth/normal/motion-vector prepass
│   ├── deferred/         # Deferred g-buffer + lighting
│   ├── light/            # Per-light render code
│   └── …
├── ssao.rs               # Screen-space ambient occlusion
├── ssr.rs                # Screen-space reflections
├── volumetric_fog.rs
├── meshlet/              # Meshlet rendering (experimental)
├── irradiance_volume.rs
├── lightmap.rs
├── decal/                # Decal projection
└── …

Key abstractions

Type	File	Description
PbrPlugin	crates/bevy_pbr/src/lib.rs	Adds the PBR pipeline to the render SubApp.
StandardMaterial	crates/bevy_pbr/src/pbr_material.rs	The default PBR material (base color, metallic, roughness, normal map, etc).
MeshMaterial3d<M>	crates/bevy_pbr/src/material.rs	Component pairing an entity with a Material asset.
PointLight / SpotLight / DirectionalLight	crates/bevy_light (data) + crates/bevy_pbr/src/light/ (rendering)	The three light kinds.
ShadowFilteringMethod	crates/bevy_pbr/src/cluster/	Hardware vs PCF/PCSS shadow sampling.
EnvironmentMapLight	crates/bevy_pbr/src/environment_map.rs	Per-camera component for IBL lighting.
Lightmap	crates/bevy_pbr/src/lightmap.rs	Baked lighting texture component.
ScreenSpaceAmbientOcclusion	crates/bevy_pbr/src/ssao.rs	SSAO settings component.
ScreenSpaceReflections	crates/bevy_pbr/src/ssr.rs	SSR settings component.
VolumetricFog	crates/bevy_pbr/src/volumetric_fog.rs	Volumetric fog component.

How it works

Forward and deferred

bevy_pbr runs both forward and deferred pipelines in the same render graph; cameras opt into a deferred pipeline by adding DeferredPrepassPlugin and the relevant prepass components. The forward path is simpler (mesh → material → done in one pass) and ships by default; deferred trades extra bandwidth for cheap lighting on scenes with many lights.

Clustered lighting

Lights are binned into a 3D cluster grid in view space (cluster/). The fragment shader samples only the lights that overlap its cluster, which keeps per-pixel light cost roughly constant in scenes with many small lights.

Shadows

Each shadow-casting light gets a depth render pass into a shadow-atlas texture. Sampling happens in the main fragment shader with PCF or PCSS filtering depending on ShadowFilteringMethod. Cascaded shadow maps for directional lights are in light/directional_light.rs.

Materials

The Material trait (defined in bevy_material) is implemented by StandardMaterial here. Each material declares:

• A WGSL fragment shader (default: pbr.wgsl).
• A bind-group layout for its uniforms.
• A specialization key for the pipeline cache.

Custom materials are written by implementing the trait and adding MaterialPlugin::<M>.

Mesh rendering

render/mesh.rs is the engine's mesh-draw hot path. It batches meshes into GPU instance buffers, runs visibility culling per cluster, and produces phase items (Opaque3d, AlphaMask3d, Transparent3d) for the core 3D render passes.

Meshlets

The meshlet/ directory contains an experimental meshlet renderer that uses GPU-driven culling and amplification shaders. Activated behind a cargo feature; not on by default.

Integration points

• Depends on: bevy_render, bevy_camera, bevy_light, bevy_material, bevy_image, bevy_mesh, bevy_core_pipeline, bevy_asset, bevy_color.
• Depended on by: Most users (via DefaultPlugins), bevy_gltf (which spawns StandardMaterial instances), bevy_solari (which augments PBR with ray-traced GI).

Entry points for modification

• Custom material: new file under crates/bevy_pbr/src/. Implement Material (or just write your own outside bevy_pbr). The examples/shader/ directory has worked examples.
• New post-effect tied to PBR: add a render-graph node and a corresponding component. SSAO/SSR/volumetric fog are templates.
• Shadow technique: edit light/ and the shadow shaders (pbr_lighting.wgsl etc). Filtering options are in cluster/.
• Cluster sizing: cluster/light_cluster.rs. The defaults are heuristic; tune for your scene.

See also

• bevy_render for the underlying render graph.
• bevy_light for the data-only light components.
• bevy_material for the Material trait.
• bevy_solari for experimental ray-traced GI.
• Rendering pipeline feature page.