Environment¶

Inherits: Resource < RefCounted < Object

Resource for environment nodes (like WorldEnvironment) that define multiple rendering options.

Description¶

Resource for environment nodes (like WorldEnvironment) that define multiple environment operations (such as background Sky or Color, ambient light, fog, depth-of-field...). These parameters affect the final render of the scene. The order of these operations is:

Depth of Field Blur
Glow
Tonemap (Auto Exposure)
Adjustments

Tutorials¶

Properties¶

float	adjustment_brightness	`1.0`
Texture	adjustment_color_correction
float	adjustment_contrast	`1.0`
bool	adjustment_enabled	`false`
float	adjustment_saturation	`1.0`
Color	ambient_light_color	`Color(0, 0, 0, 1)`
float	ambient_light_energy	`1.0`
float	ambient_light_sky_contribution	`1.0`
AmbientSource	ambient_light_source	`0`
int	background_camera_feed_id	`1`
int	background_canvas_max_layer	`0`
Color	background_color	`Color(0, 0, 0, 1)`
float	background_energy_multiplier	`1.0`
float	background_intensity	`30000.0`
BGMode	background_mode	`0`
float	fog_aerial_perspective	`0.0`
float	fog_density	`0.01`
bool	fog_enabled	`false`
float	fog_height	`0.0`
float	fog_height_density	`0.0`
Color	fog_light_color	`Color(0.518, 0.553, 0.608, 1)`
float	fog_light_energy	`1.0`
float	fog_sky_affect	`1.0`
float	fog_sun_scatter	`0.0`
GlowBlendMode	glow_blend_mode	`2`
float	glow_bloom	`0.0`
bool	glow_enabled	`false`
float	glow_hdr_luminance_cap	`12.0`
float	glow_hdr_scale	`2.0`
float	glow_hdr_threshold	`1.0`
float	glow_intensity	`0.8`
float	glow_levels/1	`0.0`
float	glow_levels/2	`0.0`
float	glow_levels/3	`1.0`
float	glow_levels/4	`0.0`
float	glow_levels/5	`1.0`
float	glow_levels/6	`0.0`
float	glow_levels/7	`0.0`
Texture	glow_map
float	glow_map_strength	`0.8`
float	glow_mix	`0.05`
bool	glow_normalized	`false`
float	glow_strength	`1.0`
ReflectionSource	reflected_light_source	`0`
float	sdfgi_bounce_feedback	`0.5`
float	sdfgi_cascade0_distance	`12.8`
int	sdfgi_cascades	`4`
bool	sdfgi_enabled	`false`
float	sdfgi_energy	`1.0`
float	sdfgi_max_distance	`204.8`
float	sdfgi_min_cell_size	`0.2`
float	sdfgi_normal_bias	`1.1`
float	sdfgi_probe_bias	`1.1`
bool	sdfgi_read_sky_light	`true`
bool	sdfgi_use_occlusion	`false`
SDFGIYScale	sdfgi_y_scale	`1`
Sky	sky
float	sky_custom_fov	`0.0`
Vector3	sky_rotation	`Vector3(0, 0, 0)`
float	ssao_ao_channel_affect	`0.0`
float	ssao_detail	`0.5`
bool	ssao_enabled	`false`
float	ssao_horizon	`0.06`
float	ssao_intensity	`2.0`
float	ssao_light_affect	`0.0`
float	ssao_power	`1.5`
float	ssao_radius	`1.0`
float	ssao_sharpness	`0.98`
bool	ssil_enabled	`false`
float	ssil_intensity	`1.0`
float	ssil_normal_rejection	`1.0`
float	ssil_radius	`5.0`
float	ssil_sharpness	`0.98`
float	ssr_depth_tolerance	`0.2`
bool	ssr_enabled	`false`
float	ssr_fade_in	`0.15`
float	ssr_fade_out	`2.0`
int	ssr_max_steps	`64`
float	tonemap_exposure	`1.0`
ToneMapper	tonemap_mode	`0`
float	tonemap_white	`1.0`
Color	volumetric_fog_albedo	`Color(1, 1, 1, 1)`
float	volumetric_fog_ambient_inject	`0.0`
float	volumetric_fog_anisotropy	`0.2`
float	volumetric_fog_density	`0.05`
float	volumetric_fog_detail_spread	`2.0`
Color	volumetric_fog_emission	`Color(0, 0, 0, 1)`
float	volumetric_fog_emission_energy	`1.0`
bool	volumetric_fog_enabled	`false`
float	volumetric_fog_gi_inject	`1.0`
float	volumetric_fog_length	`64.0`
float	volumetric_fog_sky_affect	`1.0`
float	volumetric_fog_temporal_reprojection_amount	`0.9`
bool	volumetric_fog_temporal_reprojection_enabled	`true`

Methods¶

float	get_glow_level ( int idx ) const
void	set_glow_level ( int idx, float intensity )

Enumerations¶

enum BGMode:

BGMode BG_CLEAR_COLOR = 0

Clears the background using the clear color defined in ProjectSettings.rendering/environment/defaults/default_clear_color.

BGMode BG_COLOR = 1

Clears the background using a custom clear color.

BGMode BG_SKY = 2

Displays a user-defined sky in the background.

BGMode BG_CANVAS = 3

Displays a CanvasLayer in the background.

BGMode BG_KEEP = 4

Keeps on screen every pixel drawn in the background. This is the fastest background mode, but it can only be safely used in fully-interior scenes (no visible sky or sky reflections). If enabled in a scene where the background is visible, "ghost trail" artifacts will be visible when moving the camera.

BGMode BG_CAMERA_FEED = 5

Displays a camera feed in the background.

BGMode BG_MAX = 6

Represents the size of the BGMode enum.

enum AmbientSource:

AmbientSource AMBIENT_SOURCE_BG = 0

Gather ambient light from whichever source is specified as the background.

AmbientSource AMBIENT_SOURCE_DISABLED = 1

Disable ambient light. This provides a slight performance boost over AMBIENT_SOURCE_SKY.

AmbientSource AMBIENT_SOURCE_COLOR = 2

Specify a specific Color for ambient light. This provides a slight performance boost over AMBIENT_SOURCE_SKY.

AmbientSource AMBIENT_SOURCE_SKY = 3

Gather ambient light from the Sky regardless of what the background is.

enum ReflectionSource:

ReflectionSource REFLECTION_SOURCE_BG = 0

Use the background for reflections.

ReflectionSource REFLECTION_SOURCE_DISABLED = 1

Disable reflections. This provides a slight performance boost over other options.

ReflectionSource REFLECTION_SOURCE_SKY = 2

Use the Sky for reflections regardless of what the background is.

enum ToneMapper:

ToneMapper TONE_MAPPER_LINEAR = 0

Linear tonemapper operator. Reads the linear data and passes it on unmodified. This can cause bright lighting to look blown out, with noticeable clipping in the output colors.

ToneMapper TONE_MAPPER_REINHARDT = 1

Reinhardt tonemapper operator. Performs a variation on rendered pixels' colors by this formula: color = color / (1 + color). This avoids clipping bright highlights, but the resulting image can look a bit dull.

ToneMapper TONE_MAPPER_FILMIC = 2

Filmic tonemapper operator. This avoids clipping bright highlights, with a resulting image that usually looks more vivid than TONE_MAPPER_REINHARDT.

ToneMapper TONE_MAPPER_ACES = 3

Use the Academy Color Encoding System tonemapper. ACES is slightly more expensive than other options, but it handles bright lighting in a more realistic fashion by desaturating it as it becomes brighter. ACES typically has a more contrasted output compared to TONE_MAPPER_REINHARDT and TONE_MAPPER_FILMIC.

Note: This tonemapping operator is called "ACES Fitted" in Godot 3.x.

enum GlowBlendMode:

GlowBlendMode GLOW_BLEND_MODE_ADDITIVE = 0

Additive glow blending mode. Mostly used for particles, glows (bloom), lens flare, bright sources.

GlowBlendMode GLOW_BLEND_MODE_SCREEN = 1

Screen glow blending mode. Increases brightness, used frequently with bloom.

GlowBlendMode GLOW_BLEND_MODE_SOFTLIGHT = 2

Soft light glow blending mode. Modifies contrast, exposes shadows and highlights (vivid bloom).

GlowBlendMode GLOW_BLEND_MODE_REPLACE = 3

Replace glow blending mode. Replaces all pixels' color by the glow value. This can be used to simulate a full-screen blur effect by tweaking the glow parameters to match the original image's brightness.

GlowBlendMode GLOW_BLEND_MODE_MIX = 4

Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect.

enum SDFGIYScale:

SDFGIYScale SDFGI_Y_SCALE_50_PERCENT = 0

Use 50% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be twice as short as they are wide. This allows providing increased GI detail and reduced light leaking with thin floors and ceilings. This is usually the best choice for scenes that don't feature much verticality.

SDFGIYScale SDFGI_Y_SCALE_75_PERCENT = 1

Use 75% scale for SDFGI on the Y (vertical) axis. This is a balance between the 50% and 100% SDFGI Y scales.

SDFGIYScale SDFGI_Y_SCALE_100_PERCENT = 2

Use 100% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be as tall as they are wide. This is usually the best choice for highly vertical scenes. The downside is that light leaking may become more noticeable with thin floors and ceilings.

Property Descriptions¶

float adjustment_brightness = 1.0

void set_adjustment_brightness ( float value )
float get_adjustment_brightness ( )

The global brightness value of the rendered scene. Effective only if adjustment_enabled is true.

Texture adjustment_color_correction

void set_adjustment_color_correction ( Texture value )
Texture get_adjustment_color_correction ( )

The Texture2D or Texture3D lookup table (LUT) to use for the built-in post-process color grading. Can use a GradientTexture1D for a 1-dimensional LUT, or a Texture3D for a more complex LUT. Effective only if adjustment_enabled is true.

float adjustment_contrast = 1.0

void set_adjustment_contrast ( float value )
float get_adjustment_contrast ( )

The global contrast value of the rendered scene (default value is 1). Effective only if adjustment_enabled is true.

bool adjustment_enabled = false

void set_adjustment_enabled ( bool value )
bool is_adjustment_enabled ( )

If true, enables the adjustment_* properties provided by this resource. If false, modifications to the adjustment_* properties will have no effect on the rendered scene.

float adjustment_saturation = 1.0

void set_adjustment_saturation ( float value )
float get_adjustment_saturation ( )

The global color saturation value of the rendered scene (default value is 1). Effective only if adjustment_enabled is true.

Color ambient_light_color = Color(0, 0, 0, 1)

void set_ambient_light_color ( Color value )
Color get_ambient_light_color ( )

The ambient light's Color. Only effective if ambient_light_sky_contribution is lower than 1.0 (exclusive).

float ambient_light_energy = 1.0

void set_ambient_light_energy ( float value )
float get_ambient_light_energy ( )

The ambient light's energy. The higher the value, the stronger the light. Only effective if ambient_light_sky_contribution is lower than 1.0 (exclusive).

float ambient_light_sky_contribution = 1.0

void set_ambient_light_sky_contribution ( float value )
float get_ambient_light_sky_contribution ( )

Defines the amount of light that the sky brings on the scene. A value of 0.0 means that the sky's light emission has no effect on the scene illumination, thus all ambient illumination is provided by the ambient light. On the contrary, a value of 1.0 means that all the light that affects the scene is provided by the sky, thus the ambient light parameter has no effect on the scene.

Note: ambient_light_sky_contribution is internally clamped between 0.0 and 1.0 (inclusive).

AmbientSource ambient_light_source = 0

void set_ambient_source ( AmbientSource value )
AmbientSource get_ambient_source ( )

The ambient light source to use for rendering materials and global illumination.

int background_camera_feed_id = 1

void set_camera_feed_id ( int value )
int get_camera_feed_id ( )

The ID of the camera feed to show in the background.

int background_canvas_max_layer = 0

void set_canvas_max_layer ( int value )
int get_canvas_max_layer ( )

The maximum layer ID to display. Only effective when using the BG_CANVAS background mode.

Color background_color = Color(0, 0, 0, 1)

void set_bg_color ( Color value )
Color get_bg_color ( )

The Color displayed for clear areas of the scene. Only effective when using the BG_COLOR background mode.

float background_energy_multiplier = 1.0

void set_bg_energy_multiplier ( float value )
float get_bg_energy_multiplier ( )

Multiplier for background energy. Increase to make background brighter, decrease to make background dimmer.

float background_intensity = 30000.0

void set_bg_intensity ( float value )
float get_bg_intensity ( )

Luminance of background measured in nits (candela per square meter). Only used when ProjectSettings.rendering/lights_and_shadows/use_physical_light_units is enabled. The default value is roughly equivalent to the sky at midday.

BGMode background_mode = 0

void set_background ( BGMode value )
BGMode get_background ( )

The background mode. See BGMode for possible values.

float fog_aerial_perspective = 0.0

void set_fog_aerial_perspective ( float value )
float get_fog_aerial_perspective ( )

If set above 0.0 (exclusive), blends between the fog's color and the color of the background Sky. This has a small performance cost when set above 0.0. Must have background_mode set to BG_SKY.

This is useful to simulate aerial perspective in large scenes with low density fog. However, it is not very useful for high-density fog, as the sky will shine through. When set to 1.0, the fog color comes completely from the Sky. If set to 0.0, aerial perspective is disabled.

float fog_density = 0.01

void set_fog_density ( float value )
float get_fog_density ( )

The exponential fog density to use. Higher values result in a more dense fog. Fog rendering is exponential as in real life.

bool fog_enabled = false

void set_fog_enabled ( bool value )
bool is_fog_enabled ( )

If true, fog effects are enabled.

float fog_height = 0.0

void set_fog_height ( float value )
float get_fog_height ( )

The height at which the height fog effect begins.

float fog_height_density = 0.0

void set_fog_height_density ( float value )
float get_fog_height_density ( )

The density used to increase fog as height decreases. To make fog increase as height increases, use a negative value.

Color fog_light_color = Color(0.518, 0.553, 0.608, 1)

void set_fog_light_color ( Color value )
Color get_fog_light_color ( )

The fog's color.

float fog_light_energy = 1.0

void set_fog_light_energy ( float value )
float get_fog_light_energy ( )

The fog's brightness. Higher values result in brighter fog.

float fog_sky_affect = 1.0

void set_fog_sky_affect ( float value )
float get_fog_sky_affect ( )

The factor to use when affecting the sky with non-volumetric fog. 1.0 means that fog can fully obscure the sky. Lower values reduce the impact of fog on sky rendering, with 0.0 not affecting sky rendering at all.

Note: fog_sky_affect has no visual effect if fog_aerial_perspective is 1.0.

float fog_sun_scatter = 0.0

void set_fog_sun_scatter ( float value )
float get_fog_sun_scatter ( )

If set above 0.0, renders the scene's directional light(s) in the fog color depending on the view angle. This can be used to give the impression that the sun is "piercing" through the fog.

GlowBlendMode glow_blend_mode = 2

void set_glow_blend_mode ( GlowBlendMode value )
GlowBlendMode get_glow_blend_mode ( )

The glow blending mode.

float glow_bloom = 0.0

void set_glow_bloom ( float value )
float get_glow_bloom ( )

The bloom's intensity. If set to a value higher than 0, this will make glow visible in areas darker than the glow_hdr_threshold.

bool glow_enabled = false

void set_glow_enabled ( bool value )
bool is_glow_enabled ( )

If true, the glow effect is enabled.

float glow_hdr_luminance_cap = 12.0

void set_glow_hdr_luminance_cap ( float value )
float get_glow_hdr_luminance_cap ( )

The higher threshold of the HDR glow. Areas brighter than this threshold will be clamped for the purposes of the glow effect.

float glow_hdr_scale = 2.0

void set_glow_hdr_bleed_scale ( float value )
float get_glow_hdr_bleed_scale ( )

The bleed scale of the HDR glow.

float glow_hdr_threshold = 1.0

void set_glow_hdr_bleed_threshold ( float value )
float get_glow_hdr_bleed_threshold ( )

The lower threshold of the HDR glow. When using the OpenGL renderer (which doesn't support HDR), this needs to be below 1.0 for glow to be visible. A value of 0.9 works well in this case.

float glow_intensity = 0.8

void set_glow_intensity ( float value )
float get_glow_intensity ( )

The overall brightness multiplier of the glow effect. When using the OpenGL renderer, this should be increased to 1.5 to compensate for the lack of HDR rendering.

float glow_levels/1 = 0.0

void set_glow_level ( int idx, float intensity )
float get_glow_level ( int idx ) const

The intensity of the 1st level of glow. This is the most "local" level (least blurry).

float glow_levels/2 = 0.0

void set_glow_level ( int idx, float intensity )
float get_glow_level ( int idx ) const

The intensity of the 2nd level of glow.

float glow_levels/3 = 1.0

void set_glow_level ( int idx, float intensity )
float get_glow_level ( int idx ) const

The intensity of the 3rd level of glow.

float glow_levels/4 = 0.0

void set_glow_level ( int idx, float intensity )
float get_glow_level ( int idx ) const

The intensity of the 4th