Shader Patch Materials - PrismaticFlower/shaderpatch GitHub Wiki
Contents
Intro
The modder experience for using custom materials was design to (hopefully) be simple, easy and painless. The following describe the features provided,
- Materials are defined using YAML.
- Materials are easily used, there is no need to edit .msh files to use a material with them.
- Materials can be applied to cloth without taking any special action.
- Using materials doesn't lock your mod into only working with Shader Patch. The material munger copies and edits munged models. This makes it trivial to munge for both the normal game and with Shader Patch. The default integration instructions go into more detail.
Material Config Files
Material config files are YAML files with the extension .mtrl. A lot of the meaning of properties in config files is ascribed by the selected material type. So a config file for one material type may have completely different properties to that of another.
Type: "pbr"
Material:
BaseColor: [1.0, 1.0, 1.0]
Metallicness: 0.0
Roughness: 1.0
AOStrength: 1.0
EmissivePower: 0.0
Textures:
AlbedoMap: "tile4b_basecolor"
NormalMap: "tile4b_normal-dx"
MetallicRoughnessMap: "tile4b_roughness"
AOMap: "tile4b_ao"
LightMap: ""
EmissiveMap: ""
Type
Selects which material type to use for the material.
Material
This section holds all properties provided by the material type.
Flags
** Deprecated as of v1.3! **
To keep using these flags you must edit your munge scripts to pass --usemtrlflags:true to material_munge.
The flags section contains builtin properties that are not controlled by the material type (the material type is not even aware of them). They provided a quick and convenient way to set material flags that control render state that the game can manage better than Shader Patch.
The state of these flags will be edited into the munged models produced by the material munger. Despite the ability to use custom materials with cloth these flags have no impact on cloth rendering.
| Flag Name | Description |
|---|---|
| Transparent | Enable or disable transparent rendering for models this material is applied to. |
| HardEdged | Enable or disable hard edged rendering for models this material is applied to. That is when drawing any fragment with alpha value below 0.5 will be discarded and (unless Flags.Transparent is also set) any value above 0.5 will be set to 1.0 |
| DoubleSided | Enable or disable double sided rendering. By default back facing triangle are culled, setting this causes triangles to drawn on both sides. |
| Unlit | Disable lighting for the material. If the material type being used doesn't support unlit materials then SP will fast fail (intentionally crash). (Inversely for any material type that only supports unlit materials not setting this will cause the same thing.) |
Textures
This section names the textures used by the material. The exact name of the keys in this section vary per material type. The textures referenced here will be referenced in the resulting REQ file of the material.
Builtin Textures
Texture can also be set to special "builtin" textures that SP provides itself and do not need to be included in a world. All builtin textures are prefixed with $ to indicate their status as builtin textures. Currently the following are provided.
| Name | Description |
|---|---|
$null_ao |
A completely white 1x1 texture that can be used when a material type requires a AO map but the material has none. |
$null_normalmap |
A 1x1 normal map that always points directly away from the surface. (Ie has the color R = 0.5, G = 0.5, B = 1.0). |
$null_detailmap |
A 1x1 detail map that doesn't add in any detail. (Ie has the color R = 0.5, G = 0.5, B = 0.5). |
Munger
In general you shouldn't have to worry about the actual tool itself and can instead focus on the material files. But if you find yourself in the need of writing a script to call it or feel the urge to invoke it directly this section contains documentation on material_munge.exe's command arguments.
| Option | Usage | Brief |
|---|---|---|
| -?, -h, --help | Display the list of arguments. | |
| --outputdir, -o | <output directory> | Path to place munged files in. |
| --sourcedir, -s | <source directory> | Path to search for input .mtrl files. |
| --mungedsourcedir, -m | <munged source directory> | Path to search for input munged files. |
| --descdir, -d | <description directory> | Add a path to search for descriptions of material types. |
| --usemtrlflags | <true|false> | Enables the usage of the old 'Flags' section in .mtrl files. |
Below is a slightly more detailed description of each argument and it's effect.
outputdir
The target directory that all munged materials will be placed in. Edited models will also be placed in this directory. If the directory doesn't exist the tool will attempt to create it, if it fails the tool exits displaying an error.
sourcedir
The source directory to search for .mtrl files in to munge. The search is recursive.
mungedsourcedir
The source directory to search for munged models to apply materials to in. A material is applied to a model when it references a texture with the same name as a material. The munged models will have various material flags stripped from to make them always be drawn in a single pass, as required by Shader Patch's material system.
descdir
Adds a path to the list of directories to look for material type descriptions in. (Multiple directories can be added by using this argument multiple times.) The extension for description files is simply .yml. The format of descriptions is specific to each version of Shader Patch and only the descriptions bundled with each specific material_munge version are guaranteed to work with it.