NEOLearn

Materials

Make surfaces look right with StandardMaterial, NEO's physically based material: colour, roughness, metal, textures, emission, transparency, transmission and decals.

Updated October 20, 2026

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.

Rust
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#

FieldDefaultWhat it does
base_colorwhiteThe surface colour (albedo).
base_color_texturenoneAn image multiplied with base_color.
perceptual_roughness0.50 is a mirror, 1 is fully matte.
metallic0.00 for non-metals (plastic, wood, skin), 1 for metals. Values in between are rarely physical.
metallic_roughness_texturenoneRoughness from the green channel, metal from the blue channel, multiplied with the two fields above.
reflectance0.5Specular strength for non-metals. 0.5 is about 4%, typical for most materials.
emissiveblackLight the surface gives off, as LinearRgba. Values above 1 glow with bloom.
emissive_texturenoneMultiplied with emissive.
normal_map_texturenoneFine 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_texturenoneBaked ambient occlusion in the red channel.
unlitfalseIgnores lights and shows base_color as is.
double_sided, cull_modefalse, back facesDraw both sides of thin surfaces: set double_sided: true and cull_mode: None.
fog_enabledtrueWhether fog affects this surface.
uv_transformidentityAn 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.

Rust
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:

AlphaModeUse it for
OpaqueThe default. Alpha is ignored.
Mask(cutoff)Leaves, fences, cut-outs: pixels below cutoff are discarded, the rest are opaque. They cast correct shadows.
BlendGlass, ghosts, fading objects. Drawn after opaque objects, sorted back to front.
PremultipliedColours already multiplied by alpha.
AlphaToCoverageSmoother cut-out edges when MSAA is on.
Add, MultiplyAdditive glows and darkening overlays.
Rust
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:

FieldWhat it does
specular_transmissionGlass and water: refracts the scene behind. Use with ior (index of refraction, 1.5 by default), thickness, attenuation_distance and attenuation_color.
diffuse_transmissionLeaves, 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#

FieldWhat it doesNotes
clearcoat, clearcoat_perceptual_roughnessA thin varnish layer on top, as on car paint.The clearcoat textures need pbr_multi_layer_material_textures.
anisotropy_strength, anisotropy_rotationStretched highlights, as on brushed metal or hair.anisotropy_texture needs pbr_anisotropy_texture.
specular_tintTints 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:

Rust
#[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.

Next steps#