====== The Materials (cmat files) Manual ======

Cafu materials are defined in //material script files//, which in turn are simple ASCII text files with file name suffix ''.cmat''. This page describes how such "cmat scripts" can be written, their syntax and semantics.


====== Overview ======

First of all, here is a simple example for a material definition script. It was taken from the ''Cafu-9.06/Games/DeathMatch/Materials/Kai.cmat'' file, which also contains several other, very similar material definitions:
<code>
    Textures/Kai/3r_metpan01        // Material definitions start with the material name.
    {
        diffusemap  Textures/Kai/3r_metpan01_diff.png     // This line says which texture is used as diffuse-map.
        normalmap   Textures/Kai/3r_metpan01_norm.png
        specularmap Textures/Kai/3r_metpan01_spec.png
        lightmap    $lightmap
    }
</code>

Before we dig into the details about keywords and structure of such material definitions, here are some general properties of cmat files:
  * cmat files are simple ASCII text files, containing material definition scripts. Their file name ends with ''.cmat''.
  * All statements in such files are //case-sensitive//. That means that ''text'' and ''Text'' are //not// the same. This is also true for filenames, like the ''Textures/Kai/3r_metpan01_diff.png'' filename above, because some operating systems like Linux have a case-sensitive file-system.
  * C++ style comments are allowed in material scripts:  ''%%//%% This is a comment.''
  * The cmat files for MOD "MyMOD" are all stored in the ''Cafu-9.06/Games/MyMOD/Materials/'' directory and its subdirectories. This is necessary because the Cafu engine automatically scans this directory for material scripts whenever MOD "MyMOD" is run.
  * Tokens in cmat files are separated by white-space and these individual characters: ''( { [ ] } ) ,''
  * Quoted tokens are recognized. That is, everything between two ''%%"..."%%'' is considered as one statement, even if white-space or one of the above characters is inside it. That means, if for example you //really// want to have a material name like ''my(new and cool)material'', then you have to enclose it in quotation marks like this: ''%%"my(new and cool)material"%%'' in order to account for both the white-space and the brackets. Using quotation marks is not recommended, though! They're mostly useful if somebody created textures with weird file names like for example ''%%"{_SomeFile.bmp"%%''. Write ''MyNewAndCoolMaterial'' or ''My/New/And/Cool/Material'' or something similar for your material names instead.

Material definitions always start with the **material name**. In the example above, that's ''Textures/Kai/3r_metpan01''. You can name materials almost anything you like. If you want to use white-space, commas or brackets in their name, you'll have to put the name into quotation marks as mentioned above. However, it is important that the name is //unique//. If the same material name appears again in any other cmat file of the same MOD, the engine will use only the first occurance, so the chances are 50:50 that your material wins over the other.
Most materials that come with Cafu have a filename that roughly resembles the name of its texture image files. That is often a helpful hint for conveniently working with the material, but by no means a requirement.

The **body** of the material definition is enclosed in a pair of ''{ ... }''.
In many cases, it will only contain a few texture map specification statements like in the example above.