NEOLearn

Environment

Surround a 3D scene with a skybox, light it with environment maps, light probes and lightmaps, and add distance fog, volumetric fog and an atmosphere.

Updated October 20, 2026

On this page

The environment is everything around your objects: the sky you see behind them, the light and reflections it gives them, and the air between them and the camera. Most of these are components on the camera; light probes are entities placed in the world.

Skybox#

Skybox on a camera draws a cube map behind everything:

Rust
use neo::light::Skybox;

commands.spawn((
    Camera3d::default(),
    Skybox {
        image: Some(asset_server.load("environment_maps/sky_cubemap.ktx2")),
        brightness: 1000.0,
        ..default()
    },
));

The image must be a cube map. A KTX2 cube map works as is; a PNG with the six faces stacked vertically needs its texture view changed to a cube once it has loaded (reinterpret_stacked_2d_as_array(6) and a TextureViewDimension::Cube view). rotation turns the sky. Example: cargo run --example skybox --features free_camera.

A skybox only paints the background. To have the sky light and reflect in your objects, add an environment map too.

Environment maps#

EnvironmentMapLight on a camera lights every object from all directions with a pair of pre-filtered cube maps: a diffuse map for soft ambient light and a specular map for reflections. It's what makes metals and glossy surfaces look right.

Rust
commands.spawn((
    Camera3d::default(),
    EnvironmentMapLight {
        diffuse_map: asset_server.load("environment_maps/pisa_diffuse_rgb9e5_zstd.ktx2"),
        specular_map: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
        intensity: 900.0,
        ..default()
    },
));
FieldWhat it does
diffuse_map, specular_mapThe pre-filtered cube maps, usually KTX2.
intensityBrightness in cd/m².
rotationTurns the environment. Rotate it with the skybox to keep them matched.
affects_lightmapped_mesh_diffuseTurn off for meshes whose lightmap already holds this light.

Environment maps on the camera work on every platform, including the web. Example: cargo run --example pbr.

GeneratedEnvironmentMapLight filters a single cube map on the GPU at run time instead of using pre-filtered maps. It needs compute shaders and storage textures, so it doesn't work in web builds.

Light probes#

A light probe applies lighting to the part of the world inside it. Spawn a LightProbe entity, scale its transform to the room or area it covers (it's a 1×1×1 cube before scaling), and add one of:

ComponentWhat it does
EnvironmentMapLightA reflection probe: reflections and ambient light from a cube map captured at that spot, such as inside a building.
IrradianceVolumeA 3D grid of baked diffuse light (voxels, intensity), for indirect light that changes across a room.
Rust
use neo::light::IrradianceVolume;

commands.spawn((
    LightProbe::default(),
    Transform::from_scale(Vec3::new(10.0, 4.0, 10.0)),
    IrradianceVolume {
        voxels: asset_server.load("irradiance_volumes/Example.vxgi.ktx2"),
        intensity: 150.0,
        ..default()
    },
));

LightProbe::falloff fades the probe's effect towards its edges.

On the web, reflection probes aren't supported (they need binding arrays) and only the irradiance volume nearest the camera is used. Examples: reflection_probes, irradiance_volumes.

Lightmaps#

A lightmap is lighting baked into a texture by an external tool, for static scenes that need high-quality indirect light at almost no cost. Put a Lightmap (in neo::pbr) on the mesh entity:

Rust
use neo::pbr::Lightmap;

commands.entity(mesh_entity).insert(Lightmap {
    image: asset_server.load("lightmaps/room.zstd.ktx2"),
    ..default()
});

The mesh needs a second set of texture coordinates (ATTRIBUTE_UV_1). uv_rect selects this mesh's part of a shared lightmap atlas, and bicubic_sampling smooths low-resolution lightmaps. Lights that are already baked in should set affects_lightmapped_mesh_diffuse: false. Examples: lightmaps, mixed_lighting (needs the jpeg and neo_feathers features).

Fog#

DistanceFog on a camera fades distant objects into a colour:

Rust
commands.spawn((
    Camera3d::default(),
    DistanceFog {
        color: Color::srgb(0.25, 0.25, 0.25),
        falloff: FogFalloff::Linear { start: 5.0, end: 20.0 },
        ..default()
    },
));
FogFalloffShape
Linear { start, end }Even from start to fully fogged at end. Easiest to control.
Exponential { density }Thickens quickly near the camera.
ExponentialSquared { density }Clear near the camera, then thickens.
Atmospheric { extinction, inscattering }Per-channel colours, for haze over long distances.

FogFalloff::from_visibility(distance) and its variants (from_visibility_squared, from_visibility_color, from_visibility_contrast and more) compute the parameters from how far the player should see. directional_light_color and directional_light_exponent make the fog glow towards the sun. A material with fog_enabled: false ignores fog. Fog works on every platform. Examples: fog, atmospheric_fog.

Volumetric fog#

Volumetric fog makes light shafts visible. It has three parts, all in neo::light:

  1. VolumetricFog on the camera (ambient_intensity, step_count, jitter).
  2. FogVolume entities: boxes of fog, scaled with their transform, with density_factor, fog_color, absorption, scattering and an optional density_texture.
  3. VolumetricLight on each light that should shine through the fog.
Rust
use neo::light::{FogVolume, VolumetricFog, VolumetricLight};

commands.spawn((Camera3d::default(), VolumetricFog { ambient_intensity: 0.0, ..default() }));
commands.spawn((FogVolume::default(), Transform::from_scale(Vec3::splat(35.0))));
commands.spawn((
    SpotLight { intensity: 50_000.0, shadow_maps_enabled: true, ..default() },
    VolumetricLight,
    Transform::from_xyz(-1.8, 3.9, -2.7).looking_at(Vec3::ZERO, Vec3::Y),
));

Volumetric fog is expensive; keep step_count low and the volumes tight. Examples: volumetric_fog, fog_volumes, scrolling_fog.

Atmosphere#

The atmosphere renders a physically based sky with sunsets and aerial perspective, driven by your directional light. Spawn the planet's Atmosphere and add AtmosphereSettings to each camera that should show it:

Rust
use neo::light::{atmosphere::ScatteringMedium, Atmosphere, AtmosphereEnvironmentMapLight};
use neo::pbr::AtmosphereSettings;

fn setup(mut commands: Commands, mut media: ResMut<Assets<ScatteringMedium>>) {
    let earth = media.add(ScatteringMedium::earth(256, 256));
    commands.spawn(Atmosphere::earth(earth));
    commands.spawn((
        Camera3d::default(),
        AtmosphereSettings::default(),
        AtmosphereEnvironmentMapLight::default(), // the sky lights and reflects in the scene
        Exposure { ev100: 13.0 },
    ));
    commands.spawn((
        DirectionalLight { illuminance: light_consts::lux::RAW_SUNLIGHT, shadow_maps_enabled: true, ..default() },
        Transform::from_xyz(1.0, 0.4, 0.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

Atmosphere::mars and custom ScatteringMediums give other skies; SunDisk on the light draws the sun itself. Exposure is in neo::camera.

Example: cargo run --example atmosphere.

Next steps#