Material Script .MTL

by Christoph Kubisch

Content

Definition

A material consists of a Shader (the way textures are combined) and texture/color information, it also allows to animate certain sequences of colors or textures and there are also modifiers to animate parameters automatically.

In general a material is loaded whenever you directly apply it to a rendered surface. But it can also be used as "hi-detail" version of a general texture. That means the application will look for the material with same name first, if no material available it will just use the texture.

A material is always bound to a single texture.

The header is necessary
current layout version:
luxinia_Material_v110

Syntax

All commands are case sensitive and closed by ; or "newline". A keyword and its arguments may not span multiple lines.
<id> ranges from 0 to 7
<sid> ranges from 0 to 3
<vector4> is (float,float,float,float)
<bool> is 1 = true, 0 = false

Branching

You can do branching with following commands. Enclose the branches in curly brackets { }

The condition string can be set from luxinia API with resource.condition, or it may be part of a "define" in the Cg Compiler string.
You can also negate a statement with !<condition string>.
Following conditions are automatically set if applicable:

Be aware that the parser is not fully rock solid, so at best use COMMAND{<newline> <what><newline> }<newline> , when problems occur.

Annotations & Comments

You can add annotations anywhere in the file and later query them after load. Anything between the two will become part of the annotation, so use with caution.

// comment until lineend

// multi-line annotation

<<_ "A"    
test = a * b
// this will be part of annotation as well
blahblubb
_>>

/* block commenting ...
<<_ "B"; min=25,max=90 _>>;    
//inlined annotation but ignored, due to active block comment
*/

C-style comments with // and /*...*/ may not start within command & keywords. So start comments always after ; in a line that contains command words.

Content


Example

luxinia_Material_v110
// this is a comment
Shader{
    SHD "shaders/simple.shd";
    rfalpha (0.5);
}

Color:0{
    IF:BLAH{
        RGBA (1.0,1.0,0.0,1.0);
    }
    ELSE{
        RGBA (0.0,0.0,1.0,1.0);
    }
    /*    blockcomment
        ...
    */
}
Texture:0{
    TEXALPHA "textures/blah/foo.tga";
}

Texture:1{
    frames    5;    delay    20;    loop 3;
    TEX "textures/blah/anim01.tga";
    TEX "textures/blah/anim02.tga";
    TEX "textures/blah/anim03.tga";
    TEX "textures/blah/anim04.tga";
    TEX "textures/blah/anim05.tga";
}

Texture:2{
    TEX "blubb.jpg";
    texscale (2,2,1);
} 

Content


Stages

Shader:<sid>

if no <sid> is passed 0 will be used
<sid> = 0 is the default shader, it is used most time
<sid> 1,2,3 can be enabled for use with l3dview.shaderstage from within your gamecode

can only affect values set in DrawPass, not those in RenderFlag.

Color:<id>

Texture:<id>

Content

Commands

After the stage specific commands there is multiple possibilities to change the stage, following functions are optional.

texture functions:

all floats are in texture size: 1.0 = full length/width of a texture
if any texmatrix command is called texscale,texrotate... commands will show no effect

Sequence functions:

Additionally to the mandatory you can specify these

Content

Modifiers

Modifiers are applied to the next function that takes the specified arguments (float). If the next function does not take such arguments the modifier will be ignored.
Modifiers will be interpolated or not as by user request. Some values are changed every frame, others are only "looked at" when used, the modifiers will interpolate accordingly.
Be careful and do not use too much of them. Modifiers are not allowed for sequence items.

floatmod "<name>" <type> <delay int> (<value float>) <cap uint> <arg uint>;
to modify a value over time

Notes:

ZIGZAG is linearly pending between -1 and 1 /\/\/\
Be aware an ADD on a unclamped source can never be made to stop, only by turning all modifiers of the stage off.
If source value is clamped values above/below will be ignored and maximum/minimum used.

Content


Controllables

They can be accessed via matobject class in code and can be made unique per object instance using this material.
control will override floatmods

control "<name>" <arg uint> <length uint>;

Content

Further Examples

Color:0{
    floatmod "test" ZIGZAG 500 (-1.0) 1 3;
    RGBA (1.0,1.0,1.0,1.0);
}

Alpha value changes starting from 0 to 1 to 0.. linearly every 250ms 1 is reached because 500 would be for a full cycle but we flip values if below 0 hence double frequency

Color:0{
    frames:    3;    delay:    2000;    loop: 255;
    RGBA (1.0,0.0,0.0,1.0);
    RGBA (1.0,1.0,0.0,1.0);
    RGBA (0.0,1.0,0.0,1.0);
    wait 30000;
    reverse 1;
}

this would result into a traffic light effect, 30 seconds of leadfoot action likely even a bit more if taking the 2seconds of yellow phase ;)

Texture:0{
    TEX "textures/foo/blubb.jpg";
    floatmod    "shifter" ADD 1000 (0.5) 0 0;
    texmove        (0.0,0.0,0.0);
}

Here we make a scrolling texture which is moved by half of it in a second along its X axis (sideways).

Content


History

1st Draft 24.2.2005:
Shaders were split into "shaders" and material. mostly a pure branching of functionality

2nd Draft 11.5.2005:
rotation is 3d now

3rd Draft 21.5.2005:
added tile-based texturing

4th Draft 4.6.2005:
added texcenter function to offset the origin for the other operations

5th Draft 15.6.2005:
controllables are added

6th Draft 28.12.2005:
USER Textures added

7th Draft 2.12.2005:
multiple shaders added

8th Draft 27.5.2006:
added .dds support

9th Draft 28.7.2006:
texture clamping

10th Draft 10.8.2006:
added "preprocessor" branching

11th Draft 2.9.2006:
removed sky/cloudmatrix

12th Draft 19.12.2006:
controllabes now can have an optional length parameter texmatrixcolum commands added

13th Draft 9.4.2007:
removed sunscreenmatrix, became part of materialobject features added texgenplane commads

14th Draft 26.5.2007:
added pass identifier for multiple instances of same parameter in shaders

15th Draft 8.9.2007:
controllables now support, shader parameter arrays

16th Draft 9.9.2007:
texcontrol added, to allow changing certain textures at runtime

17th Draft 24.1.2008:
proper block commenting with #{ ... #}

18th Draft 23.4.2008:
commenting now in C-Style, along with raised version number // and /* ... */

19th Draft 18.5.2008:
annotation system added

20th Draft 24.9.2008:
rfalpha added, alpha removed (left deprecated)

Content