Shader Stutter Tracker

A Godot 4.6+ add-on to debug and fix shader compilation stutters in the Compatibility rendering pipeline.

Limitations

Debugging tools do not yet capture all possible compilation triggers; the project is under development.

Installation

• Download the latest release and paste it into your Godot project
• For debugging tools: Enable the addon in the Project Settings

Usage

Watch the video in the GitHub README to see the plugin in action with the Third Person Shooter Demo.

Shader precompilation

Create an SSTShaderPrecompiler node and assign it a configuration describing the materials, environments and nodes to precompile.

There are two configuration variants:

1. SSTSceneExtractorPrecompilerConfig accepts a list of scenes and extracts compilation triggers from them and their dependencies. The best option to start with.
2. SSTPrecompilerConfig can be generated by debug tools or filled in manually.

Example scene with precompilation: addons/shader_stutter_tracker/examples/precompiler_screen_example.tscn. You can simply create an inherited scene to get started.

Limitations

1. Dynamically changed or created triggers and scenes loaded via load/preload cannot be covered by SSTSceneExtractorPrecompilerConfig. Add these scenes manually.
2. Not all node types may be covered. Comprehensive analysis of compilation triggers is a complex and difficult task. For instructions on identifying a problematic node, refer to the Debugging section. If you successfully identify a new compilation trigger, please create an issue.

Two trigger sources are checked:

1. Specific node types: Label3D, SpriteBase3D, Light3D and their subtypes.
2. Node properties that contain resources like Material, Mesh, Shader, MeshLibrary, MultiMesh, Environment.

Supported node properties since v0.2.0 (inherited properties are hidden):

Debugging

Installation

1. Enable plugin.
2. Enable shader_stutter_tracker/shader_watcher/enable (enabled by default in debug mode).
3. Enable shader_stutter_tracker/shader_watcher/clear_cache_on_run (enabled by default in debug mode).
4. Play your scene, then open the Shader Stutter Tracker debugger tab.
5. Report settings: shader_stutter_tracker/report/scan_triggers, take_screenshots, save_scenes.

Monitors

Add new monitors to track counters for compiled GLSL shaders.

New debug tab

In the new debug tab you can see all compilation trigger events and known compilation triggers detected by the plugin.

Some shaders are compiled on the second frame after their triggers' appearance:

• Environment related,
• Particles.

In that case, see the previous frame for the triggers.

Brute-force analysis

This tool runs the scene and iterates through the nodes, looking for trigger nodes that will be displayed in the debugging tab.

Settings

All settings are under the shader_stutter_tracker/ prefix in Editor Settings.

Acknowledgements

Standing on the shoulders of giants:

• https://github.com/Brandt-J/ShaderPrecompiler
• https://www.reddit.com/r/godot/comments/osx0f6/my_very_comprehensive_shader_cache_solution/

License

This project is licensed under the MIT License. See the LICENSE file for details.

Development

Formatter

gdscript-formatter

gdscript-formatter --reorder-code addons/shader_stutter_tracker
gdscript-formatter --reorder-code addons/shader_stutter_tracker_test
gdscript-formatter --reorder-code test

Testing

GUT framework