World environment

Configure sky, fog, ambient light, and post-processing effects

Overview

The Environment resource controls the rendering environment of your scene, including background, ambient lighting, fog, sky, and post-processing effects. It’s used with WorldEnvironment nodes to define the visual atmosphere.

WorldEnvironment node

Add environmental settings to your scene:

var world_env = WorldEnvironment.new()
var environment = Environment.new()
world_env.environment = environment
add_child(world_env)

Only one WorldEnvironment should be active per scene. If multiple exist, the one highest in the scene tree takes priority.

Background modes

Configure how the background is rendered:

Sky background

var environment = Environment.new()
environment.background_mode = Environment.BG_SKY

# Create sky
var sky = Sky.new()
var sky_material = ProceduralSkyMaterial.new()
sky_material.sky_top_color = Color(0.1, 0.3, 0.8)
sky_material.sky_horizon_color = Color(0.6, 0.7, 0.9)
sky_material.ground_bottom_color = Color(0.1, 0.1, 0.1)
sky_material.ground_horizon_color = Color(0.4, 0.4, 0.4)

sky.sky_material = sky_material
environment.sky = sky

Color background

environment.background_mode = Environment.BG_COLOR
environment.background_color = Color(0.2, 0.2, 0.3)

Canvas background

environment.background_mode = Environment.BG_CANVAS
environment.background_canvas_max_layer = 100

Keep background

environment.background_mode = Environment.BG_KEEP
# Preserves whatever was rendered previously

Camera feed background

environment.background_mode = Environment.BG_CAMERA_FEED
environment.background_camera_feed_id = 1
# Useful for AR applications

Sky types

ProceduralSkyMaterial

Generate sky procedurally:

var sky_material = ProceduralSkyMaterial.new()
sky_material.sky_top_color = Color(0.1, 0.3, 0.8)
sky_material.sky_horizon_color = Color(0.6, 0.7, 0.9)
sky_material.sky_curve = 0.15
sky_material.ground_bottom_color = Color(0.1, 0.1, 0.1)
sky_material.ground_horizon_color = Color(0.4, 0.4, 0.4)
sky_material.ground_curve = 0.02
sky_material.sun_angle_max = 30.0
sky_material.sun_curve = 0.15

PanoramaSkyMaterial

Use an HDR panorama image:

var sky_material = PanoramaSkyMaterial.new()
sky_material.panorama = preload("res://hdri/sky.hdr")
sky_material.filter = true

PhysicalSkyMaterial

Physically-based atmospheric scattering:

var sky_material = PhysicalSkyMaterial.new()
sky_material.rayleigh_coefficient = 2.0
sky_material.rayleigh_color = Color(0.26, 0.41, 0.58)
sky_material.mie_coefficient = 0.005
sky_material.mie_eccentricity = 0.8
sky_material.mie_color = Color(0.63, 0.77, 0.92)
sky_material.turbidity = 10.0
sky_material.sun_disk_scale = 1.0
sky_material.ground_color = Color(0.1, 0.07, 0.034)

PhysicalSkyMaterial provides the most realistic sky but is more computationally expensive than ProceduralSkyMaterial.

Ambient light

Control ambient lighting in the scene:

# Ambient light from sky
environment.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
environment.ambient_light_sky_contribution = 1.0

# Custom ambient light color
environment.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR
environment.ambient_light_color = Color(0.2, 0.2, 0.25)
environment.ambient_light_energy = 1.0

Ambient light sources

Background

Ambient light matches the background color or sky.

Disabled

No ambient light. Only direct lighting affects objects.

Color

Use a solid color for ambient light.

Sky

Sample the sky for ambient light (most realistic).

Fog

Add atmospheric fog to your scene:

Volumetric fog

environment.volumetric_fog_enabled = true
environment.volumetric_fog_density = 0.01
environment.volumetric_fog_albedo = Color(0.9, 0.9, 0.9)
environment.volumetric_fog_emission = Color.BLACK
environment.volumetric_fog_emission_energy = 0.0
environment.volumetric_fog_gi_inject = 1.0
environment.volumetric_fog_anisotropy = 0.2
environment.volumetric_fog_length = 64.0
environment.volumetric_fog_detail_spread = 2.0

Depth fog

environment.fog_mode = Environment.FOG_MODE_DEPTH
environment.fog_light_color = Color(0.5, 0.6, 0.7)
environment.fog_light_energy = 1.0
environment.fog_sun_scatter = 0.0
environment.fog_density = 0.01
environment.fog_aerial_perspective = 0.0
environment.fog_sky_affect = 1.0

# Depth range
environment.fog_depth_begin = 10.0
environment.fog_depth_end = 100.0
environment.fog_depth_curve = 1.0

Exponential fog

environment.fog_mode = Environment.FOG_MODE_EXPONENTIAL
environment.fog_density = 0.001
environment.fog_light_color = Color(0.7, 0.7, 0.8)

Volumetric fog is expensive. Use it sparingly and adjust the detail settings for better performance.

Tonemapping

Control HDR to LDR conversion:

# Tonemap mode
environment.tonemap_mode = Environment.TONE_MAPPER_FILMIC
# Options: LINEAR, REINHARD, FILMIC, ACES

# Exposure
environment.tonemap_exposure = 1.0
environment.tonemap_white = 1.0

Auto exposure

environment.auto_exposure_enabled = true
environment.auto_exposure_min_sensitivity = 0.0
environment.auto_exposure_max_sensitivity = 800.0
environment.auto_exposure_speed = 0.5
environment.auto_exposure_scale = 1.0

Glow (bloom)

Add bloom/glow effects:

environment.glow_enabled = true
environment.glow_intensity = 0.8
environment.glow_strength = 1.0
environment.glow_bloom = 0.0
environment.glow_blend_mode = Environment.GLOW_BLEND_MODE_ADDITIVE

# Configure glow levels (7 levels available)
environment.set_glow_level(0, 0.0)  # Finest detail
environment.set_glow_level(1, 0.0)
environment.set_glow_level(2, 1.0)
environment.set_glow_level(3, 0.0)
environment.set_glow_level(4, 1.0)
environment.set_glow_level(5, 0.0)
environment.set_glow_level(6, 0.0)  # Coarsest detail

# HDR settings
environment.glow_hdr_threshold = 1.0
environment.glow_hdr_scale = 2.0

Enable only the glow levels you need. Each enabled level adds processing cost.

Screen-space reflections (SSR)

environment.ssr_enabled = true
environment.ssr_max_steps = 64
environment.ssr_fade_in = 0.15
environment.ssr_fade_out = 2.0
environment.ssr_depth_tolerance = 0.2

SSR is only available with the Forward+ renderer.

Screen-space ambient occlusion (SSAO)

environment.ssao_enabled = true
environment.ssao_radius = 1.0
environment.ssao_intensity = 2.0
environment.ssao_power = 1.5
environment.ssao_detail = 0.5
environment.ssao_horizon = 0.06
environment.ssao_sharpness = 0.98
environment.ssao_light_affect = 0.0
environment.ssao_ao_channel_affect = 0.0

Screen-space indirect lighting (SSIL)

environment.ssil_enabled = true
environment.ssil_radius = 5.0
environment.ssil_intensity = 1.0
environment.ssil_sharpness = 0.98
environment.ssil_normal_rejection = 1.0

Adjustments

Final color adjustments:

environment.adjustment_enabled = true
environment.adjustment_brightness = 1.0
environment.adjustment_contrast = 1.0
environment.adjustment_saturation = 1.0

# Color correction LUT
var lut_texture = preload("res://luts/color_grade.png")
environment.adjustment_color_correction = lut_texture

Depth of field (DOF)

DOF Far

environment.dof_blur_far_enabled = true
environment.dof_blur_far_distance = 10.0
environment.dof_blur_far_transition = 5.0
environment.dof_blur_far_amount = 0.1

DOF Near

environment.dof_blur_near_enabled = true
environment.dof_blur_near_distance = 2.0
environment.dof_blur_near_transition = 1.0
environment.dof_blur_near_amount = 0.1

DOF quality

# Global DOF settings (project settings)
ProjectSettings.set_setting("rendering/environment/depth_of_field/depth_of_field_bokeh_shape", 1)
ProjectSettings.set_setting("rendering/environment/depth_of_field/depth_of_field_bokeh_quality", 2)
ProjectSettings.set_setting("rendering/environment/depth_of_field/depth_of_field_use_jitter", false)

Global illumination

SDFGI (Signed Distance Field GI)

environment.sdfgi_enabled = true
environment.sdfgi_cascades = 6
environment.sdfgi_min_cell_size = 0.2
environment.sdfgi_use_occlusion = true
environment.sdfgi_bounce_feedback = 0.5
environment.sdfgi_read_sky_light = true
environment.sdfgi_energy = 1.0
environment.sdfgi_normal_bias = 1.1
environment.sdfgi_probe_bias = 1.1

SDFGI is only available with the Forward+ renderer and provides real-time global illumination.

VoxelGI

# Create VoxelGI node
var voxel_gi = VoxelGI.new()
voxel_gi.size = Vector3(20, 10, 20)
voxel_gi.subdiv = VoxelGI.SUBDIV_256
add_child(voxel_gi)

# Bake GI data
voxel_gi.bake()

Camera attributes

Override per-camera settings:

var camera_attributes = CameraAttributesPractical.new()
camera_attributes.dof_blur_far_enabled = true
camera_attributes.dof_blur_far_distance = 20.0
camera_attributes.auto_exposure_enabled = true

var camera = Camera3D.new()
camera.attributes = camera_attributes

Common environment presets

Outdoor daytime

var env = Environment.new()
env.background_mode = Environment.BG_SKY

var sky = Sky.new()
var sky_mat = ProceduralSkyMaterial.new()
sky_mat.sky_top_color = Color(0.1, 0.3, 0.8)
sky_mat.sky_horizon_color = Color(0.6, 0.7, 0.9)
sky.sky_material = sky_mat
env.sky = sky

env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
env.tonemap_mode = Environment.TONE_MAPPER_FILMIC
env.tonemap_exposure = 1.0

Indoor scene

var env = Environment.new()
env.background_mode = Environment.BG_COLOR
env.background_color = Color(0.1, 0.1, 0.15)
env.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR
env.ambient_light_color = Color(0.2, 0.2, 0.25)
env.ambient_light_energy = 0.5

Foggy atmosphere

var env = Environment.new()
env.fog_mode = Environment.FOG_MODE_EXPONENTIAL
env.fog_density = 0.01
env.fog_light_color = Color(0.7, 0.7, 0.8)
env.fog_light_energy = 1.0

Stylized/cartoon

var env = Environment.new()
env.background_mode = Environment.BG_COLOR
env.background_color = Color(0.4, 0.6, 0.9)
env.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR
env.ambient_light_color = Color(0.5, 0.5, 0.5)
env.tonemap_mode = Environment.TONE_MAPPER_LINEAR
env.adjustment_enabled = true
env.adjustment_saturation = 1.3
env.adjustment_contrast = 1.1

Performance optimization

Disable unused effects

Turn off SSAO, SSR, and volumetric fog when not needed.

Adjust quality settings

Lower quality settings in project settings for better performance.

Use simpler sky types

ProceduralSkyMaterial is faster than PhysicalSkyMaterial.

Limit glow levels

Enable only necessary glow levels to reduce blur passes.

Dynamic environment changes

func transition_to_night(duration: float):
    var tween = create_tween()
    
    # Animate sky colors
    var sky_mat = environment.sky.sky_material as ProceduralSkyMaterial
    tween.parallel().tween_property(sky_mat, "sky_top_color", 
        Color(0.01, 0.01, 0.05), duration)
    tween.parallel().tween_property(sky_mat, "ground_bottom_color", 
        Color(0.05, 0.05, 0.05), duration)
    
    # Animate ambient light
    tween.parallel().tween_property(environment, "ambient_light_energy", 
        0.2, duration)

Next steps

Shaders

Create custom shader effects

Particles

Add particle systems