Decal¶

Inherits: VisualInstance3D < Node3D < Node < Object

Node that projects a texture onto a MeshInstance3D.

Description¶

Decals are used to project a texture onto a Mesh in the scene. Use Decals to add detail to a scene without affecting the underlying Mesh. They are often used to add weathering to building, add dirt or mud to the ground, or add variety to props. Decals can be moved at any time, making them suitable for things like blob shadows or laser sight dots.

They are made of an AABB and a group of Texture2Ds specifying Color, normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within their AABB so altering the orientation of the Decal affects the direction in which they are projected. By default, Decals are projected down (i.e. from positive Y to negative Y).

The Texture2Ds associated with the Decal are automatically stored in a texture atlas which is used for drawing the decals so all decals can be drawn at once. Godot uses clustered decals, meaning they are stored in cluster data and drawn when the mesh is drawn, they are not drawn as a post-processing effect after.

Properties¶

float	albedo_mix	`1.0`
int	cull_mask	`1048575`
float	distance_fade_begin	`10.0`
bool	distance_fade_enabled	`false`
float	distance_fade_length	`1.0`
float	emission_energy	`1.0`
Vector3	extents	`Vector3(1, 1, 1)`
float	lower_fade	`0.3`
Color	modulate	`Color(1, 1, 1, 1)`
float	normal_fade	`0.0`
Texture2D	texture_albedo
Texture2D	texture_emission
Texture2D	texture_normal
Texture2D	texture_orm
float	upper_fade	`0.3`

Methods¶

Texture2D	get_texture ( DecalTexture type ) const
void	set_texture ( DecalTexture type, Texture2D texture )

Enumerations¶

enum DecalTexture:

TEXTURE_ALBEDO = 0 --- Texture2D corresponding to texture_albedo.
TEXTURE_NORMAL = 1 --- Texture2D corresponding to texture_normal.
TEXTURE_ORM = 2 --- Texture2D corresponding to texture_orm.
TEXTURE_EMISSION = 3 --- Texture2D corresponding to texture_emission.
TEXTURE_MAX = 4 --- Max size of DecalTexture enum.

Property Descriptions¶

float albedo_mix

Default	`1.0`
Setter	set_albedo_mix(value)
Getter	get_albedo_mix()

Blends the albedo Color of the decal with albedo Color of the underlying mesh.

int cull_mask

Default	`1048575`
Setter	set_cull_mask(value)
Getter	get_cull_mask()

Specifies which VisualInstance3D.layers this decal will project on. By default, Decals affect all layers. This is used so you can specify which types of objects receive the Decal and which do not. This is especially useful so you can ensure that dynamic objects don't accidentally receive a Decal intended for the terrain under them.

float distance_fade_begin

Default	`10.0`
Setter	set_distance_fade_begin(value)
Getter	get_distance_fade_begin()

Distance from the camera at which the Decal begins to fade away.

bool distance_fade_enabled

Default	`false`
Setter	set_enable_distance_fade(value)
Getter	is_distance_fade_enabled()

If true, decals will smoothly fade away when far from the active Camera3D starting at distance_fade_begin. The Decal will fade out over distance_fade_length, after which it will be culled and not sent to the shader at all. Use this to reduce the number of active Decals in a scene and thus improve performance.

float distance_fade_length

Default	`1.0`
Setter	set_distance_fade_length(value)
Getter	get_distance_fade_length()

Distance over which the Decal fades. The Decal becomes slowly more transparent over this distance and is completely invisible at the end.

float emission_energy

Default	`1.0`
Setter	set_emission_energy(value)
Getter	get_emission_energy()

Energy multiplier for the emission texture. This will make the decal emit light at a higher intensity.

Vector3 extents

Default	`Vector3(1, 1, 1)`
Setter	set_extents(value)
Getter	get_extents()

Sets the size of the AABB used by the decal. The AABB goes from -extents to extents.

float lower_fade

Default	`0.3`
Setter	set_lower_fade(value)
Getter	get_lower_fade()

Sets the curve over which the decal will fade as the surface gets further from the center of the AABB.

Color modulate

Default	`Color(1, 1, 1, 1)`
Setter	set_modulate(value)
Getter	get_modulate()

Changes the Color of the Decal by multiplying it with this value.

float normal_fade

Default	`0.0`
Setter	set_normal_fade(value)
Getter	get_normal_fade()

Fades the Decal if the angle between the Decal's AABB and the target surface becomes too large. A value of 0 projects the Decal regardless of angle, a value of 1 limits the Decal to surfaces that are nearly perpendicular.

Texture2D texture_albedo

Setter	set_texture(value)
Getter	get_texture()

Texture2D with the base Color of the Decal. Either this or the texture_emission must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object.

Texture2D texture_emission

Setter	set_texture(value)
Getter	get_texture()

Texture2D with the emission Color of the Decal. Either this or the texture_emission must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object.

Texture2D texture_normal

Setter	set_texture(value)
Getter	get_texture()

Texture2D with the per-pixel normal map for the decal. Use this to add extra detail to decals.

Texture2D texture_orm

Setter	set_texture(value)
Getter	get_texture()

Texture2D storing ambient occlusion, roughness, and metallic for the decal. Use this to add extra detail to decals.

float upper_fade

Default	`0.3`
Setter	set_upper_fade(value)
Getter	get_upper_fade()

Sets the curve over which the decal will fade as the surface gets further from the center of the AABB.

Method Descriptions¶

Texture2D get_texture ( DecalTexture type ) const

Returns the Texture2D associated with the specified DecalTexture. This is a convenience method, in most cases you should access the texture directly.

For example, instead of albedo_tex = $Decal.get_texture(Decal.TEXTURE_ALBEDO), use albedo_tex = $Decal.texture_albedo.

One case where this is better than accessing the texture directly is when you want to copy one Decal's textures to another. For example:

for i in Decal.TEXTURE_MAX:
    $NewDecal.set_texture(i, $OldDecal.get_texture(i))

for (int i = 0; i < (int)Decal.DecalTexture.Max; i++)
{
    GetNode<Decal>("NewDecal").SetTexture(i, GetNode<Decal>("OldDecal").GetTexture(i));
}

void set_texture ( DecalTexture type, Texture2D texture )

Sets the Texture2D associated with the specified DecalTexture. This is a convenience method, in most cases you should access the texture directly.

For example, instead of $Decal.set_texture(Decal.TEXTURE_ALBEDO, albedo_tex), use $Decal.texture_albedo = albedo_tex.

One case where this is better than accessing the texture directly is when you want to copy one Decal's textures to another. For example:

for i in Decal.TEXTURE_MAX:
    $NewDecal.set_texture(i, $OldDecal.get_texture(i))

for (int i = 0; i < (int)Decal.DecalTexture.Max; i++)
{
    GetNode<Decal>("NewDecal").SetTexture(i, GetNode<Decal>("OldDecal").GetTexture(i));
}