Writing shaders

Shaders are written in HLSL and compiled with DXC for every backend. The editor reloads them automatically when they change.

Adding a shader

Shaders live in Source/Shaders/. Write your .hlsl file, then add it to the Definitions list in Config/Shaders.hmf:

ShaderDefinitions "ShaderDefinitions" {
    Definitions = [
        ...
        ShaderDefinition "MyEffect" {
            VS = "MyEffect/MyEffect.hlsl"
            PS = "MyEffect/MyEffect.hlsl"
        }
    ]
}

Paths are relative to Source/Shaders/. The keys are the stages:

Key	Stage
VS	Vertex shader
PS	Pixel shader
CS	Compute shader
RGS, CHS, MS	Ray tracing: ray generation, closest hit, and miss

Condition = "Rendering.FogVolumes" (any bool CVar) only compiles and uses the shader while that CVar is on.

Permutations

Shader variants are declared at the top of the file:

PERMUTE(GTAO_ENABLED)
PERMUTE(LIGHT_TYPE, CLUSTERED, DIRECTIONAL, POINT, SPOT, AREA_RECT);

With just a name, it's an on/off variant. With a list of values, each variant defines one of them, such as LIGHT_TYPE_POINT:

#ifdef LIGHT_TYPE_DIRECTIONAL
    // directional light only
#endif

STATIC(NAME, value) sets a fixed define.

Precompiling

Shipping builds use precompiled shaders. Packaging does this automatically. To run it yourself:

PrecompileShaders.exe --platform=windows

Add --api=vulkan, --api=dx12 or --api=webgpu to pick a backend, or --filter=MyEffect to limit it to matching shaders. --platform takes windows, mac, linux, android, ios or web.