General – Shader replacements

Originally shader replacements were meant, well, for replacing shaders for existing models, but it grew further and further into much more than that, allowing to change material parameters and properties, textures, object parameters and sometimes even a bit of behaviour.

Main difference from things like [MATERIAL_ADJUSTMENT_…] for tracks or [EMISSIVE_…] for cars, shader replacements are completely static, applied once either during loading or after config change. This way, they themselves do not affect performance or waste any RAM (while dynamic [MATERIAL_ADJUSTMENT_…] is being updated each frame, for example). So for static changes, I’d highly recommend to use shader replacements.

One consequence of that difference though is that, if you change config and remove a [SHADER_REPLACEMENT_...] section, it wouldn’t restore original values.

Syntax:

[SHADER_REPLACEMENT_...]
ACTIVE = 1    ; set to 0 to disable the whole section (default value is 1)
SKINS = red?  ; list of skins to use replacement with (only for cars)

; First, targets, either materials or meshes (one thing to consider: 
; for altering material properties, each mesh in MESHES would get its own material, thus 
; increasing number of GPU calls, so it’s better to use MATERIALS where possible):
MATERIALS = tree?, texture:grass?.dds
MESHES = mesh_bush_?

; Optionally, a new shader:
SHADER = ksTree_ppshadows

; Shader can be set differently for different original shaders:
SHADER_OVERRIDE_0 = ksTree, ksGrass  ; if original is ksTree, use ksGrass instead
SHADER_OVERRIDE_... = ksPerPixelAT?, ksTree ; if original starts with “ksPerPixelAT”, use ksTree

; Material properties:
PROP_0 = ksAmbient, 0.4
PROP_1 = ksDiffuse, 0.5
PROP_... = ksEmissive, 1, 0, 0 ; as usual, you can use “...” to fill indices automatically

; Textures, set with one of this ways (here, it’s better not to use “...” to make sure key 
; would be paired with its value):
RESOURCE_0 = txDiffuse
RESOURCE_TEXTURE_0 = name_of_texture_in_kn5.dds ; TEXTURE refers to texture in original model

RESOURCE_1 = txNormal
RESOURCE_REF_1 = txDetailNM  ; REF refers to original texture in certain slot

RESOURCE_2 = txMaps
RESOURCE_COLOR_2 = 1, 1, 1 ; COLOR creates new 1×1 solid color texture

RESOURCE_3 = txDetail
RESOURCE_FILE_3 = custom.dds ; FILE refers to a texture on a disk, next to the config

FILL_MISSING_TEXTURES = 1 ; this option would automatically create missing textures, such 
                          ; as txNormal (flat) or txMaps (white), to ensure non-broken look
FORCE_POINT_SAMPLER = 1   ; forces pixel texture sampler, if you have tiny texture and you
                          ; want to make it sharp and pixelated, not blurry

; Material parameters (for details, scroll to “Different modes” section):
BLEND_MODE = ALPHA_BLEND  ; OPAQUE, ALPHA_TEST, ALPHA_BLEND, …
CULL_MODE = OFF           ; FRONT, BACK, DOUBLESIDED, …
DEPTH_MODE = NORMAL       ; NORMAL, OFF, NOWRITE, LESSEQUAL

; Shadow parameters:
CAST_SHADOWS = 1  ;* sets if mesh should cast shadows, either 0, 1 or TERRAIN:
                  ; 1 enables them constantly, TERRAIN only when the sun is low, to speed it up

SEMITRANSPARENT_SHADOWS = 1  ; for semi-transparent shadows, either 0, 1 or TEXTURE:
                             ; 1 for solid semi-transparency, TEXTURE would consider texture

; Double face shadows (although it might make shadows rendering a bit slower,
; I recommend to try it, it seems to improve shadows quite a lot by getting rid of lots of
; holes or peter-panning effect, especially for dashboards or with distance):
DOUBLE_FACE_SHADOW = 1         ; this one might — and, most likely, will — cause a lot of self-shadowing
DOUBLE_FACE_SHADOW_BIASED = 1  ; but this one is biased, so it would work nicely

; Masking pass (with it, mesh is rendered twice, first, with multiply blending mode and 
; a custom type of shader to extract solid texture color, thus colorizing stuff behind it
; for proper colored glass look):
EXTRA_MASK_PASS = 1              ;* enables masking pass
EXTRA_MASK_PASS_COLOR = 0, 0, 0  ;* optional color offset, RGB, can be either positive or negative values
EXTRA_MASK_PASS_OPACITY = 2      ;* optional opacity adjustment for that colored glass pass

; Other mesh parameters:
IS_TRANSPARENT = 1  ;* for that IsTransparent flag, to make sure mesh would be rendered last
LAYER = 0           ;* mesh layer, which is also a minimum detail level mesh would be rendered at
LOD_IN = 0          ;* LOD in distance (mesh will be hidden if distance is lower), in meters
LOD_OUT = 500       ;* LOD out distance (mesh will be hidden if distance is bigger), in meters

DISABLE_FAR_PLANE_CLIPPING = 1  ;* when checking visibility against camera frustum, skip far plane, required
                                ; for distant geometry (with its custom shader) to work

; * — per-object tweaks, those will not create new materials if you’re using MESHES and nothing but them.

Different modes:

Blend modes (BLEND_MODE = …):

• OPAQUE: regular opaque mode;
• ALPHA_TEST: regular alpha test;
• ALPHA_BLEND: regular alpha blend;
• ADD: additive mode, might work well for glowing areas (just make sure to set ksDiffuse and ksAmbient to zero and rely only on ksEmissive);
• MULTIPLY: multiply mode just in case (again, use only ksEmissive, and also don’t forget to set extFixedEmissive to 1 to make sure surface would have constant color; for more info about that, proceed to “New parameters” section);
• TRANSPARENT_AS_BLACK: works similar to alpha blend, but transparent surfaces instead of being transparent are black (used by extended config for Ruf Yellowbird to fix its grid at the back which doesn’t have stuff modelled behind it, maybe would be useful somewhere else);

Keep in mind, opaque and alpha test ones are the fastest, others slow things down. All but OPAQUE, ALPHA_TEST and TRANSPARENT_AS_BLACK might need transparency flag for the mesh (but only if you can’t move all the meshes that could be behind it above it in rendering queue, otherwise, please, avoid using transparency flag to both save performance and improve visual quality, as usual).

Cull modes (CULL_MODE = …):

• FRONT: regular mode, culling back side;
• BACK: show back side and hide front side;
• WIREFRAME: show wireframe;
• WIREFRAME_AA: show antialiased wireframe (very slow);
• DOUBLESIDED, NONE or OFF: show both sides.

Double sided mode will affect performance negatively by increasing surface to shade.

Depth modes (DEPTH_MODE = …):

• NORMAL: normal distance-to-camera-based occlusion mode;
• OFF: mesh can’t be occluded or wouldn’t occlude anything, if it’s rendered last, it would show on top, if it’s rendered first, everything would be drawn over it;
• NOWRITE: mesh can be occluded by others, but it itself wouldn’t occlude anything;
• LESSEQUAL: mesh can occlude other meshes if they’re in exactly the same spot (replacing regular < in “new distance to camera < old distance to camera” by ≤);
• LESSEQUAL_NOWRITE: same as NOWRITE, but with ≤.

I suspect LESSEQUAL might be perfect for stickers on cars added with a second layer, as it wouldn’t require any offset for them to work properly.

Colors for filling missing textures:

• txDiffuse: white;
• txMaps: white;
• txDetail: white;
• txNormal: flat normal (127, 127, 255);
• txNormalBlur: flat normal (127, 127, 255);
• txNormalDetail: flat normal (127, 127, 255);
• txNormalR: flat normal (127, 127, 255);
• txNormalG: flat normal (127, 127, 255);
• txNormalB: flat normal (127, 127, 255);
• txNormalA: flat normal (127, 127, 255).