Editing Darkplaces material system/Introduction

{{navigation | Darkplaces material system | p= | n=Key Concepts}}
= Introduction =

Darkplaces material system is created to put more direct control over the surfaces qualities of textures into the hands of designers and artists. 

=== What is a Material? ===
Materials are short text scripts that define the properties of a surface as it appears and functions in a game world (or compatible editing tool). By convention, the documents that contain these scripts usually has the same name as the texture set which contains the textures being modified (e.g; textures_inn, models_mapobjects_crypt, etc,). Several specific script documents have also been created to handle special cases, like liquids, environments and special effects.

For Darkplaces, material scripts are located in 'Path_To_The_Game/gamedir/scripts'.

A Darkplaces material file consists of a series of surface attribute and rendering instructions formatted within braces ("{" and "}"). Below you can see a simple example of syntax and format for a single process, including the [[Q3map | Q3MAP]] keywords or "Surface Parameters", which follow the first bracket and a single bracketed "stage":

 <font color=green>// material definition</font>
 '''textures/crypt/stone'''
 {
    <font color=green>// parameters</font>
    <font color=blue>qer_editorImage</font> '''radiant/textures/crypt/stone'''
    <font color=blue>q3map_textureImage</font> '''radiant/textures/crypt/stone'''
    <font color=blue>dpglossexponentmod</font> 0.5
    <font color=blue>surfaceparm</font> '''stone'''
    <font color=green>// base stage</font>
    {
        <font color=blue>map</font> '''textures/crypt/stone''' <font color=green>// engine will search fo textures/mymaterial.tga, textures/mymaterial.jpeg</font>
    }
    <font color=green>// lighting stage</font>
    {
        <font color=blue>map</font> '''$lightmap'''
    }
 }

=== Material names & Conventions ===
The first line is the material name. Material names can be up to 63 characters long. The names are often a mirror of a pathname to a .tga file without the extension or basedir (/Blood Omnicide/kain in our case), but they do not need to be.

Materials that are only going to be referenced by the game code, not modeling tools, often are just a single world, like "collision" or "dpbihclip".

Materials that are used on characters or other polygon models need to mirror a .tga file, which allows the modelers to build with normal textures, then have the special effects show up when the model is loaded into the game.

Materials that are placed on surfaces in the map editor commonly mirror a .tga file, but the "qer_editorimage" material parameter can force the editor to use an arbitrary image for display.

Material pathnames have a case sensitivity issue - on windows, they aren't case sensitive, but on unix they are. Try to always use lowercase for filenames, and always use forward slashes "/" for directory separators.

==== Material scripts Formatting ====

In order to get materials to be easily readable and editable it is recommended to format all material scripts like this template:

 materialname
 {
     &lt;Editor Specific Keywords&gt;
 
     &lt;Q3Map2 Specific Keywords&gt;
     &lt;General Keywords&gt;
     &lt;Engine Specific Keywords&gt;
     {
          &lt;Stage Keywords&gt;
     }
 }

=== Inspired by Quake 3 but different ===
Quake 3 shader scripts was an inspiration for darkplaces material system and visual look of material scripts is very very close to quake 3. So if you are familiar with Id Tech 3 [[Shader | shaders]] system, you will be right home with material script syntax. Therefore Darkplaces material system was written independently and there is some serious differences:

==== Realtime lighting ====
Any shader keywords that is not compatible with realtime lighting was removed. Other ones have sligtly changed behavior.

Aiming to realtime lighting changes the way stages working. Darkplaces material render pipeline can have 1 to 3 fixed usage stages:
* No draw: 0 stages
* Unlit texture: 1 stage
* Lit texture: 2 stages
* Lit texture with terrain blending: 3 stages
All other Id Tech 3 stage configuration such as skies are not supported.

'''Design Notes:''' To simulate multilayer materials, should make several copies of surface with different material atatched (for map surfaces can use Q3map2's cloneShader keyword)

==== New keywords ====
Darkplaces introduces many of it's own keywords that not exist in Id Tech 3.

==== Q3 Texture = Darkplaces skinframe ====
Id tech 3 only need color info for texture. Darkplaces engine using normalmap, specularity map, glow texture and other textures that store additional info. All that texture files toggether (color + normalmap + glossmap + glow etc.) forms a skinframe. 
Read more at [[Texture]] article.

==== Different speed costs ====
Darkplaces's engine rendering pipeline is very different from Id Tech 3. By using pixel and vertex shaders, it introduces new speed cost parameters that was not exist in Idtech 3:
* shader instructions - amount of vertex and pixel shader instructions generated for particular material (depends of effects used)
* texture lookups - amount of texture lookups in pixel shader, additional textures in a skinframe, parallax mapping increase amount of texture lookups
* use of VBO - non-animated models render faster with VBO, some shader keywords (such as tcMod turbulent, deformVertexes) disables VBO 
* use of Lighting - realtime light is slower on blended (add more draws of surface, one per light) or offset mapped surfaces (offset mapping is processed again for each light) 

==== Material is 'Shader' ====
Since Darkplaces uses tools with Id Tech 3 roots, materials is often spelled as 'shaders' there. To not be confused, this terms are identical in q3 tools:
* Shader = Material 
* Shader name = Surface shader = Material name = Surface material
* Shader script = Material script
* Shader keywords = Material keywords
* etc.

=== Material Types ===
The keywords that affect materials are divided into three classes. The first class of keywords are global parameters. Some global parameters ( "surfaceparms" And all "q3map_" keywords) are processed by [[Q3Map2 | Q3MAP2]] and change physical attributes of the surface that uses the material. These attributes can affect the player. To see changes in these parameters one must re-compile the [[MAP | map]].

Second class are keywords parsed by engine server part (surfaceparms, some other keywords). They are changes physical properties of surface and can affact gameplay.

The remaining global keywords, and all Stage Specific Keywords are processed by the renderer. They are appearance changes only and have no effect on game play or game mechanics. Changes to any of these attributes will take effect as soon as the game goes to another level or vid_restarts (type command vid_restart in the game [[Console | console]]).

Material keywords are not case sensitive.

'''IMPORTANT NOTE''': some of the material commands may be order dependent, so it's good practice to place all global material commands (keywords defined in this section) at the very beginning of the material and to place material stages at the end (see various examples).

{{navigation | Darkplaces material system | p= | n=Key Concepts}}