MTR files define a material which can be referenced from within models (MDL files) that are linked to a node on a model. They essentially can define any custom shaders and shader parameters to use, any additional texture references such as normal or specular textures, and even replace the base texture (the diffuse one) by referencing another texture file.
Loading MTR Files
There are two ways to reference an mtr file. The first method is to use the new materialname field in the MDL file, usually with a file name such as m_name.mtr, since this this removes any ambiguity and for the case of PLT textures makes it clear what MTR file is in use, due to the bugs below.
The second way is to reference it in a bitmap or texture0 field:
The latter enables using materials with existing textures and models without model edits. If an mtr file is present it takes precedence over image textures - be it DDS, PLT or TGA.
PLT and MTR Usage Note
Please note that MTR files are PLT files need to be done in a very specific way. The texture0 line in the MTR file must be omitted entirely. It cannot be null, or even the original PLT texture name, since this does some odd things around what PLT colour are chosen and can lead to colour bleeding between models.
The best bug free method is to have the bitmap (or texture0) to be the PLT texture name - mainly as a point of reference (it is actually ignored) - and materialfile line to be the material name, eg:
Then the file m_pmh0_belt003.mtr contains just this line (since it is just a normal file):
Note the omission of the texture0 line.
MTR File Format
MTR files are made up of a number of simple text settings one per line. They are outlined below. Comments can be added with two slashes (eg: "// comment" ).
A sample completed MTR file:
Defining shaders is optional. If omitted, a default shader will be picked depending on content type. See here for more about shaders.
The renderhint can also be addedfile.
Note that NormalAndSpecMapped and NormalTangents do seem to have different effects if you're directly altering a flat amount of specular or roughness set in the MTR file itself. See Shaders for an example.
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*).
As noted above texture0 should be omitted for PLT mtr files due to bugs.
Default textures are as per below if using Standard material inputs:
To have a set of texture0, texture1...texture10 lines but miss some out, use the keyword null, eg to miss off the specular and roughness map but have the height map:
Additional texture slots are available from 11 to 15 which previously had similar functionality, however they are currently unavailable for use in the MTR file using the default shaders. Each slot is now internally used for other purposes as listed below.
|Texture Slot||Current Use|
Depth Buffer [used for post processing]
|texture12||Screen Buffer Color [used for reflections and post processing]|
|texture13||Cube Environment Map|
|texture14||Flat Environment Map|
|texture15||Noise Map [used for water]|
Optional definitions of parameters, which will be passed to the shader.
See an example of passing parameters on the Standard material inputs page.
You can also set parameters on objects in NWN (so not individual tiles, but say a creature, item or placeable) for shaders with nwscript, such as with the function SetMaterialShaderUniformVec4, see Shaders for some more info on this.
The following example overrides the standard armoire placeable (plc_a01.mdl). The new placeable is a simple square and references a mtr file with three textures. The files have to be placed into the override folder:
The MDL file has these fields:
For information on PBR texture references in .mtr files, see here.
Roughness, Heightmaps and Illumination are supported as well, the fuller usually used list are as follows:
Remember: if the model uses PLT textures make sure you do not include the texture0 line at all, even if it says "texture0 null", since it can bug out the PLT loading.
Accessing Textures Within Shader Code
Each texture 0-10 comes with two uniforms accessible within shader code.
The first is texture<X>Bound where <X> is the index of the texture. If texture1Bound is not equal to 0, then a texture is available in that slot to the shader. If not, then reading that slot may instead print waste data from the object's last purpose. Errors include printing a ghost spec map from another material in the scene if a spec map is not explicitly given in the MTR file or when texture2 is set to null.
The second uniform is tex<X<Unit, again where <X> is the index of the texture. This uniform holds the Sampler2D object. Using the texture2D function, you can ask for a texel form the sampler2D object by specifying uv coordinates and an optional bias. See external link for more details.
Textures 11-15 use other names as listed below.
|Texture Slot||Availability Flag||Shader Uniform or Method|
|N/A||uniform sampler2D texFBDepth|
|N/A||uniform sampler2D texFBColor|
|texture13||texEnvCubeBound||uniform samplerCubeMap texUnitEnvCube and function SampleEnvironmentMapCube()|
|texture14||texEnvBound||uniform sampler2D texUnitEnv and function SampleEnvironmentMap()|
|texture15||texNoiseBound||uniform sampler2D texUnitNoise|