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.
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:
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.
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()
},
));| Field | What it does |
|---|---|
diffuse_map, specular_map | The pre-filtered cube maps, usually KTX2. |
intensity | Brightness in cd/m². |
rotation | Turns the environment. Rotate it with the skybox to keep them matched. |
affects_lightmapped_mesh_diffuse | Turn 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:
| Component | What it does |
|---|---|
EnvironmentMapLight | A reflection probe: reflections and ambient light from a cube map captured at that spot, such as inside a building. |
IrradianceVolume | A 3D grid of baked diffuse light (voxels, intensity), for indirect light that changes across a room. |
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:
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:
commands.spawn((
Camera3d::default(),
DistanceFog {
color: Color::srgb(0.25, 0.25, 0.25),
falloff: FogFalloff::Linear { start: 5.0, end: 20.0 },
..default()
},
));FogFalloff | Shape |
|---|---|
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:
VolumetricFogon the camera (ambient_intensity,step_count,jitter).FogVolumeentities: boxes of fog, scaled with their transform, withdensity_factor,fog_color,absorption,scatteringand an optionaldensity_texture.VolumetricLighton each light that should shine through the fog.
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:
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.