Material

{{NeedUpdate}}

The Grit materials are defined in the Lua files. You can put them in their own file or interleave them with other definitions. If you re-include the Lua file, the materials will be updated.

Definition

 material "name" { properties }

name is the material name used in the mesh

The different properties are separated by commas or semicolons. Material definitions can span several lines, and spaces/tabs can be used to make them neat and tidy.

Properties

Alpha

 alpha = 0.5

Render with full alpha (scene blending, z sorting, no depth write, etc.) This is the alpha component of the diffuse colour, i.e a fixed uniform alpha for the whole material. You can also set it to 1 (or true) if you want all the alpha to come from the alpha mask of the diffuse map. Defaults to false (no alpha except alpha rejection, below).

 depthSort = true

This forces a depth sort, i.e. causes meshes in the scene to be rendered in order starting with the furthest. Defaults to true for alpha materials and false otherwise.

 alphaReject = x

The alpha reject value, any alpha values below this will be culled completely. Set to false if you don't want alpha rejection. Defaults to 0.25 (i.e. anything up to 25% alpha is culled).

 premultipliedAlpha = true

See PremultipliedAlpha. Defaults to false.

Shadow

 castShadows = false

Disable casting shadows for a particular material. Default is true.

 shadowAlphaReject = true

Whether or not to use the alpha value from the diffuse map and the alpha reject value when casting shadows. Defaults to true when alphaReject is set, false otherwise.

 shadowBias = 0.1

The bias of the shadow depth (in metres) when casting shadows. Defaults to 0. Use a higher value to avoid artefacts, but too high a value will cause shadow disconnection?.

 shadowObliqueCutOff = 30

Stop drawing shadows when the polygon is nearly in-line with the light source. A higher value gets rid of normal bending artefacts?. A lower value will have more distinctive shadows. Default is 5 degrees, maximum is 90 degrees (which will disable shadow reception on the surface entirely.

Misc

 backfaces = true

Render polies as double sided (back faces) if not specified, defaults to false. The normal is automatically inverted for the back faces.

 blendedBones = 0

The max number of bone weights per vertex used by the mesh wearing this material. If this is too large, the vertexes may be corrupted. Default 0 (i.e. no skeleton is present).

 clamp = true

Whether or not to enable clamping the texture instead of wrapping it. This avoids bleeding across the texture in mipmaps, which is often what you want for e.g. vegetation. Default is false (i.e. wrap).

 depthWrite = true

This forces depth writing to the stencil buffer. Defaults to false for alpha materials and true otherwise. Using this with alpha is necessary for GTA SA style trees and alpha LOD fading.

 stipple = false

Whether or not to use the 'stipple' effect for fading out objects or the traditional 'alpha fade'. Defaults to false unless the material is already alpha blended in which case defaults to true.

 textureAnimation={U,V}

Offset of the UV coordinates as time progresses. The U and V values are the rate of change of the UV data per second. Default is 0 for both U and V (i.e. no animation).

 textureScale ={U,V}

Used to change the tiling of textures. Values 1,1 are default, use 2 for double, etc...

Ambient

 vertexAmbient = true/false

Whether the vertex colour channel is used in the material (Shows vertex colors)

 ambientColour = {r,g,b}

The ambient colour in rgb using floats. Defaults to white, i.e., {1.0, 1.0, 1.0}. This is an additional mask on the ambient vertex colour channel (if it exists) and the ambient lighting of the scene.

Diffuse

 diffuseColour = {r,g,b}

The diffuse colour in rgb using floats. Defaults to white, i.e., {1.0, 1.0, 1.0}.

 diffuseMap = "path/name"

A diffuse texture?. Includes the path and the texture name. Masked by the diffuse colour, if given.

Normals

 normalMap = "path/name"

A normal map?. Includes the path and the texture name.

Specular Highlights

 specularColour={r,g,b}

The specular highlight colour in rgb using floats. Defaults to black if there is no specular map and white otherwise.

 gloss=value

The size of the specular highlight. (Default 10)

 specularMap="path/name"

The specular texture?. Includes the path and the texture name. Masked by the specular colour, if given.

 specularFromDiffuse = {x, y}

The specularMap will be derived from the desaturated diffuse texture by brightening it (x) and changing its contrast (y). These values can be negative to decrease brightness / contrast. Values of brightness above 1 will make the specular texture completely bright, and values below -1 will make it completely dark. A contrast of -1 greys out the texture. Values of contrast less than -1 will invert the texture.

 glossFromSpecularAlpha = true

Use the alpha channel of the specular map to control the gloss attribute. Note that white is 100% of the gloss value, and dark is always 0 gloss. So white is 'more shiney'. Defaults to false.

Translucency (sub surface scattering)

 translucencyMap = "path/name"

The translucency texture? is used to fake Subsurface scattering

.
Note: currently disabled since it required another channel in the deferred shading g-buffer.

Paint

 paintColour = 1
 paintByDiffuseAlpha = true

For paint attributes, see Paint.

Simple Examples

A white blank material:

 material "diffuse" { }

A white blank material with specular:

 material "diffuse" { diffuseColour={1,1,1}, specularColour={1,1,1}, specularity=15 }

A simple material that has a diffuse texture and a specular highlight:

 material "diffusemap" { diffuseMap="texture.dds", specularColour={1,1,1}, specularity=5 }

The most common material, diffuse texture with a normal map and a specular map:

 material "diffusespecnormalmapped" { diffuseMap="texture.dds", normalMap="texture_n.dds", specularMap="texture_s.dds"  }

A material with a diffuse map, normal map and a translucency map. The specular is derived from the diffuse.

 material "diffusenormaltranslucencynospec" {diffuseMap = "texture.dds", normalMap = "texture_n.dds", translucencyMap = "texture_SSS.dds", specularFromDiffuse = {-0.25, 0.1}, specularity=20,}

A material that blends textures:

 material "blenddiffnorm" {
     blend = {
         { diffuseMap="texture1.dds", normalMap="texture1_n.dds", specularFromDiffuse={-0.5,0.2} },
         { diffuseMap="texture2.dds", normalMap="texture2_n.dds", specularFromDiffuse={-1,0.2} },
         { diffuseMap="texture3.dds", normalMap="texture3_n.dds", specularFromDiffuse={0.0,0.5} },
         { diffuseMap="texture4.dds", normalMap="texture4_n.dds", specularFromDiffuse={0.5,0.8} },
     }
 }

See also texture blending for more info.