Getting Started - PrismaticFlower/shaderpatch GitHub Wiki

Getting Started with Custom Materials

Shader Patch's material system has been designed to hopefully be simple and easy to use. This guide should give you all the information you need to hit the ground running with it.

How It Works

Shader Patch doesn't actually do any edits to the games code, it uses metadata from shaders to work out when to do things and what is happening. The materials system is much the same. Shader Patch includes tools that will munge a material into a special texture, this texture isn't a texture at all and is instead all the information Shader Patch needs to override shaders.

When the game tells Direct3D to bind the texture SP recognizes this and intercepts it, changing the render state to that what the material wants. Then when the game unbinds the texture it puts everything back to normal.

Now this leads to a very important piece of information. Materials are applied by having a name matching that of a texture a model references.

So if we have a model section with a diffuse texture "amazing_bricks" and we wanted to apply a custom material to this model section we would name our material also "amazing_bricks". Make sense? If not at the end there are some example files you can download.

Install Shader Patch

You won't get very far without it, grab the newest version from here.

Install & Integrate Tools

First things first, install the tools check out this guide for how to do that and then come back!

Handle Shader Patch Loading

If you followed the integration instructions correctly you should now be getting two .lvl files output for your world/side, one for you to load when Shader Patch isn't present (or custom materials are disabled by the user) and one for you to load when Shader Patch is present.

When Shader Patch is installed it exposes a small Lua API that let's mods test for it's presence. The API can be loaded by doing the following.

ReadDataFile("shader_patch_api.script")
ScriptCB_DoFile("shader_patch_api")

These two lines will produce warnings in your bfront2.log but will not crash the game if SP is not installed. After that you can test if SP is installed and it's current version of SP is compatible with version you're developing for by doing this.

local useShaderPatch = gSP_Installed and SP_TestVersion(1, 0, 0)

gSP_Installed is a global variable that will be true when SP is installed and nil when it isn't. The function SP_TestVersion is of the form SP_TestVersion(major, minor, patch).

The first argument is the major version of SP your mod targets. The second argument is the minor version of SP your mod targets. The third argument is the patch version of SP your mod targets.

Shader Patch's releases follow the form v(major).(minor).(patch) and you should supply SP_TestVersion with the values from the release you're using.

Anyway after you've assigned useShaderPatch you can wrap ReadDataFile calls like so.

if useShaderPatch then
   -- Note the addition of 'SP\\'.
   ReadDataFile("dc:MOD\\SP\\MOD.lvl", "MOD_conquest")
else
   ReadDataFile("dc:MOD\\MOD.lvl", "MOD_conquest")
end

Your mod will now work regardless of if Shader Patch is installed, if it isn't it'll just fallback to the normal game .lvl.

Learn About All The Shader Patch Things

There are three key things you need to learn before you're all set. Links to their documentation are below, in general you should be able to skim read them and just reference back to them when you have questions.

• Materials
• Textures
• Supplied Material Types
• Effects
• Developer Screen
• Reference Maps

Have fun, feel free to ask questions and maybe if Shader Patch proves useful to you contribute to it. Improvements to this documentation would be greatly appreciated!