> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/godotengine/godot/llms.txt
> Use this file to discover all available pages before exploring further.

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

```gdscript theme={null}
var world_env = WorldEnvironment.new()
var environment = Environment.new()
world_env.environment = environment
add_child(world_env)
```

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

## Background modes

Configure how the background is rendered:

### Sky background

```gdscript theme={null}
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

```gdscript theme={null}
environment.background_mode = Environment.BG_COLOR
environment.background_color = Color(0.2, 0.2, 0.3)
```

### Canvas background

```gdscript theme={null}
environment.background_mode = Environment.BG_CANVAS
environment.background_canvas_max_layer = 100
```

### Keep background

```gdscript theme={null}
environment.background_mode = Environment.BG_KEEP
# Preserves whatever was rendered previously
```

### Camera feed background

```gdscript theme={null}
environment.background_mode = Environment.BG_CAMERA_FEED
environment.background_camera_feed_id = 1
# Useful for AR applications
```

## Sky types

### ProceduralSkyMaterial

Generate sky procedurally:

```gdscript theme={null}
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:

```gdscript theme={null}
var sky_material = PanoramaSkyMaterial.new()
sky_material.panorama = preload("res://hdri/sky.hdr")
sky_material.filter = true
```

### PhysicalSkyMaterial

Physically-based atmospheric scattering:

```gdscript theme={null}
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)
```

<Tip>
  PhysicalSkyMaterial provides the most realistic sky but is more computationally expensive than ProceduralSkyMaterial.
</Tip>

## Ambient light

Control ambient lighting in the scene:

```gdscript theme={null}
# 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

<AccordionGroup>
  <Accordion title="Background">
    Ambient light matches the background color or sky.
  </Accordion>

  <Accordion title="Disabled">
    No ambient light. Only direct lighting affects objects.
  </Accordion>

  <Accordion title="Color">
    Use a solid color for ambient light.
  </Accordion>

  <Accordion title="Sky">
    Sample the sky for ambient light (most realistic).
  </Accordion>
</AccordionGroup>

## Fog

Add atmospheric fog to your scene:

### Volumetric fog

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
environment.fog_mode = Environment.FOG_MODE_EXPONENTIAL
environment.fog_density = 0.001
environment.fog_light_color = Color(0.7, 0.7, 0.8)
```

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

## Tonemapping

Control HDR to LDR conversion:

```gdscript theme={null}
# 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

```gdscript theme={null}
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:

```gdscript theme={null}
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
```

<Tip>
  Enable only the glow levels you need. Each enabled level adds processing cost.
</Tip>

## Screen-space reflections (SSR)

```gdscript theme={null}
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
```

<Info>
  SSR is only available with the Forward+ renderer.
</Info>

## Screen-space ambient occlusion (SSAO)

```gdscript theme={null}
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)

```gdscript theme={null}
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:

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
# 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)

```gdscript theme={null}
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
```

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

### VoxelGI

```gdscript theme={null}
# 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:

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
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

```gdscript theme={null}
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

<CardGroup cols={2}>
  <Card title="Disable unused effects" icon="toggle-off">
    Turn off SSAO, SSR, and volumetric fog when not needed.
  </Card>

  <Card title="Adjust quality settings" icon="sliders">
    Lower quality settings in project settings for better performance.
  </Card>

  <Card title="Use simpler sky types" icon="cloud">
    ProceduralSkyMaterial is faster than PhysicalSkyMaterial.
  </Card>

  <Card title="Limit glow levels" icon="sun">
    Enable only necessary glow levels to reduce blur passes.
  </Card>
</CardGroup>

## Dynamic environment changes

```gdscript theme={null}
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

<CardGroup cols={2}>
  <Card title="Shaders" icon="code" href="/rendering/shaders">
    Create custom shader effects
  </Card>

  <Card title="Particles" icon="sparkles" href="/rendering/particles">
    Add particle systems
  </Card>
</CardGroup>