Post Process Effects

PostFX are post-processing effects applied after the scene is rendered. They shape the final image through effects such as ambient occlusion, bloom, color correction, depth of field, motion blur, local exposure, and screen-space shadows.

For modders, PostFX are best used to tune presentation, not to replace lighting. Set up the scene with physically meaningful lights, emissives, materials, exposure, and tone mapping first, then use PostFX for final image treatment.

Screen-space shadows use the depth visible from the current camera to add fine contact shadowing and shadows from distant visible geometry. They complement regular shadow maps, but cannot replace shadows from geometry outside the camera view.

What you can mod

Common PostFX modding goals:

• Add a custom color filter or grade.
• Change PostFX values when a level, scenario, camera mode, or tool starts.
• Temporarily enable or disable existing effects.
• Create a custom shader-based fullscreen effect.

Recommended approaches:

Color correction ramps

Color correction ramps are the simplest PostFX mod. They are one-dimensional PNG lookup textures used by the color correction pass.

Place custom ramps in:

art/postfx/

For example, a packed mod can contain:

my_postfx_mod.zip
art/
  postfx/
    my_color_grade.png

Ramp requirements:

• Use PNG format.
• Use a 256x1 image.
• Start from the default color ramp when creating a grade.
• Keep the grade subtle enough that exposure, sky color, headlights, UI readability, and night driving remain usable.

The game discovers color correction ramps by searching art/postfx/*.png. The same path is used by Photo Mode filters, so a ramp placed there can be used as a custom filter.

See Photomode for a practical color-ramp workflow.

Runtime tuning from Lua

Existing PostFX objects can be found through the scene tree and adjusted from Lua. This is useful for scenarios, extensions, tools, and level-specific presentation.

Typical pattern:

local dof = scenetree.findObject("DOFPostEffect")
if dof then
  dof:setFocusParams(0.0, 0.25, 50, 250, -5, 5)
  dof:setAutoFocus(false)
  dof:setFocalDist(120)
  dof:enable()
end

For simple enable/disable behavior:

local ssao = scenetree.findObject("SSAOPostFx")
if ssao then
  ssao:enable()
end

local motionBlur = scenetree.findObject("PostFxMotionBlur")
if motionBlur then
  motionBlur.strength = 0.5
  motionBlur:enable()
end

Important object names:

Use the graphics settings API when you want to change the same values exposed by the Options menu. Direct object edits are better for temporary effects, editor tools, and custom camera behavior.

Common graphics setting keys include:

• PostFXSSAOGeneralEnabled
• PostFXSSAOGeneralQuality
• PostFXScreenSpaceShadowsEnabled
• PostFXDOFGeneralEnabled
• PostFXMotionBlurEnabled
• PostFXMotionBlurStrength
• PostFXMotionBlurPlayerVehicle
• GraphicEVCompensation

Creating custom shader PostEffects

Custom shader-based effects are built from engine PostEffect objects. This is the path to use when a color ramp or runtime tuning cannot express the effect.

A custom effect usually needs:

• A ShaderData object that points to HLSL shader files.
• A GFXStateBlockData object that defines depth, blending, and sampler state.
• A PostEffect object that defines shader, textures, target, timing, and priority.
• An optional callback table for shader constants and enable checks.

Minimal Lua structure:

local shader = scenetree.findObject("MyPostFxShader")
if not shader then
  shader = createObject("ShaderData")
  shader.DXVertexShaderFile = "shaders/common/postFx/myEffect.hlsl"
  shader.DXPixelShaderFile = "shaders/common/postFx/myEffect.hlsl"
  shader.pixVersion = 5.0
  shader:registerObject("MyPostFxShader")
end

local state = scenetree.findObject("MyPostFxStateBlock")
if not state then
  state = createObject("GFXStateBlockData")
  state.zDefined = true
  state.zEnable = false
  state.zWriteEnable = false
  state.samplersDefined = true
  state:setField("samplerStates", 0, "SamplerClampLinear")
  state:registerObject("MyPostFxStateBlock")
end

local callbacks = {}
callbacks.onEnabled = function()
  return true
end
callbacks.setShaderConsts = function()
  local fx = scenetree.findObject("MyPostFx")
  if fx then
    fx:setShaderConst("$strength", 1.0)
  end
end
rawset(_G, "MyPostFxCallbacks", callbacks)

local fx = scenetree.findObject("MyPostFx")
if not fx then
  fx = createObject("PostEffect")
  fx:setField("shader", 0, "MyPostFxShader")
  fx:setField("stateBlock", 0, "MyPostFxStateBlock")
  fx:setField("texture", 0, "$backBuffer")
  fx:setField("target", 0, "$backBuffer")
  fx:setField("renderTime", 0, "PFXAfterDiffuse")
  fx:setField("renderPriority", 0, "1")
  fx:registerObject("MyPostFx")
end

Useful PostEffect fields:

Custom effects should use existing game effects as reference examples. Good starting points are lua/ge/client/postFx/fog.lua, lua/ge/client/postFx/chromaticLens.lua, lua/ge/client/postFx/caustics.lua, lua/ge/client/postFx/smaa.lua, and lua/ge/client/postFx/dof.lua.

Render targets and buffers

PostFX shaders read textures through the texture fields on the PostEffect. A texture can be a special token, a named render target, or a file path.

Special tokens:

Named render targets use #name, #name[RT0], #name[RT1], or #name[Depth]. Slots RT0 through RT7 and Depth are supported by the engine, but only slots actually filled by the producer are valid.

Common scene buffers:

Lighting and PostFX masks:

Effect-local targets created by shipped PostFX:

Sensor and tool targets such as #LIDAR_Viz_Texture, #RadarGBuffer, and #UltrasonicGBuffer exist in some builds or tools. Do not depend on them for normal graphics mods.

Reading the prepass

Most depth, normal, and roughness effects use the prepass:

fx:setField("texture", 0, "#prepass[RT0]")
fx:setField("texture", 1, "#prepass[Depth]")

The current Advanced Lighting 1.5 prepass has the following layout:

RT2 through RT7 are not populated by #prepass. The target syntax supports those slot names generically, but that does not mean every named target provides every slot. On the older Advanced Lighting path, the prepass only provides RT0 and Depth.

In HLSL, include the shared PostFX and G-buffer helpers:

#include "shaders/common/postFx/postFx.h.hlsl"
#include "shaders/common/gbuffer.hlsl"

uniform_sampler2D(prepassTex, 0);
uniform_sampler2D(prepassDepthTex, 1);

struct Appdata
{
    float4 hpos : SV_Position;
    float2 uv0 : TEXCOORD0;
};

float4 main(Appdata IN) : SV_Target
{
    float4 packedPrepass = tex2Dlod(prepassTex, float4(IN.uv0, 0, 0));
    float4 gbuffer = decodeGBuffer(
        TEX_SAMPLER(prepassDepthTex),
        TEX_SAMPLER(prepassTex),
        IN.uv0,
        projParams
    );

    float3 normalWS = gbuffer.xyz;
    float roughness = packedPrepass.z;
    return float4(normalWS * 0.5 + 0.5, roughness);
}

The example displays the decoded normal as RGB and roughness as alpha. Eye-linear depth is available in gbuffer.w for effects that need it. Use the helper functions in shaders/common/gbuffer.hlsl for normals and depth instead of manually decoding them. The prepass layout depends on the lighting path and can change.

Useful prepass facts:

• Roughness is #prepass[RT0].b, not a separate named target.
• #prepass[RT1] is present on the Advanced Lighting 1.5 path and carries specular color plus retroreflectivity.
• #prepass[Depth] is a copied depth texture that can be sampled by PostFX after the prepass.
• decodeGBuffer(...) returns world-space normal in xyz and eye-linear depth in w for the common PostFX helper overload.
• projParams, nearFar, and invNearFar are auto-bound when the shader declares them.

Shader constants

PostEffect automatically binds several constants if the shader declares them. Unused constants do not need to be declared.

Target and viewport constants:

Camera and transform constants:

Lighting, fog, water, and time constants:

Custom constants can be set from Lua callbacks:

callbacks.setShaderConsts = function()
  local fx = scenetree.findObject("MyPostFx")
  if fx then
    fx:setShaderConst("$strength", 1.0)
    fx:setShaderConst("$tint", "1 0.9 0.8 1")
  end
end

Supported script-set constant shapes are float, float2, float3, float4, and float4 arrays. Prefix shader constant names with $ when calling setShaderConst.

Timing and chaining

PostFX timing decides what buffers are already available and what later systems will see.

Common render bins used by shipped effects:

For a multi-pass effect, make a parent PostEffect and add child effects. Write intermediate passes to $outTex or a named #target, then read $inTex in the next pass. Use a named target when another effect or debug view needs to sample the result by name.

Custom shader constraints

• A generic PostEffect has six texture inputs and twelve textureCube inputs.
• ShaderData must reference registered shader files and a supported pixVersion.
• Missing named targets make the effect invalid until the target exists.
• renderPriority is sorted descending for effects with the same timing.
• skip = true skips the effect and its children without disabling siblings.
• Reflection passes skip most PostFX unless allowReflectPass = true.
• Writing directly to $backBuffer is common for final composite passes, but multi-pass effects should usually write to $outTex or named intermediate targets first.
• Compute-shader PostFX are possible through engine-side specialized classes, but generic Lua PostEffect mods should use graphics shader passes.
• Avoid depending on internal HDR/exposure targets unless the mod is tied to the current renderer version.

Performance Considerations

PostFX effects run every frame for every pixel on the screen. Even a seemingly simple shader can significantly impact performance, especially at high resolutions (4K) or on lower-end GPUs.

Optimization tips:

• Minimize texture fetches: Every tex2D call has a cost. Group your samples and avoid redundant lookups in loops.
• Avoid complex branching: Heavy use of if/else inside pixel shaders can lead to “branch divergence,” slowing down the GPU. Use step(), lerp(), or clamp() instead.
• Watch target scale: If an effect does not require full resolution (e.g., a blur pass), use targetScale to render it at a lower resolution and upscale later.
• Precision: Use half precision for colors and effects where 32-bit floating point accuracy isn’t required.
• Avoid heavy loops: Avoid long for loops in the pixel shader unless absolutely necessary (e.g., high-quality Gaussian blurs). Consider approximating effects with fewer samples.

Debugging your Effects

Debugging PostFX is challenging because you cannot step through GPU code. The primary method is “visual debugging”—outputting raw data as colors to the screen.

Techniques:

• NamedTextureTarget Viewer: Use this editor tool to browse and preview all active render targets (NamedTexTargets) in real-time. It supports pan/zoom and channel filtering, making it the fastest way to verify if a buffer like #prepass or #ssaoMask contains the expected data without modifying shaders.
• Visualizing buffers: Instead of calculating a complex effect, return the value of a specific buffer (e.g., return float4(normalWS * 0.5 + 0.5, 1); to see normals).
• Color coding values: Map a scalar value (like depth or roughness) to a color ramp to identify precision issues or clamping.
• Binary search for errors: If a shader fails to compile or causes a crash, comment out sections of the code until you find the problematic line.

Common Pitfalls

• Linear vs Non-linear Depth: Forgetting that #prepass[Depth] is non-linear (device depth). Always use decodeGBuffer or shared helpers to get eye-linear depth for distance calculations.
• Resolution Mismatches: Using a downsampled target (via targetScale) but sampling it with UVs meant for full resolution without accounting for the offset/scale.
• Assuming Target Existence: Assuming #prepass[RT1] or other buffers are available on all graphics presets. Always check if the object exists in Lua before enabling an effect that depends on a specific target.
• Ignoring Alpha Channels: Some targets store critical data (like subsurface intensity or retroreflectivity) in the alpha channel; forgetting to sample .a can lead to missing visual details.

Loading and persistence

At startup, the game initializes the Lua PostFX modules and creates the standard PostFX objects. Photo Mode keeps a temporary backup of values it changes so they can be restored when leaving Photo Mode.

This has a few practical consequences for mods:

• Prefer temporary runtime changes for scenarios, camera tools, and gameplay effects.
• Restore any temporary changes when your extension unloads or the effect is no longer needed.

Quality settings

PostFX availability depends on graphics settings. Lower presets can disable or reduce SSAO, screen-space shadows, bloom, depth of field, motion blur, reflections, and other effects.

Do not build essential gameplay visibility around a subtle PostFX effect. A level should remain readable when lower graphics presets reduce or disable PostFX.

Recommended checks:

1. Author and tune on High or Ultra.
2. Check Normal for typical gameplay.
3. Check Low and Lowest for readability.
4. Test day, dusk, night, tunnels, forests, interiors, and weather transitions.
5. Verify SDR and HDR output if the content depends on bright highlights.

Best practices

• Use PostFX after lighting, exposure, and tone mapping are already in a good state.
• Keep color grading subtle enough for gameplay.
• Avoid using bloom as the only way to communicate that a light is bright.
• Avoid heavy depth of field or motion blur during normal driving.
• Keep SSAO and screen-space shadows moderate so they ground objects without dirtying the image.
• Prefer color ramps for shareable looks.
• Prefer Lua runtime tuning for temporary camera, scenario, or level behavior.
• Treat custom shader effects as advanced and version-sensitive.

Related pages

• Physically Based Lighting - physical values before PostFX.
• Auto Exposure - exposure and local exposure behavior.
• Tone Mapping and HDR - final image mapping and HDR output.
• Lighting Quality - how graphics presets affect PostFX.
• Reflections - reflection settings that interact with the final image.
• Atmosphere and lighting - level workflow for time of day, fog, local lights, and PostFX.
• Photomode - custom color-ramp filters.