Custom shader code in Unreal Engine — Part 1: Setup and Configuration

3 min readFeb 23, 2020

Intro

As part of an ongoing series about developing custom shaders for plugins in Unreal Engine, we start off by looking at how we setup the environment.

Preface

Unreal Engine’s Material and Shader System is very powerful and fun to work with. If you find yourself in need of some advanced features, or having to extend the default shaders work, you have to dig into the way UE loads and processes it’s custom shader source abstraction. UE shaders come in two varieties, .ush and .usf files. These stand for unreal shader header and unreal shader file respectivly. They are really no different from each other, except that ush files are supposed to contained shared definitions to be included, and usf files actual shading work. The core engine comes with a lot of predefined shader source. You can find most of it under: Engine/Shaders

Here are some library files I’d recomment taking a peak at:

Engine/Shaders/Private/BasePassCommon.ush
Engine/Shaders/Private/BasePassVertexShader.ush
Engine/Shaders/Private/MaterialTemplate.ush

Project Settings

Create shader debug information

To enable Unreal Engine to create valuable shader debug information, we can add the following options to the config file Config/DefaultEngine.ini.

After following the setup described above, every material used in your project, will produce files showing you the combined / final shader file, after the UE shader preprocessor has glued all dependencies together. The output of your shader debug information can be found under: [YouProjectRoot]/Saved/ShaderDebugInfo/[ShaderTarget] where ShaderTarget might be PCD3D_SM5.

Optional / Recommended Settings

I would also recommend you switch off auto exposure, just to have a consitent light situation when developing. You can do this by adding this option to Config/DefaultEngine.ini or go to Project Settings -> Rendering -> Default Settings and disable it there.

Build Script

In order to allow us to configure including custom shaders in a plugin, we need to add module dependencies to RenderCore and Projects.

In MyShaderDevPlugin.Build.cs:

Plugin Setup

Directory Structure

Our custom shader source files will be located in the directory of your plugin. In this example the directory is called Shaders. The plugin’s directory structure might look something like:

Module Definition

To get started with using and developing custom shaders, we have to tell Unreal Engine to look for additional directories which can contain shader source files, so they can be compiled into materials if necessary. This can be done through mapping what is called a virtual directory. We do this in the plugin module’s startup and respective shudown method.

In MyShaderDevPlugin.cpp:

Outlook

After setting up the basic work environment, we will have a look at how we structured shaders to minimize turn-around time and allow for modularization of shared code. If you find this information useful, or have any suggestions on how to improve, we would love to hear your thoughts in the comments.

Originally published at https://biq.solutions on February 23, 2020.