Material Scripts

From Multiverse

Particle Scripts

Syntax  •  Attributes  •  Emitters  •  Affectors

Material Scripts

Techniques  •  Texture Units  •  Passes  •  Vertex and Fragment Programs  •  Calling Vertex and Fragment Programs  •  Copying Materials

Compositor Framework

Compositor Scripts  •  Compositor Techniques  •  Compositor Target Passes  •  Compositor Passes

Shaders

Writing Custom Shaders  •  Built-in Shaders  •  Troubleshooting

Contents 1 Overview 2 Format 2.1 Name 2.2 Techniques 2.3 Passes 2.4 Texture units 2.5 Vertex and pixel shader scripts 3 Top-level material attributes 3.1 lod_distances 3.2 receive_shadows 3.3 transparency_casts_shadows 3.4 set_texture_alias

Overview

Material scripts define complex materials in a reusable script that the Client loads as needed to display a model. The Client parses files with .material extension in the asset repository.

It's important to realize that the Client does not completely load materials by this parsing process: it loads only the definition, not textures or other resources. This is because it is common to have a large library of materials, but only use a relatively small subset of them in any one scene. To load every material completely in every script would therefore cause unnecessary memory overhead.

Another important factor is that material names must be unique throughout ALL scripts in a given asset repository, since materials are identified by name.

Format

A single script may define several materials. The script format is pseudo-C++, with sections delimited by curly braces { and }. There are four sections:

• The top-level material section
• One or more technique sections
• One or more pass sections within each technique.
• Zero or more texture_unit sections within each technique.

Each section takes the form

section_name
{
   attribute1 [parameters ...] 
   attribute2 [parameters ...]  
   ...
}

Where attribute1, attribute2, and so on represent the attributes, and parameters the corresponding value or set of parameters.

Comments are indicated by starting a line with "//" (no nested form comments are allowed).

The example below illustrates the general format of a fixed-function material script that doesn't use vertex or fragment programs (see Using Vertex and Fragment Programs).

// This is a comment
material walls/funkywall1
{
    // first, preferred technique
    technique
    {
        // first pass
        pass
        {
            ambient 0.5 0.5 0.5
            diffuse 1.0 1.0 1.0
			
            // Texture unit 0
            texture_unit 
            {
                texture wibbly.jpg
                scroll_anim 0.1 0.0
                wave_xform scale sine 0.0 0.7 0.0 1.0
            }
            // Texture unit 1 (this is a multitexture pass)
            texture_unit
            {
                texture wobbly.png
                rotate_anim 0.25
                colour_op add
            }
        }
    }

    // Second technique, can be used as a fallback or LOD level
    technique
    {
        // .. and so on
    }		
}

Name

Every material in a script must have a name, defined as follows:

material name
{
...

A material name must be globally unique. It can include "/" path characters (as in the example) to logically divide up materials, and avoid duplicate names, but the Multiverse Client does not treat the name as hierarchical, just as a string.

NOTE: The colon character ":" is the delimiter for specifying material copy in the script so it can't be used as part of the material name.A material can copy from a previously defined material by using a colon :after the material name followed by the name of the reference material to copy. If the reference material can not be found then it is ignored. For more information, see Copying Materials.

Techniques

A material can be made up of many techniques. A technique is one way of achieving a particular effect. Supply more than one technique to provide fallback approaches where a graphics card does not have the ability to render the preferred technique, or where you wish to define lower level of detail versions of the material to conserve rendering power when objects are more distant.

For more information on techniques, see Techniques.

Passes

Each technique can be made up of many passes. A complete render of the object can be performed multiple times with different settings to produce composite effects. The Multiverse Client may also split the passes you have defined into many passes at runtime, if you define a pass which uses too many texture units for the card you are currently running on (it can only do this if not using a fragment program). Each pass has a number of top-level attributes such as ambient to set the amount and colour of the ambient light reflected by the material. Some of these options do not apply if you are using vertex programs.

For more information on passes, see Passes.

Texture units

Each pass can use zero or many texture units that define the texture to be used, and optionally some blending operations (which use multitexturing) and texture effects.

Vertex and pixel shader scripts

A material script can call vertex and fragment (pixel shader) programs in a pass with arguments. Declare vertext and fragment programs separately in .program scripts; see Vertex and Fragment Programs for more information. For information on how to use programs, see Using Vertex and Fragment Programs in a Pass.

Top-level material attributes

Most of the configurable parameters are in the child sections of a material script (techniques, passes, and texture_units), but the top-level section of a material definition has the following attributes:

• lod_distances
• receive_shadows
• transparency_casts_shadows
• set_texture_alias

lod_distances

This attribute controls the distances at which different Techniques can come into effect. See Techniques for a full discussion of this option.

receive_shadows

This attribute controls whether objects using this material can have shadows cast upon them.

Whether or not an object receives a shadow is the combination of a number of factors (see About Shadows for details). However this attribute makes a material opt-out of receiving shadows if required. Note that transparent materials never receive shadows so this option only affects solid materials.

Format:

 receive_shadows [ on | off ]

Default: on

transparency_casts_shadows

This attribute controls whether transparent materials can cast certain kinds of shadow. Whether or not an object receives a shadow is the combination of a number of factors (See About Shadows for details).

However this attribute makes a transparent material cast shadows, when it would otherwise not. For example, when using texture shadows, transparent materials are normally not rendered into the shadow texture because they should not block light. This flag overrides that.

Format:

 transparency_casts_shadows [ on|off ]

Default: off

set_texture_alias

This attribute associates a texture alias with a texture name. This attribute sets the textures used in texture unit states copied from another material; see Copying Materials.

Format:

 set_texture_alias alias_name texture_name