Animated Decal Node for all Godot 4 Renderers

This plugin provides both instanced and non-instanced animated decal node functionality for all Renderers in Godot 4.4-4.7.1, packaged as an easy-to-use plugin.

Allows thousands of decals to be drawn with one draw call and performs well. No limits set, unlike Godot's Compatibility/Mobile Decal limits of Max 8 decals per mesh and max 64 decals per frame.

[!IMPORTANT]
The PR to support the Decal Node for the Compatibility Renderer has been merged, with the same support as the Mobile renderer (Max 8 decals per surface, max 64 decals per frame). It should be available when Godot 4.8 launches. If you need to use hundreds or thousands of decals on a single mesh, then my solution is a very good option.

Included Demo scene:

2000 Animated Instanced Skull Decals + 1000 pooled one shot Animated Explosions Decals

1000 instanced decal bullet holes:

Features

• No limits like Godot's Decal implementation for Compatibility/Mobile renderers which limits decals to 8 decals per mesh, AND 64 decals per frame. With my solution you can use thousands of decals PER MESH.
• Projects decals onto uneven surfaces (e.g., terrain or complex geometry).
• Stencil support, which allows you to exclude specific geometry from recieving decal (such as the player).
• Decals can be projected onto both floors and walls.
• Instanced Flipbook animation support, with:
  • Speed control.
  • Both Looping (the default) and Oneshot support.
  • Easy oneshot reset.
  • Frame offset support to randomize looping animation.
• Adds two new nodes to Godot:
  • DecalCompatibility extends MeshInstance3D, which should be used when only one decal is needed.
  • DecalInstanceCompatibility extends MultiMeshInstance3D, which should be used when you need large amounts of the same decal, like bullet holes.
• No need to modify shaders - fully usable via the Godot editor Inspector.
• Full transparency support of the decal, but cannot project on semi-transparent geometry, only opaque geometry.
• Easy fading controls with start, end, and power parameters.
• Individual decal alpha control when using the DecalInstanceCompatibility node.
• Fully documented code.
• Includes three demo scenes:
  • demo.tscn shows all the features of the plugin:
    • Decals that are moving, rotating, height fading, distance culling, transparency, color modulating.
    • Instanced decals (bullet holes).
    • Both one_shot and looping decal animations.
  • instanced_flipbook.tscn shows 2000 instanced animated skulls, and 1000 oneshot explosions, rendering with just TWO draw calls.
  • instanced.tscn shows 1000 instanced bullets rendering with just ONE draw call.

Limitations

• No support for normal maps, ambient occlusion, roughness, metallic, or emission textures.
• can only project decals on fully opaque materials (no alpha or semi-transparent materials)
• Decals are unshaded (no lighting interaction).

As of V1.1 of the plugin, you can now use the plugin with the Forward+ or Mobile renderers.

Tested on Godot 4.4.1 to 4.7.1.

Limitation analysis of Godot's built in Decals nodes

From Godot official documentation:

Decal Implementation	Decals per mesh	Decals per frame	Animation Support	PBR Shaded	Cull Mask / Stencil Support
Godot's Forward+ Decal	Unlimited	Default limit of 512 clustered elements	Yes	Yes	Cull mask
Godot's Mobile Decal	8	Default limit of 64	Yes	Yes	Cull mask
Godot's Compatibility Decal	8	Default limit of 64	Yes	Yes	Cull mask
This plugin	Unlimited	Unlimited	Yes	No	Stencil Support

Video explaining limitations of Mobile/Compatibility decals: https://youtu.be/mcV4-2ymtlU

Summary:

• if QUANTITY of decals important = use this plugin.
• if ANIMATION of decals important = use Godot's default Decal nodes.
• if PBR QUALITY of decals important = use Godot's default Decal nodes.
• if projecting decals on semi-transparent materials = use Godot's default Decal nodes.

Try to do this on the offical Godot Decal Node using the Compatibility Renderer!

https://github.com/user-attachments/assets/65baf898-8b2a-42cf-9b2e-d789fb8d3fa2

Installing

Option 1: Use as a project template:

• Download this repository as a ZIP file.
• Extract the ZIP file.
• Import the project from the Godot's project selection screen.

Option 2: Add plugin to existing project:

• Download this repository as a ZIP file.
• Extract the ZIP file.
• Copy the addons directory from the extracted ZIP file into your Godot project's res:// filesystem.
• Go to Project > Project Settings > Plugins and enable Decal Compatibility Nodes plugin as shown below.

New Nodes

DecalCompatibility

Use this node if you just need one or two decals.

DecalInstanceCompatibility

Use this node if you plan to use many copies of the same decal, such as bullet holes. This allows thousands of decals to be drawn using one draw call.

custom_data is used to modify individual decal instances.

• custom_data.r = instanced one_shot timestamp
• custom_data.g = instanced frame offset [0..(x_frames * y_frames - 1)]
• custom_data.b = Not used
• custom_data.a = instance alpha of decal: use fade_out_instance(instance_id, fade_out_time, start_delay)

Using new nodes in your projects

The new nodes are automatically added to Godot. Just search Decal as shown below:

How to use

Make sure you assign a texture to the decal. Decal nodes in scenes will have warnings until you assign a texture to it.

Make sure the geometry of the decal size intersects the ground/wall geometry or else you will see nothing. Watch the tutorial video if unsure what this means. Video: https://youtu.be/8_vL1B_J56I

By default both projection of the decal and fading happen on the Y-AXIS, which works great on the ground.

If you need to use the decals on walls (like for the bullet holes), then you will need to rotate the decal. It is up to you to find the normal of the wall, and rotate the decal to the proper rotation. Watch the tutorial video if unsure what this means. Video: https://youtu.be/8_vL1B_J56I

Stencil Support

If you want specific geometry to not receive the decal projection, all you need to do is enable Stencil in the StandardMaterial3D of your player or any other object you don't want decals to be projected.

You set up the stencil in the editor as you see below:

The demos show the result below:

YouTube Tutorial and Examples

See the first tutorial at: https://youtu.be/8_vL1B_J56I

See the demos in action and more information: https://youtu.be/8XnH3mT1C-c

Example game using this plugin: https://antzgames.itch.io/little-mage

Asset Attributions

Skeleton and Mage by Kay Lousberg - CC0 License

Floor Tile by Kenney - CC0 License

Spryte free spritesheets by AutoSprite - "Meet Spryte, our mascot. Download and use in your game."