UE4 – Loading shaders from within the project folder

Unreal Engine 4.25

I’m probably the 10th guy that’s documenting these steps on the web,
I didn’t come up with this solution myself, I learned it from the sources listed below.
The reason I’m documenting this (again) myself is to have a clear source I can come back to for this issue because I’m absolutely incapable of remembering subjects like this…… :-\
If you find inaccuracies in the steps I’m detailing or my explanation, I’ll be very grateful if you share a comment.

  1. https://forums.unrealengine.com/development-discussion/rendering/1562454-virtual-shader-source-path-link-custom-shaders-shadertoy-demo-download
  2. https://dinwy.github.io/study/2019/july/customShaderInUE4/
  3. https://forums.unrealengine.com/community/community-content-tools-and-tutorials/1710373-using-external-shader-files-ush-usf-and-getting-the-most-of-the-custom-node

In short:
AFAIK since version 4.21 UE doesn’t load custom node shader code from your project/Shaders folder by default anymore, but only from the shaders folder in the engine installation, which makes it less practical for developing shaders for specific projects.

Steps for setting the UE project to load shaders from the project folder in UE 4.22:

> The examples here are for a project named: “Tech_Lab”

A. The project must be a C++ project:

So either create a new project, define as such or just create a new C++ class and compile the project with it to convert it to a C++ project.
a. You may need to right click the .uproject file icon and and Generate Visual Studio Project Files for the project to load correctly into Visual Studio and compile.
b. You can delete the unneeded C++ class you added after the new settings took place.

B. Create a folder for the shader files:

Typically, it will be called “Shaders” and will be placed in the project root folder.

C. Add the RenderCore module to the project:

This is done by adding string “RenderCore” to array of public dependency modules in the <project>.build.cs file:

PublicDependencyModuleNames.AddRange(new string[] { "RenderCore", "Core", "CoreUObject", "Engine", "InputCore" });
(see image)

a. In UE 4.21 it should be ShaderCore.
b. This addition is needed in-order to compile a new primary project module (next step).

D. Define a custom primary module for your project:

In <project_name>.h file add a new module named F<project_name>Module, with a StartupModule function overrides.
a. We have add an include statement for “Modules/ModuleManager”.
b. The <project_name>.h file is located in the /Source/<project_name> folder.
c. Some sources state that you also have to override the ShutdownModule function, with an empty override, it works for me without this (maybe its just a mistake..)

E. Implement the function override,
and set the custom module as the project primary module:

In <project_name>.cpp file, add the StartupModule override,
With the definition of the added shaders path:
FString ShaderDirectory = FPaths::Combine(FPaths::ProjectDir(), TEXT("Shaders"));

and mapping this new path as “/Project” for conveniently including it:
AddShaderSourceDirectoryMapping("/Project", ShaderDirectory);

Last thing to do is to replace “FDefaultGameModuleImpl” with our custom module name in the IMPLEMENT_PRIMARY_GAME_MODULE macro:
IMPLEMENT_PRIMARY_GAME_MODULE(FTech_LabModule, Tech_Lab, "Tech_Lab" );

a. We must include “Misk/Paths”
b. Note that the addition of this folder mapping is restricted to versions 4.22 and higher via a compiler directive condition. for version 4.21, you should state “ENGINE_MINOR_VERSION >= 21:

F. Wrapping up:

After taking these steps and compiling the project.
You should be able to include .ush and .usf files stored in <your_ue_project>/Shaders with the “Project” path mapping:
include "/Project/test.usf"

That’s it! ūüôā

I hope you found this helpful,
And if you encountered errors, or inaccuracies,
I’ll be grateful if you’ll take the time to comment.


  1. UE4 – Cyber enhancement shader
  2. UE4 – Fog post process effect

Using OSL Shaders in Blender & Cycles

Blender 2.82 | Cycles

The Cycles render engine in Blender has a very convenient OSL Shader development and usage workflow.
Shaders can be both loaded from external files or written and compiled directly inside Blender.

Before you begin:
Make sure your Blender scene is set to use the Cycles render engine, in CPU rendering mode, and also check the option Open Shading Language:
Annotation 2020-05-28 165830


To write an OSL shader in Blender:

  1. Write your shader code in Blender‘s Text Editor:
    Annotation 2020-05-28 173405
  2. In your object’s material shader graph (Shader Editor view),
    Create a Script node:
    Annotation 2020-05-28 170331
  3. Set the Script node‘s mode to Internal,
    And select your shader’s text from the Script node‘s source drop-down:
    Annotation 2020-05-28 170711
  4. If the shader compiles successfully, the Script node will display its input and output parameters, and you can connect it’s output to an appropriate input in your shading graph.
    * If your shader is a material (color closure) connect it directly to the Material Output node’s Surface input, is it’s a volume to the Volume input, or if its a texture to other material inputs as needed.
    Annotation 2020-05-28 171419
  5. If the shader code contains errors, it will fail to compile, and you’l be able to read the error messages in Blender‘s System Console window:
    Annotation 2020-05-28 172423
  6. After fixing errors or updating the shader’s code, press the Script Noe Update button on the Script node to re-compile the shader:
    Annotation 2020-05-28 172735


Loading an external OSL shader into Cycles:

Exactly the same workflow described in the previous section, except setting the Script node‘s mode to External and either typing a path to the shader file in the Script node or pressing the little folder button to locate it using the file browser:Annotation 2020-05-28 173159



  1. OSL read-list
  2. What are OSL shaders?
  3. Using OSL shaders in Arnold for Maya
  4. Using OSL shaders in V-ray for 3ds max
  5. Writing a basic OSL color shader
  6. Blender 2.83 OSL bug & fix

Using OSL Shaders in V-Ray for 3ds max

3ds max 2020 | V-Ray next

V-Ray for 3ds max supports compiling and rendering OSL shaders,
And also offers some handy shaders for download on the V-Ray documentation website.
OSL shaders are supported only in V-Ray Advanced and not in V-Ray GPU.


To load an external OSL shader:

  1. For a material (color closure) shader, create a:
    Materials > V-Ray > VRayOSLMtl
    For a texture shader create a:
    Maps > V-Ray > VRayOSLTex
  2. In the VRayOSLMtl or VRayOSLTex‘s General properties,
    Click the Shader File slot-button to locate and load the *.osl file.
  3. Provided that the shader has loaded and compiled successfully,
    You will now be able to set it’s custom parameters in its Parameters section:
    Annotation 2020-05-25 200439
  4. If compile errors will be found you’l be able to read the error messages in the V-Ray messages window:
    Annotation 2020-05-25 200625


To write an OSL shader:

  1. To write a material shader (color closure) create a:
    Materials > V-Ray > VRayOSLMtl
    To write a texture shader create a:
    Maps > V-Ray > VRayOSLTex
  2. Expend the Quick Shader section of the node’s properties,
    And check the Enable option.
  3. Write you’r OSL code, and press Compile.
    Annotation 2020-05-25 204835
  4. Provided that the shader compiled successfully,
    You will now be able to set it’s custom parameters in its Parameters section:
    Annotation 2020-05-25 205225
  5. If compile errors will be found you’l be able to read the error messages in the V-Ray messages window.



  1. OSL read-list
  2. What are OSL shaders?
  3. Using OSL shaders in Arnold for maya 
  4. Using OSL shaders in Blender & Cycles
  5. Writing a basic OSL color shader

Using OSL Shaders in Arnold for Maya

Maya 2020 | Arnold 6

Autodesk Maya 2020 & Arnold 6 offer a flexible OSL development and usage workflow.
You can both load or write OSL shaders on the fly, compile, test, and render them,
And also define a shader folder path for shaders to be available as part of your library for all projects.
Steps for using OSL shaders in Maya & Arnold:

Writing an OSL shader or loading it for single use (just the current project):

  1. Create a new aiOslShader node:
    Annotation 2020-05-19 220416
  2. Select the new aiOslShader node and in its attributes either write new OSL code in the code OSL Code section, or press Import to Load an OSL shader file (*.osl):
    Annotation 2020-05-19 220454
  3. When new shader code is imported, it’s automatically compiled:
    Annotation 2020-05-19 220649
  4. I f you’ve written new code, or changed the code it will have to be re-compiled.
    In that case press Compile OSL Code:
    Annotation 2020-05-19 223632
  5. The code may contain errors, in that case you will see a red Compile Failure message:
    Annotation 2020-05-19 224342
    You can read the error message in the Maya output window, or in the Maya Script Editor, Correct the code and press Compile OSL Code again.
    Annotation 2020-05-19 224410
  6. After the OSL code is compiled successfully, the shader’s input parameters can be accessed in the OSL Attributes section below the code:
    Annotation 2020-05-19 224431
  7. Depending on the type of output the OSL shader generates, the aiOSLShader node should to be connected to an input in the object’s shader graph or Shading Group.
    * OSL shaders can be surface shaders, volume shaders, procedural textures, texture processors and more..
    To Apply the OSL shader to an object as a surface shader, disconnect the object’s current surface shader if it has one,
    And then drag and drop the aiOSLShader node from the Hypershade window onto the object.
    In the Connection Editor select outValue on the left side (node outputs) and surfaceShader in the right side (object inputs):
    Annotation 2020-05-19 220810

When compiling OSL shaders “on the fly” using the above steps, the shader’s input parameters don’t necessarily appear at their intended order that is¬† defined in the shader code.


Installing OSL shaders so they will always be available as custom nodes in the Hypershade library

  1. Create a folder for storing your OSL shaders, and place you OSL shader files (*.osl) in this folder.
    Annotation 2020-05-20 225134
  2. Locate Maya’s Maya.env file.
    This is an ascii text file containing environment variables that Maya loads at startup.
    The Maya.env will usually be located at:
    C:\Users\<your user>\Documents\maya\<maya version>
    Annotation 2020-05-20 225221
  3. Open Maya.env in a text editor and add the following line to it:
    ARNOLD_PLUGIN_PATH=<path to your OSL shaders folder>
    for example:
    Annotation 2020-05-20 225400
  4. Restart Maya.
    When Maya loads, the MtoA (Maya to Arnold) plugin will automatically compile the shaders that are found in the folder, report about the compilations or found errors in the Maya output window, and create compiled *.oso files for each shader:
    Annotation 2020-05-20 230917
  5. The compiled shaders will now be available as custom nodes in the Hypershade Arnold library with the typical “ai” (Arnold Interface) prefix added to their names:
    Annotation 2020-05-20 231138
  6. The OSL shaders will be created as nodes with their editable attributes, that can be connected to an object’s shading network graph:
    * Connecting the node to the graph is the same as described in the previous part (7)
    Annotation 2020-05-20 231232



  1. OSL read-list
  2. What are OSL Shaders?
  3. Using OSL shaders in V-Ray for 3ds max
  4. Using OSL shaders in Blender & Cycles
  5. Writing a basic OSL color shader

What are OSL shaders?

OSL is an acronym for Open Shading Language.
Developed Originally at Sony Pictures Imageworks for the Arnold render engine, Open Shading language is a C like programming language with which custom material, textures and shading effects can be developed OSL shaders (*.osl files), that are supported many by popular render engines.

OSL allows development of complex texturing and shading effects using scene input parameters like the shading point’s world position vector, normal vector, UV coordinates etc., and optical ray-tracing¬† functions – BSDF*’s or “Color Closures” as they are called in OSL, like Diffuse, Glossy, Refraction light scattering etc. that can be combined with C¬† logic and math programming.

*.osl files are compiled to *.oso file for rendering.
Most render engines supporting OSL shaders ship with an OSL compiler.


Useful OSL shader libraries found on the web:

> OSL Shaders for download on the Chaos Group website:

> OSL Shaders for download at the Autodesk Developer Network Github repository:
These are the OSL shaders that ship with 3ds max 2019 or newer, and are providing texture and pattern processing tools, but not materials.
* Material shaders or “Closures” as they are referred to in OSL are not supported by 3ds max’s native implementation of OSL.

> A library of OSL shaders collected by Shane Ambler:



  1. In general, OSL shaders are supported only in CPU Rendering, but not supported by GPU renderers. There are some attempts to develop OSL support for GPU renderers, But as far as I know they are limited.
  2. Some OSL shaders will work on one or more render engines, and not work as expected on other render engines. the reason being that each render engine has it’s own implementation of OSL.
    These differences may show in a different rendered result and also compile failure.


Basic example:
The following example renders show how a combination of two basic OSL shaders iv’e written, one of which is a dielectric material shader, and the other a color/angle blend procedural texture, produce fairly consistent results when rendered in different render engines.
* note the difference in specular glossy roughness interpretation for the same 0.1 value..

> You’r welcome to download these two basic OSL shaders here.

Arnold for Maya:
Annotation 2020-05-22 213609

V-Ray for 3ds max:
Annotation 2020-05-22 213629

Cycles for Blender:
Annotation 2020-05-22 213723



  1. OSL read-list
  2. Using OSL shaders in Arnold for Maya
  3. Using OSL shaders in V-Ray for 3ds max
  4. Using OSL shaders in Blender & Cycles
  5. Writing a basic OSL color shader

Using Arnold’s Ambient Occlusion node to create an eroding paint shader effect

Maya 2018 | Arnold 5

Arnold’s Ambient Occlusion (dirt) node can be used as a procedural mask to create interesting material effects like in this example of paint that is eroded at the model’s bulging areas to reveal metal beneath it.

In this shader’s case the Ambient Occlusion node is connected to the Mix property of an Arnold Mix shader, that blends between two different Arnold Standard Surface shaders, one simulating the underlying tin metal, and the other simulating the red paint that covers it.

Note that in the Ambient Occlusion node the Invert Normals property is checked, so that the effect will create a mask for the bulges and not for the creases,
And also that the Self Only property is checked so that the node will behave as a fixed object mask disregarding the proximity of other objects.
In this example the output of the Ambient Occlusion node is also process using a Remap Value node to increase it’s contrast so it will define borders between the areas.




VRayMtl’s new metallic goodness

3ds max 2019 | V-Ray Next | V-Ray next GPU

In V-Ray Next (4) for 3ds max, a new Metalness parameter has been added to the Reflect parameters of the VRayMtl material.
This allows for easy creation of realistic metal materials and also effectively enables a PBR workflow with V-Ray.

When the Metalness parameter is set to 1.0, the material becomes completely reflective, the Diffuse color controls the general reflection color, and the Reflect color (which should generally be set to white) controls the reflection color at grazing incidence angle.

The IOR parameter still controls how fast will the main reflection color (set by the Diffuse color) blend into the Reflection color, and I don’t know whether some form of complex Fresnel has been implemented or if it’s just a dielectric simple Fresnel blended over a reflective surface.

An excellent article on the new Feature from the Chaos Group blog:



  1. Fresnel Reflections
  2. Complex Fresnel for Blender & Cycles
  3. Metal material in UE4