Description

Decals are used to project a texture onto aMesh in the scene. Use Decals to add detail to a scene without affecting the underlyingMesh. 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 anAABB and a group ofTexture2Ds specifyingColor, normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within theirAABB 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).

TheTexture2Ds 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.

Note: Decals cannot affect an underlying material's transparency, regardless of its transparency mode (alpha blend, alpha scissor, alpha hash, opaque pre-pass). This means translucent or transparent areas of a material will remain translucent or transparent even if an opaque decal is applied on them.

Note: Decals are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 decals can be displayed on each mesh resource. Attempting to display more than 8 decals on a single mesh resource will result in decals flickering in and out as the camera moves.

Note: When using the Mobile rendering method, decals will only correctly affect meshes whose visibility AABB intersects with the decal's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB,GeometryInstance3D.extra_cull_margin must be increased on the mesh. Otherwise, the decal may not be visible on the mesh.

Properties

Methods

Enumerations

enumDecalTexture:🔗

DecalTextureTEXTURE_ALBEDO =0

Texture2D corresponding totexture_albedo.

DecalTextureTEXTURE_NORMAL =1

Texture2D corresponding totexture_normal.

DecalTextureTEXTURE_ORM =2

Texture2D corresponding totexture_orm.

DecalTextureTEXTURE_EMISSION =3

Texture2D corresponding totexture_emission.

DecalTextureTEXTURE_MAX =4

Max size ofDecalTexture enum.

Property Descriptions

floatalbedo_mix =1.0🔗

• voidset_albedo_mix(value:float)

• floatget_albedo_mix()

Blends the albedoColor of the decal with albedoColor of the underlying mesh. This can be set to0.0 to create a decal that only affects normal or ORM. In this case, an albedo texture is still required as its alpha channel will determine where the normal and ORM will be overridden. See alsomodulate.

intcull_mask =1048575🔗

• voidset_cull_mask(value:int)

• intget_cull_mask()

Specifies whichVisualInstance3D.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.

floatdistance_fade_begin =40.0🔗

• voidset_distance_fade_begin(value:float)

• floatget_distance_fade_begin()

The distance from the camera at which the Decal begins to fade away (in 3D units).

booldistance_fade_enabled =false🔗

• voidset_enable_distance_fade(value:bool)

• boolis_distance_fade_enabled()

Iftrue, decals will smoothly fade away when far from the activeCamera3D starting atdistance_fade_begin. The Decal will fade out overdistance_fade_begin +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.

floatdistance_fade_length =10.0🔗

• voidset_distance_fade_length(value:float)

• floatget_distance_fade_length()

The distance over which the Decal fades (in 3D units). The Decal becomes slowly more transparent over this distance and is completely invisible at the end. Higher values result in a smoother fade-out transition, which is more suited when the camera moves fast.

floatemission_energy =1.0🔗

• voidset_emission_energy(value:float)

• floatget_emission_energy()

Energy multiplier for the emission texture. This will make the decal emit light at a higher or lower intensity, independently of the albedo color. See alsomodulate.

floatlower_fade =0.3🔗

• voidset_lower_fade(value:float)

• floatget_lower_fade()

Sets the curve over which the decal will fade as the surface gets further from the center of theAABB. Only positive values are valid (negative values will be clamped to0.0). See alsoupper_fade.

Colormodulate =Color(1,1,1,1)🔗

• voidset_modulate(value:Color)

• Colorget_modulate()

Changes theColor of the Decal by multiplying the albedo and emission colors with this value. The alpha component is only taken into account when multiplying the albedo color, not the emission color. See alsoemission_energy andalbedo_mix to change the emission and albedo intensity independently of each other.

floatnormal_fade =0.0🔗

• voidset_normal_fade(value:float)

• floatget_normal_fade()

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

Note: Settingnormal_fade to a value greater than0.0 has a small performance cost due to the added normal angle computations.

Vector3size =Vector3(2,2,2)🔗

• voidset_size(value:Vector3)

• Vector3get_size()

Sets the size of theAABB used by the decal. All dimensions must be set to a value greater than zero (they will be clamped to0.001 if this is not the case). The AABB goes from-size/2 tosize/2.

Note: To improve culling efficiency of "hard surface" decals, set theirupper_fade andlower_fade to0.0 and set the Y component of thesize as low as possible. This will reduce the decals' AABB size without affecting their appearance.

Texture2Dtexture_albedo🔗

• voidset_texture(type:DecalTexture, texture:Texture2D)

• Texture2Dget_texture(type:DecalTexture)const

Texture2D with the baseColor of the Decal. Either this or thetexture_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.

Note: UnlikeBaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode forDecal textures is set globally withProjectSettings.rendering/textures/decals/filter.

Texture2Dtexture_emission🔗

• voidset_texture(type:DecalTexture, texture:Texture2D)

• Texture2Dget_texture(type:DecalTexture)const

Texture2D with the emissionColor of the Decal. Either this or thetexture_albedo 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.

Note: UnlikeBaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode forDecal textures is set globally withProjectSettings.rendering/textures/decals/filter.

Texture2Dtexture_normal🔗

• voidset_texture(type:DecalTexture, texture:Texture2D)

• Texture2Dget_texture(type:DecalTexture)const

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

Note: UnlikeBaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode forDecal textures is set globally withProjectSettings.rendering/textures/decals/filter.

Note: Setting this texture alone will not result in a visible decal, astexture_albedo must also be set. To create a normal-only decal, load an albedo texture intotexture_albedo and setalbedo_mix to0.0. The albedo texture's alpha channel will be used to determine where the underlying surface's normal map should be overridden (and its intensity).

Texture2Dtexture_orm🔗

• voidset_texture(type:DecalTexture, texture:Texture2D)

• Texture2Dget_texture(type:DecalTexture)const

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

Note: UnlikeBaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode forDecal textures is set globally withProjectSettings.rendering/textures/decals/filter.

Note: Setting this texture alone will not result in a visible decal, astexture_albedo must also be set. To create an ORM-only decal, load an albedo texture intotexture_albedo and setalbedo_mix to0.0. The albedo texture's alpha channel will be used to determine where the underlying surface's ORM map should be overridden (and its intensity).

floatupper_fade =0.3🔗

• voidset_upper_fade(value:float)

• floatget_upper_fade()

Sets the curve over which the decal will fade as the surface gets further from the center of theAABB. Only positive values are valid (negative values will be clamped to0.0). See alsolower_fade.

Method Descriptions

Texture2Dget_texture(type:DecalTexture)const🔗

Returns theTexture2D associated with the specifiedDecalTexture. This is a convenience method, in most cases you should access the texture directly.

For example, instead ofalbedo_tex=$Decal.get_texture(Decal.TEXTURE_ALBEDO), usealbedo_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:

foriinDecal.TEXTURE_MAX:$NewDecal.set_texture(i,$OldDecal.get_texture(i))

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

voidset_texture(type:DecalTexture, texture:Texture2D)🔗

Sets theTexture2D associated with the specifiedDecalTexture. 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:

foriinDecal.TEXTURE_MAX:$NewDecal.set_texture(i,$OldDecal.get_texture(i))

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