Part-level material switching

[al2me6]

This is a (vastly simplified) replacement for TU's shader replacement functionality.

A new top-level SHABBY_MATERIAL_DEF node is introduced. It specifies a replacement shader and any number of shader properties to be modified and contains the following items:

• name (required): a unique identifier for this material.
• displayName (optional): a human-facing name. Not used in Shabby but may be accessed by other mods depending on this mod. Defaults to name if not specified.
• updateExisting (optional): whether to apply changes to the existing material, or to create a new material from scratch. Defaults to true.
• shader (optional in update-existing mode, otherwise required): name of the shader to apply. May be a stock shader or one loaded by Shabby.
• preserveRenderQueue (optional): whether the existing render queue of the material should be preserved when its shader is replaced. Defaults to false, which will reset the render queue to the shader's default.
• One or none of each the following nodes, to specify the corresponding type of shader property to be applied. They contain any number of keys of the format _Property = value:
  • KEYWORD {}: the value is a boolean (true or false).
  • FLOAT {}
  • COLOR {}: the value is either a float color (r, g, b or r, g, b, a normalized to [0, 1]), an HTML hex color (#rgb, #rrggbb, #rgba, or #rrggbbaa), or a named Unity color.
  • VECTOR {}: the value is a Vector4. All four components must be specified.
  • TEXTURE {}: the value is a GameData-relative path to a texture file, sans extension.

There is also a new configuration under the existing SHABBY top-level node, ICON_SHADER, with the string-valued keys shader and iconShader. It specifies that the shader with the given name is to be substituted when used in an icon prefab. Without this configuration, all custom shaders will be replaced by stock code with KSP/ScreenSpaceMask in icon prefabs and thus editor part icons.

Material replacements are applied in PARTs using the SHABBY_MATERIAL_REPLACE node. It contains the following items:

• materialDef (required): the unique identifier of the material definition to apply.
• Optionally, exactly one of the following. If neither are specified, the replacement is applied to the entire part.
  1. At least one targetMaterial key with a string value, specifying that the existing material with that name is to be replaced. This is the recommended workflow.
  2. At least one targetTransform key with a string value, specifying that all meshes under that transform (recursively) are to have their materials replaced.
• Optionally, any number of ignoreMesh keys with string values, specifying that the mesh with the given name is to be ignored even if it matches one of the target conditions. This applies to the mesh itself only, not any of its children.

Multiple material replacement nodes may be defined in the part, but they should apply to distinct meshes. The behavior in case of overlap is unspecified.

All of the above configurations may be modified by ModuleManager.

The material replacement is performed once per part, during prefab compilation. The result is indistinguishable from the model mu natively containing the replaced material. In particular, this is compatible with existing texture switching mods such as B9PartSwitch.

An example configuration:

SHABBY_MATERIAL_DEF
{
    name = ExampleMaterial

    shader = TU/Metallic  // This is just an example; to use a TU shader one must load it as a `.shab` bundle first.

    Texture
    {
        _MainTex = MyMod/Assets/PBRdiff
        _MetallicGlossMap = MyMod/Assets/PBRmet
        _AOMap = MyMod/Assets/PBRmet
    }

    Float
    {
        _Metal = 0.5
        _Smoothness = 0.96
    }
}

@PART[MyPart]:FOR[MyMod]
{
    SHABBY_MATERIAL_REPLACE
    {
        materialDef = ExampleMaterial
        targetTransform = transformA
        targetTransform = transformB
        excludeMesh = Flag
    }
}

Fixes #7.