User Tools

Site Tools


This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
matsys:cmat_manual [2005-10-22 20:32]
Carsten Removed the sections that have been created as individual pages
matsys:cmat_manual [2013-01-07 12:07] (current)
Line 1: Line 1:
 +====== 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:​
 +    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
 +    }
 +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.