r.ShaderCompiler.RecompileShadersOnSave

r.ShaderCompiler.RecompileShadersOnSave

#Overview

name: r.ShaderCompiler.RecompileShadersOnSave

This variable is created as a Console Variable (cvar).

• type: Var
• help: When enabled, the editor will attempt to recompile any shader files that have changed when saved. Useful for iterating on shaders in the editor.\nDefault: false

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderCompiler.RecompileShadersOnSave is to enable automatic recompilation of shader files when they are saved in the editor. This feature is primarily used for iterating on shaders during development.

The Unreal Engine subsystem that relies on this setting variable is the Shader Compiler system, which is part of the engine’s rendering module. This can be seen from the file location (ShaderCompiler.cpp) and the context in which it’s used.

The value of this variable is set through a console variable (CVarRecompileShadersOnSave) which is defined as a static TAutoConsoleVariable. It’s initialized with a default value of false, meaning this feature is disabled by default.

The associated variable CVarRecompileShadersOnSave interacts directly with r.ShaderCompiler.RecompileShadersOnSave. They share the same value and purpose.

Developers must be aware that:

1. This feature is only available in editor builds (WITH_EDITOR is checked).
2. Enabling this feature can impact performance, as it will trigger shader recompilation whenever relevant files are saved.
3. It’s intended for development and iteration, not for use in shipping builds.

Best practices when using this variable include:

1. Only enable it when actively working on shaders to avoid unnecessary recompilations.
2. Be aware of the performance impact, especially in large projects with many shaders.
3. Use in conjunction with other shader development tools and practices for efficient workflow.

Regarding the associated variable CVarRecompileShadersOnSave:

• It’s the actual console variable that controls the behavior.
• It’s defined as read-only (ECVF_ReadOnly), meaning it can’t be changed at runtime through console commands.
• It’s used to initialize directory watchers that monitor shader file changes when enabled.

Developers should use this console variable to control the behavior, typically setting it in configuration files or at engine startup, rather than trying to modify it at runtime.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:89

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarRecompileShadersOnSave(
	TEXT("r.ShaderCompiler.RecompileShadersOnSave"),
	false,
	TEXT("When enabled, the editor will attempt to recompile any shader files that have changed when saved.  Useful for iterating on shaders in the editor.\n")
	TEXT("Default: false"),
	ECVF_ReadOnly);

int32 GShaderCompilerJobCache = 1;

#Associated Variable and Callsites

This variable is associated with another variable named CVarRecompileShadersOnSave. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:88

Scope: file

Source code excerpt:

LLM_DEFINE_TAG(ShaderCompiler);

static TAutoConsoleVariable<bool> CVarRecompileShadersOnSave(
	TEXT("r.ShaderCompiler.RecompileShadersOnSave"),
	false,
	TEXT("When enabled, the editor will attempt to recompile any shader files that have changed when saved.  Useful for iterating on shaders in the editor.\n")
	TEXT("Default: false"),
	ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:5737

Scope (from outer to inner):

file
function     FShaderCompilingManager::FShaderCompilingManager

Source code excerpt:

#if WITH_EDITOR
	static const bool bAllowShaderRecompileOnSave = CVarRecompileShadersOnSave.GetValueOnAnyThread();
	if (bAllowShaderRecompileOnSave)
	{
		if (IDirectoryWatcher* DirectoryWatcher = FModuleManager::LoadModuleChecked<FDirectoryWatcherModule>(TEXT("DirectoryWatcher")).Get())
		{
			// Handle if we are watching a directory for changes.
			{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:5841

Scope (from outer to inner):

file
function     FShaderCompilingManager::~FShaderCompilingManager

Source code excerpt:

#if WITH_EDITOR
	const bool bAllowShaderRecompileOnSave = CVarRecompileShadersOnSave.GetValueOnAnyThread();
	if (bAllowShaderRecompileOnSave)
	{
		if (IDirectoryWatcher* DirectoryWatcher = FModuleManager::LoadModuleChecked<FDirectoryWatcherModule>(TEXT("DirectoryWatcher")).Get())
		{
			for (const auto& It : DirectoryWatcherHandles)
			{