Custom HLSL Global Shaders in UE5: C++ & RDG Guide

The Architectural Case for Native Global Shaders

At Outlore, building deterministic combat architectures for Project Ronin and writing bespoke C++ rendering routines has proven that developer convenience should never hide pipeline reality. Unreal's Material Editor is fine for quick surface shaders, but when you need surgical control over full-screen passes, custom compute dispatch, or stylized post-fx, wrapping HLSL inside graph bloat is an architectural liability. Writing native FGlobalShader implementations backed by RDG strips out the fluff, enforces explicit memory layout across the CPU-GPU boundary, and treats the rendering pipeline with the directness it demands. Read technical details on outlore game studio project ronin. Reference: Combat Token System in C++: Multi-Enemy AI Pacing. Reference: UE5 GAS Melee Combo Tree Architecture in C++. Reference: Structuring Character State Machines in C++ for Action Combat. Reference: Souls-Like Parry Windows in Unreal Engine C++: An Architecture. Reference: Why UE5 Live Coding Crashes When You Edit Header Files.

Unlike material shaders, which compile per material domain and generate massive permutation matrices tied to mesh attributes, global shaders operate on fixed geometry or abstract compute grids. They do not interface with scene primitives, UV channels, or vertex factory bindings. Instead, they give you direct access to the Render Dependency Graph (RDG), raw StructuredBuffers, and uniform parameter blocks with zero abstraction overhead. Read technical details on project ronin action combat souls-like.

Module Initialization and the PostConfigInit Contract

The most common failure point when implementing custom global shaders is module lifecycle management. Unreal Engine compiles global shaders during early engine initialization. If you attempt to declare or register an FGlobalShader inside a standard gameplay module set to the Default loading phase, the engine asserts immediately during startup with a fatal error: 'Shader type was loaded after engine init'. Read technical details on studio story founder game development journey.

To satisfy this requirement, custom shaders must reside in a dedicated C++ module whose LoadingPhase is explicitly assigned to PostConfigInit in your project's .uproject or your plugin's .uplugin descriptor. This ensures that the engine's shader compiler registers the C++ shader types before the global shader cache is locked. Read technical details on project ronin games roster.

{
  "FileVersion": 3,
  "Modules": [
    {
      "Name": "RoninRenderer",
      "Type": "Runtime",
      "LoadingPhase": "PostConfigInit"
    }
  ]
}

In your module's Build.cs file, you must declare public dependencies on Core, CoreUObject, Engine, RenderCore, RHI, and Projects. RenderCore provides the core shader registry primitives and directory mapping APIs, while RHI handles the raw hardware interfaces.

using UnrealBuildTool;

public class RoninRenderer : ModuleRules
{
    public RoninRenderer(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(new string[] {
            "Core",
            "CoreUObject",
            "Engine",
            "RenderCore",
            "Renderer",
            "RHI",
            "Projects"
        });
    }
}

Virtual Directory Mapping in StartupModule

Unreal Engine resolves shader source files (.usf and .ush) through a virtual file system rather than absolute disk paths. By default, the engine only searches within its internal Engine/Shaders directory. To maintain your HLSL source code under project version control without modifying engine files, you must mount a custom virtual shader directory during module startup.

Implement IModuleInterface::StartupModule and call AddShaderSourceDirectoryMapping. This binds a virtual root like /ProjectShaders/ directly to a physical directory on disk, such as FPaths::ProjectDir() / TEXT("Shaders").

#include "RoninRendererModule.h"
#include "Interfaces/IPluginManager.h"
#include "Misc/Paths.h"
#include "ShaderCore.h"

void FRoninRendererModule::StartupModule()
{
    const FString ShaderDirectory = FPaths::Combine(FPaths::ProjectDir(), TEXT("Shaders"));
    AddShaderSourceDirectoryMapping(TEXT("/ProjectShaders"), ShaderDirectory);
}

void FRoninRendererModule::ShutdownModule()
{
    ResetAllShaderSourceDirectoryMappings();
}

IMPLEMENT_MODULE(FRoninRendererModule, RoninRenderer)

Declaring FGlobalShader and Parameter Structs

Legacy versions of Unreal relied on manual parameter binding via SetShaderValue and SetTextureParameter. Modern UE5 discards this boilerplate in favor of declarative parameter blocks defined through the BEGIN_SHADER_PARAMETER_STRUCT and END_SHADER_PARAMETER_STRUCT macros. This mirrors HLSL constant buffers directly in C++ with automatic alignment validation.

When building shared data layouts between C++ and HLSL, never use high-level Unreal container types such as TArray or dynamic FVector classes inside shared uniform blocks. HLSL has no comprehension of engine allocators. Stick strictly to primitive types, FVector4f, FMatrix44f, or explicit GPU resource bindings like SHADER_PARAMETER_RDG_TEXTURE.

#pragma once

#include "GlobalShader.h"
#include "ShaderParameterStruct.h"

class FRoninPostProcessCS : public FGlobalShader
{
public:
    DECLARE_GLOBAL_SHADER(FRoninPostProcessCS);
    SHADER_USE_PARAMETER_STRUCT(FRoninPostProcessCS, FGlobalShader);

    BEGIN_SHADER_PARAMETER_STRUCT(FParameters, )
        SHADER_PARAMETER(FVector4f, VignetteColor)
        SHADER_PARAMETER(float, Intensity)
        SHADER_PARAMETER_RDG_TEXTURE_SRV(Texture2D, InputTexture)
        SHADER_PARAMETER_RDG_TEXTURE_UAV(RWTexture2D<float4>, OutputTexture)
    END_SHADER_PARAMETER_STRUCT()

    static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& Parameters)
    {
        return IsFeatureLevelSupported(Parameters.Platform, ERHIFeatureLevel::SM5);
    }

    static void ModifyCompilationEnvironment(const FGlobalShaderPermutationParameters& Parameters, FShaderCompilerEnvironment& OutEnvironment)
    {
        FGlobalShader::ModifyCompilationEnvironment(Parameters, OutEnvironment);
        OutEnvironment.SetDefine(TEXT("THREADGROUP_SIZE"), 16);
    }
};

Compiling and Registering the Shader Implementation

Declaring the class header is only half the equation; the engine requires explicit registration linking the C++ type to the physical .usf source file, entry point identifier, and shader frequency stage. In your module's implementation file (.cpp), invoke IMPLEMENT_GLOBAL_SHADER.

The macro maps your class type, virtual shader path, entry point function name, and target shader frequency (such as SF_Compute, SF_Pixel, or SF_Vertex). If your ShouldCompilePermutation logic evaluates to true, the engine compiles the bytecode and serializes it into the global cache.

#include "RoninPostProcessCS.h"

IMPLEMENT_GLOBAL_SHADER(FRoninPostProcessCS, "/ProjectShaders/RoninPostProcess.usf", "MainCS", SF_Compute);

Next, implement the corresponding HLSL code inside Shaders/RoninPostProcess.usf within your project root. Keep the constant buffer signature aligned with your parameter struct.

#include "/Engine/Public/Platform.ush"

float4 VignetteColor;
float Intensity;
Texture2D<float4> InputTexture;
RWTexture2D<float4> OutputTexture;

[numthreads(THREADGROUP_SIZE, THREADGROUP_SIZE, 1)]
void MainCS(uint3 DispatchThreadId : SV_DispatchThreadID)
{
    uint2 PixelCoord = DispatchThreadId.xy;
    uint2 Dimensions;
    OutputTexture.GetDimensions(Dimensions.x, Dimensions.y);

    if (PixelCoord.x >= Dimensions.x || PixelCoord.y >= Dimensions.y)
    {
        return;
    }

    float2 UV = (float2(PixelCoord) + 0.5f) / float2(Dimensions);
    float4 SceneColor = InputTexture.Load(int3(PixelCoord, 0));

    float DistanceFromCenter = length(UV - 0.5f) * 1.4142f;
    float Mask = smoothstep(0.4f, 1.0f, DistanceFromCenter) * Intensity;

    float4 FinalColor = lerp(SceneColor, VignetteColor, Mask);
    OutputTexture[PixelCoord] = FinalColor;
}

RDG Integration via FSceneViewExtensionBase

Injecting native passes into UE5 does not require overriding core engine systems. The correct architectural injection point is FSceneViewExtensionBase. By subclassing this interface, you can tap directly into the render pipeline across hooks such as PrePostProcessPass_RenderThread without hacking scene capture actors or wrapping logic inside the Material Graph.

Within the render thread callback, you utilize the incoming FRDGBuilder instance. You declare your textures, instantiate your parameter struct via GraphBuilder.AllocParameters, and dispatch the pass using FComputeShaderUtils::AddPass.

#include "SceneViewExtension.h"
#include "RenderGraphBuilder.h"
#include "RenderGraphUtils.h"
#include "RoninPostProcessCS.h"

class FRoninViewExtension : public FSceneViewExtensionBase
{
public:
    FRoninViewExtension(const FAutoRegister& AutoRegister) : FSceneViewExtensionBase(AutoRegister) {}

    virtual void SetupViewFamily(FSceneViewFamily& InViewFamily) override {}
    virtual void SetupView(FSceneViewFamily& InViewFamily, FSceneView& InView) override {}
    virtual void BeginRenderViewFamily(FSceneViewFamily& InViewFamily) override {}

    virtual void PrePostProcessPass_RenderThread(FRDGBuilder& GraphBuilder, const FSceneView& View, const FPostProcessingInputs& Inputs) override
    {
        FRDGTextureRef SceneColor = Inputs.SceneColor.IsValid() ? Inputs.SceneColor.Resolve : nullptr;
        if (!SceneColor)
        {
            return;
        }

        FRDGTextureDesc OutputDesc = SceneColor->Desc;
        OutputDesc.Flags |= TexCreate_UAV;
        FRDGTextureRef OutputTexture = GraphBuilder.CreateTexture(OutputDesc, TEXT("RoninPostProcess_Output"));

        FRoninPostProcessCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FRoninPostProcessCS::FParameters>();
        PassParameters->VignetteColor = FVector4f(0.05f, 0.0f, 0.1f, 1.0f);
        PassParameters->Intensity = 0.85f;
        PassParameters->InputTexture = GraphBuilder.CreateSRV(FRDGTextureSRVDesc::Create(SceneColor));
        PassParameters->OutputTexture = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(OutputTexture));

        TShaderMapRef<FRoninPostProcessCS> ComputeShader(View.ShaderMap);

        FIntVector GroupCount = FComputeShaderUtils::GetGroupCount(
            OutputDesc.Extent,
            FIntPoint(16, 16)
        );

        FComputeShaderUtils::AddPass(
            GraphBuilder,
            RDG_EVENT_NAME("RoninPostProcessDispatch"),
            ComputeShader,
            PassParameters,
            GroupCount
        );
    }
};

Live Shader Iteration and Memory Safety Protocols

Restarting the Unreal Editor to test a one-line HLSL change destroys developer velocity. To achieve rapid iteration during engine runtime, ensure r.ShaderDevelopmentMode=1 is set within your project's ConsoleVariables.ini. This flag enables detailed compilation diagnostics and hot-reloading hooks.

Whenever you alter your .usf or .ush files on disk, execute the console command recompileshaders changed or press Ctrl+Shift+Period in the viewport. The engine re-reads the modified files, recompiles the byte code, updates the in-memory shader maps, and immediately swaps the pipeline state without dropping your active PIE session.

When developing these systems, pay strict attention to resource lifetimes inside RDG. Never persist FRDGTextureRef or FRDGBuilder references across frame boundaries. The Render Dependency Graph is strictly transient; memory is pooled and repurposed every frame. Persisting raw RDG pointers into game-thread objects causes silent GPU driver crashes or memory corruption.