Materials
Make surfaces look right with StandardMaterial, NEO's physically based material: colour, roughness, metal, textures, emission, transparency, transmission and decals.
On this page
A material decides how a mesh's surface reacts to light. StandardMaterial is the engine's physically based material: you describe the surface with real-world properties (how rough it is, whether it's metal) and it looks right under any lighting. Put a material handle in MeshMaterial3d next to a Mesh3d.
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
) {
let gold = materials.add(StandardMaterial {
base_color: Color::srgb(1.0, 0.77, 0.34),
metallic: 1.0,
perceptual_roughness: 0.3,
..default()
});
commands.spawn((Mesh3d(meshes.add(Sphere::new(0.5))), MeshMaterial3d(gold)));
}A Color or an image handle converts straight into a material: materials.add(Color::WHITE), materials.add(asset_server.load("textures/crate.png")).
Materials are assets. Many entities can share one handle, which is cheaper than a material each and lets them draw together. Changing a shared material through Assets<StandardMaterial>::get_mut changes every entity that uses it.
The main properties#
| Field | Default | What it does |
|---|---|---|
base_color | white | The surface colour (albedo). |
base_color_texture | none | An image multiplied with base_color. |
perceptual_roughness | 0.5 | 0 is a mirror, 1 is fully matte. |
metallic | 0.0 | 0 for non-metals (plastic, wood, skin), 1 for metals. Values in between are rarely physical. |
metallic_roughness_texture | none | Roughness from the green channel, metal from the blue channel, multiplied with the two fields above. |
reflectance | 0.5 | Specular strength for non-metals. 0.5 is about 4%, typical for most materials. |
emissive | black | Light the surface gives off, as LinearRgba. Values above 1 glow with bloom. |
emissive_texture | none | Multiplied with emissive. |
normal_map_texture | none | Fine surface detail. The mesh needs tangents: call Mesh::with_generated_tangents() on your own meshes. Set flip_normal_map_y for maps authored for DirectX. |
occlusion_texture | none | Baked ambient occlusion in the red channel. |
unlit | false | Ignores lights and shows base_color as is. |
double_sided, cull_mode | false, back faces | Draw both sides of thin surfaces: set double_sided: true and cull_mode: None. |
fog_enabled | true | Whether fog affects this surface. |
uv_transform | identity | An Affine2 applied to texture coordinates, for tiling and offsets. |
Example: cargo run --example pbr shows a grid of spheres from rough to smooth and from non-metal to metal.
Textures#
Load textures through the asset server. The image formats compiled into NEO's builds are PNG, KTX2 (with Zstandard compression) and HDR. JPEG, WebP, BMP, TGA, EXR and others each need their cargo feature (jpeg, webp, ...), which NEO's builds don't turn on; convert textures to PNG or KTX2 instead, including those inside glTF files.
let material = materials.add(StandardMaterial {
base_color_texture: Some(asset_server.load("textures/brick_color.png")),
normal_map_texture: Some(asset_server.load("textures/brick_normal.png")),
perceptual_roughness: 0.9,
..default()
});Each texture field has a matching *_channel field (UvChannel::Uv0 or Uv1) that picks which texture coordinates it uses.
Parallax mapping#
depth_map with parallax_depth_scale, parallax_mapping_method (ParallaxMappingMethod::Occlusion or Relief { max_steps }) and max_parallax_layer_count fakes depth on flat surfaces. Example: cargo run --example parallax_mapping.
Transparency#
alpha_mode decides how the alpha channel of base_color and its texture is used:
AlphaMode | Use it for |
|---|---|
Opaque | The default. Alpha is ignored. |
Mask(cutoff) | Leaves, fences, cut-outs: pixels below cutoff are discarded, the rest are opaque. They cast correct shadows. |
Blend | Glass, ghosts, fading objects. Drawn after opaque objects, sorted back to front. |
Premultiplied | Colours already multiplied by alpha. |
AlphaToCoverage | Smoother cut-out edges when MSAA is on. |
Add, Multiply | Additive glows and darkening overlays. |
let ghost = materials.add(StandardMaterial {
base_color: Color::srgba(0.6, 0.8, 1.0, 0.4),
alpha_mode: AlphaMode::Blend,
..default()
});Blended objects are sorted per object, not per triangle, so overlapping blended meshes can draw in the wrong order. Order-independent transparency fixes that on the desktop; see Screen-space effects. Examples: transparency_3d, blend_modes.
Transmission#
Transmission lets light pass through a surface instead of only blending with what's behind it:
| Field | What it does |
|---|---|
specular_transmission | Glass and water: refracts the scene behind. Use with ior (index of refraction, 1.5 by default), thickness, attenuation_distance and attenuation_color. |
diffuse_transmission | Leaves, paper, wax: light scatters through. |
Specular transmission samples the screen behind the object, which costs extra passes; the camera's ScreenSpaceTransmission component (in neo::pbr) sets how many layers it resolves. The texture versions of these fields (specular_transmission_texture and others) need the pbr_transmission_textures cargo feature, which NEO's builds don't turn on. Example: cargo run --example transmission.
Advanced layers#
| Field | What it does | Notes |
|---|---|---|
clearcoat, clearcoat_perceptual_roughness | A thin varnish layer on top, as on car paint. | The clearcoat textures need pbr_multi_layer_material_textures. |
anisotropy_strength, anisotropy_rotation | Stretched highlights, as on brushed metal or hair. | anisotropy_texture needs pbr_anisotropy_texture. |
specular_tint | Tints the specular highlight. | specular_texture and specular_tint_texture need pbr_specular_textures. |
None of those texture features is on in NEO's builds; the scalar fields work everywhere.
Changing materials at runtime#
Change the asset to change every user of the handle, or give an entity its own material to change just that one:
#[derive(Component)]
struct Flash;
fn pulse(
time: Res<Time>,
query: Query<&MeshMaterial3d<StandardMaterial>, With<Flash>>,
mut materials: ResMut<Assets<StandardMaterial>>,
) {
for handle in &query {
if let Some(mut material) = materials.get_mut(handle) {
let glow = (time.elapsed_secs() * 4.0).sin() * 0.5 + 0.5;
material.emissive = LinearRgba::rgb(glow * 4.0, 0.0, 0.0);
}
}
}Example: cargo run --example animated_material.
Decals#
A forward decal projects a texture onto the surfaces under it, such as a bullet hole or a puddle. Spawn ForwardDecal with a ForwardDecalMaterial<StandardMaterial> (both in neo::pbr::decal) and add DepthPrepass to the camera. Forward decals need a readable depth texture, so they don't work in web builds. Clustered decals (ClusteredDecal) need the pbr_clustered_decals feature and bindless textures, which NEO's builds and WebGL 2 don't have. Example: cargo run --example decal --features free_camera.
Lighter shading for low-end GPUs#
ConsoleLiteShading (in neo::pbr) on a camera shades every StandardMaterial with a lean lighting path: the first directional light, up to two point lights per cluster, one environment map lookup and ambient light, with no shadows, clearcoat, anisotropy, transmission or light probes. Material inputs, light units, fog and tonemapping stay the same, so the look stays close at a fraction of the cost. NEO's console render profile adds it automatically.