bevyengine/bevy

bevy_material

The Material trait and its asset glue. Defines the abstraction that ties a mesh to a shader plus uniforms; the actual implementations (PBR, sprite, UI) live in the renderer-specific crates.

Purpose

A "material" in Bevy is the binding between:

A mesh (vertex layout).
A shader (vertex + fragment WGSL).
A bind group of textures and uniforms.
A specialization key that tells the pipeline cache which permutation to compile.

bevy_material provides the trait, the asset infrastructure, and the MeshMaterial3d<M> / MeshMaterial2d<M> components. Concrete implementations are in bevy_pbr (PBR), bevy_sprite_render (sprite), bevy_ui_render (UI), and any user crate.

Directory layout

crates/bevy_material/src/
├── lib.rs                  # Material trait, MaterialPlugin
├── material_bind_groups.rs # Bind group caching
├── extended_material.rs    # User extension on top of a base material
├── alpha.rs                # AlphaMode types
└── …

Key abstractions

Type	File	Description
`Material` (trait)	`crates/bevy_material/src/lib.rs`	The user-facing material abstraction.
`MaterialPlugin<M>`	`crates/bevy_material/src/lib.rs`	Adds a renderer for a specific material.
`MeshMaterial3d<M>` / `MeshMaterial2d<M>`	`crates/bevy_material/src/lib.rs`	Component pairing entity ↔ material handle.
`AlphaMode`	`crates/bevy_material/src/alpha.rs`	Opaque / Mask(threshold) / Blend / AlphaToCoverage.
`ExtendedMaterial<B, E>`	`crates/bevy_material/src/extended_material.rs`	Composes a base material with user extras (extra uniforms, shader defs).

How it works

Material has methods for:

The fragment / vertex shader handle.
The bind-group layout.
The specialization key (for the pipeline cache).
A prepass_fragment_shader (optional, for the depth/normal/motion prepass).

A MaterialPlugin<M> wires up the extract → prepare → queue path for that specific material type. PBR's StandardMaterial is the most-used implementation.

Integration points

Depends on: bevy_app, bevy_ecs, bevy_asset, bevy_render, bevy_shader.
Depended on by: bevy_pbr, bevy_sprite_render, bevy_ui_render, custom material crates.

Entry points for modification

Custom material: implement Material for your asset type, register MaterialPlugin::<MyMaterial>. The examples/shader/ directory has worked examples.
Extension API: ExtendedMaterial lets you add fields without rewriting StandardMaterial. Look at examples/shader/extended_material.rs.