Templates

Templates

Templates provide away to avoid repetitive copy and paste of declarations such as materials and sound shaders. Templates are defined in the templates folder, in files with ".template" as an extension. A template is basically a fancy way of replacing one piece of placeholder text with another.

A sample template for a material is shown below:

template material/generic {
    parameters < TextureParm, 
                 BumpBehavior = "useTemplate hasHeightMap< TextureParm, 1.0 >" >
    text {
        BumpBehavior
        diffusemap     TextureParm_d
        specularmap    TextureParm_s
    }
}

Keywords

template

First we have the keyword template. This lets the engine know that we're defining a new template. Next is the name of the template. Templates follow the same naming rules as other declarations in the engine.

parameters

Next we have the parameters block. This is a list of names that will be replaced when the template is evaluated. Think of them as placeholders for real information. Each name is separated by a comma (,) and can optionally have a default value. The whole block is enclosed in < > to make it more readable.

Default parameters allow you to specify things that aren't often changed. As soon as you specify a default value for a parameter, all parameters following it must also have defaults. If you leave off a default parameter when one is needed you will get a warning about it in the console.

If you want to override a default parameter, but don't want to specify custom values for any preceding default parameters, give them a value of "__default" to automatically use their default value.

text

The text block contains the actual text that is inserted into your declaration. Parameters that match text exactly (that is, case matters) will be replaced by the values that are passed into the template.

Terminology

Parameter - This is a named placeholder that we use to mark where we want substitute in values.

Argument - This is the value that we give to the parameter. 
               The argument is what is actually substituted into the the text.

Using Templates

Using a template to insert text into your declarations a simple process. In this example we create a material.

material textures/jrad/templateTest {
    useTemplate material/generic< "textures/sand/dry_beach_sand_footprints" >
}

When the material is loaded it will turn into this:

material textures/jrad/templateTest {
    bumpmap addnormals ( textures/sand/dry_beach_sand_footprints_local.tga, 
                         heightmap ( textures/sand/dry_beach_sand_footprints_h.tga, 1.0 ) )
    diffusemap     textures/sand/dry_beach_sand_footprints_d.tga
    specularmap    textures/sand/dry_beach_sand_footprints_s.tga
}

Ignore for the moment where the bumpmap line came from. You'll see that anywhere the first parameter "TextureParm" appeared it has been replaced by the first ( and only, in the case ) thing that we included in the useTemplate line.

All arguments should be enclosed within quotes "", even numbers. This is to ensure that the proper values are loaded into the appropriate arguments.

Including Other Templates

You might have noticed that the bumpmap line in the above shader has come from

BumpBehavior = "useTemplate hasHeightMap< TextureParm, ScaleParm >"

When the template is evaluated, all of the arguments that you pass in are first applied to all of the other arguments that you pass in. Before we start replacing text in the main body of the material we evaluate BumpBehavior with the other arguments that are passed in and end up with

useTemplate hasHeightMap< textures/sand/dry_beach_sand_footprints, 1.0 >

This is what is then used to replace text in the main body of the material.

Before we get any further, here is the definition of the template hasHeightmap

template hasHeightmap {
    parameters < TextureParm, ScaleParm >
    text {
        bumpmap addnormals ( TextureParm_local.tga, heightmap ( TextureParm_h.tga, ScaleParm ) )
    }
}

This is one of several behaviors that are available for the bumpmap stage of materials. This provides an easy way to customize the behavior of a single template in a flexible manner instead of having an excessive number of copy-pasted "almost-the-same" templates.

Commands ( Advanced )

Commands allow for iterative or conditional generation of template result strings. Commands work similar to text blocks, commands blocks can be interleaved with text blocks

text {
  bleh bleh
}
commands {
  meh meh
}
....

List of commands

Append

Just copies the text block to the template output.

append {
  -uninterpreted text block-
}

If

Evaluates the condition and evaluates commands if true

if ( condition ) {
  -commands-
}

Condition is one of the following forms

left operator right

Operator can be == or != Left and right can be either a string constant ( "string" ) or a template parameter name.