Shader Stutter Tracker
A Godot 4.6+ add-on to debug and fix shader compilation stutters in the Compatibility rendering pipeline.
Limitations
- Currently supports 3D nodes and Control; not all 2D nodes and Camera2D are supported yet.
- 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:
SSTSceneExtractorPrecompilerConfigaccepts a list of scenes and extracts compilation triggers from them and their dependencies. The best option to start with.
SSTPrecompilerConfigcan 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.
- 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.
- Dynamically changed or created triggers and scenes loaded via
load/preloadcannot be covered bySSTSceneExtractorPrecompilerConfig. Add these scenes manually.
Debugging
Installation- Enable plugin.
- Enable
shader_stutter_tracker/shader_watcher/enable(enabled by default in debug mode). - Enable
shader_stutter_tracker/shader_watcher/clear_cache_on_run(enabled by default in debug mode). - Play your scene, then open the Shader Stutter Tracker debugger tab.
- Report settings:
shader_stutter_tracker/report/scan_triggers,take_screenshots,save_scenes.
Add new monitors to track counters for compiled GLSL shaders.
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.
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.
| Group | Setting | Default | Default.debug | Description |
|---|---|---|---|---|
| base | preserve_settings_when_disabled |
false | false | Keep settings after disabling the plugin |
| shader_watcher | enable |
false | true | Enable the runtime shader cache watcher |
| shader_watcher | clear_cache_on_run |
false | true | Clear the shader cache before each run |
| report | scan_triggers |
false | true | Collect trigger candidates on stutter |
| report | take_screenshots |
false | true | Capture a viewport screenshot per frame |
| report | save_scenes |
false | true | Save debug scene with visible nodes |
| report | preserve_last_logs |
3 | 3 | Number of log directories to keep in user://shader_stutter_tracker/logs |
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 --reorder-code addons/shader_stutter_tracker
gdscript-formatter --reorder-code addons/shader_stutter_tracker_test
gdscript-formatter --reorder-code test
Testing
Changelog for version v0.1.0
No changelog provided for this version.