mtr files define a material which can be referenced from within models/ mdl files. There are two ways to reference an mtr file:

materialname myMaterialFile

or

bitmap myMaterialFile

The latter enables using materials with existing textures and models. If an mtr file is present it takes precedence over image textures - be it dds, plt or dds.

Shaders

Defining shaders is optional. If omitted, a default shader will be picked depending on content type.

// Specifies a custom vertex shader: vsMyVertexShader.shd
customshaderVS vsMyVertexShader   

// Specifies a custom fragment shader: fsMyFragmentShader.shd
customshaderFS fsMyFragmentShader  

Renderhint

Specifying a renderhint in the material file will instruct the game to handle the associated content in a certain way. Currently, only two renderhint tokens are supported, which have identical function and can be used interchangeably : "NormalAndSpecMapped" and "NormalTangents". Specifying either of these will make the game generate vertex tangent and handedness information (provided that the associated model is not already compiled), as well as picking a shader variant with normal mapping if no custom shader is specified.

renderhint NormalAndSpecMapped

The renderhint can also be added directly to a MDL file.

Textures

Texture definitions are optional. Any texture defined in the mtr file takes precedence over the one in the model/ mdl file. Up to 11 textures are supported: texture0 - texture10 (numbering doesn't need to be continuous). Specifying a texture makes it available in the shaders in the corresponding uniform sampler (texUnit*).

// Binds a texture to texUnit0 in the fragment shader. Overrides bitmap/texture0 in the model.
texture0 myFirstTexture

// Binds a texture to texUnit1 in the fragment shader. Overrides texture1 in the model.
texture1 mySecondTexture

Parameters

Optional definitions of parameters, which will be passed to the shader.

// Creates a float parameter that will be bound to a shader uniform of the same name (if it exists).
parameter float fModulator 0.5

// Creates an integer parameter that will be bound to a shader uniform of the same name.
parameter int iCount 2

// Creates a 4-float parameter that will be bound to a shader uniform of the same name. 
// Float parameters may have up to 4 dimensions (not supported for int)
parameter float vDiffuse 0.8 1.0 0.65 1.0  

Examples

node trimesh a01_planeA
  parent plc_a01
  ...
  bitmap ttr01_grass02           # Old style texture reference, overwritten in mtr
  texture1 null                  # texture will be overwritten in mtr
  texture2 null					 # texture will be overwritten in mtr
  renderhint NormalAndSpecMapped # Enables normal and specular mapping
  materialname testmat           # Reference to mtr file
  ...
endnode

// textures0 overwrites bitmap or texture0 parameter in mdl
texture0 testtx
// Used by normal and spec mapping shaders
texture1 testtx_n
texture2 testtx_s

Roughness, Heightmaps and Illumination are supported as well.  An mtr file can be defined in the mtr as such

renderhint NormalAndSpecMapped
texture0 * (Diffuse)
texture1 *_n (Normal)
texture2 *_s (Specular)
texture3 *_r (Roughness)
texture4 *_h (Height)
texture5 *_i (Illumination)