Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Using decals¶

Note

Decals are only supported in the Clustered Forward and Forward Mobile rendering backends, not the Compatibility backend.

If using the Compatibility backend, consider using Sprite3D as an alternative for projecting decals onto (mostly) flat surfaces.

Decals are projected textures that apply on opaque or transparent surfaces in 3D. This projection happens in real-time and doesn't rely on mesh generation. This allows you to move decals every frame with only a small performance impact, even when applied on complex meshes.

While decals cannot add actual geometry detail onto the projected surface, decals can still make use of physically-based rendering to provide similar properties to full-blown PBR materials.

On this page, you'll learn:

How to set up decals in the 3D editor.
How to create decals during gameplay in a 3D scene (such as bullet impacts).
How to balance decal configuration between performance and quality.

Use cases¶

Static decoration¶

Sometimes, the fastest way to add texture detail to a scene is to use decals. This is especially the case for organic detail, such as patches of dirt or sand scattered on a large surface. Decals can help break up texture repetition in scenes and make patterns look more natural. On a smaller scale, decals can also be used to create detail variations for objects. For example, decals can be used to add nuts and bolts on top of hard-surface geometry.

Since decals can inject their own PBR properties on top of the projected surfaces, they can also be used to create footprints or wet puddles.

Dirt added on top of level geometry using decals¶

Dynamic gameplay elements¶

Decals can represent temporary or persistent gameplay effects such as bullet impacts and explosion scorches.

Using an AnimationPlayer node or a script, decals can be made to fade over time (and then be removed using queue_free()) to improve performance.

Blob shadows¶

Blob shadows are frequently used in mobile projects (or to follow a retro art style), as real-time lighting tends to be too expensive on low-end mobile devices. However, when relying on baked lightmaps with fully baked lights, dynamic objects will not cast any shadow from those lights. This makes dynamic objects in lightmapped scenes look flat in comparison to real-time lighting, with dynamic objects almost looking like they're floating.

Thanks to blob shadows, dynamic objects can still cast an approximative shadow. Not only this helps with depth perception in the scene, but this can also be a gameplay element, especially in 3D platformers. The blob shadow's length can be extended to let the player know where they will land if they fall straight down.

Even with real-time lighting, blob shadows can still be useful as a form of ambient occlusion for situations where SSAO is too expensive or too unstable due to its screen-space nature. For example, vehicles' underside shadows are well-represented using blob shadows.

Quick start guide¶

Creating decals in the editor¶

Create a Decal node in the 3D editor.
In the inspector, expand the Textures section and load a texture in Textures > Albedo.
Move the Decal node towards an object, then rotate it so the decal is visible (and in the right orientation). If the decal appears mirrored, try to rotate it by 180 degrees. You can double-check whether it's in the right orientation by increasing Parameters > Normal Fade to 0.5. This will prevent the Decal from being projected on surfaces that are not facing the decal.
If your decal is meant to affect static objects only, configure it to prevent affecting dynamic objects (or vice versa). To do so, change the decal's Cull Mask property to exclude certain layers. After doing this, modify your dynamic objects' MeshInstance3D nodes to change their visibility layers. For instance, you can move them from layer 1 to layer 2, then disable layer 2 in the decal's Cull Mask property.

Decal node properties¶

Extents: The size of the decal. The Y axis determines the length of the decal's projection. Keep the projection length as short as possible to improve culling opportunities, therefore improving performance.

Textures¶

Albedo: The albedo (diffuse/color) map to use for the decal. In most situations, this is the texture you want to set first. If using a normal or ORM map, an albedo map must be set to provide an alpha channel. This alpha channel will be used as a mask to determine how much the normal/ORM maps will affect the underlying surface.
Normal: The normal map to use for the decal. This can be used to increase perceived detail on the decal by modifying how light reacts to it. The impact of this texture is multiplied by the albedo texture's alpha channel (but not Albedo Mix).
ORM: The Occlusion/Roughness/Metallic map to use for the decal. This is an optimized format for stor