From Valve Developer Community
Revision as of 05:57, 30 June 2005 by Jimius (talk | contribs)
Jump to: navigation, search

Materials are what the Source engine uses to define which textures (in .VTF file format) and shaders (functions which define how materials are rendered to the screen) are used on surfaces (models, world surfaces, sprites, etc).

Material files

Materials are defined inside of a .VMT (Valve Material) file. This is a high-level script that details how a material is to be rendered.

Let’s start by looking at an example of a .VMT file:

    // String values are quoted 
    "$basetexture" "shadertest/LightmappedTexture"
    "$envmap" "shadertest/LightmappedTexture_envmap"

    // Vector values are quoted 
    "$color" "[1 0 0]"
    // Float and integer values are *not* quoted 

    "$alpha" 0.5 
    "$nocull" 1

The first line of the .VMT file is the name of the shader to be used. The material variables for the shader are defined inside the curly braces. Note that you should not have '=' between the material variable name and its value. Also note that comment lines use '//'. Any text after the '//' on the same line will be ignored when the material is loaded.

If the shader needs to fallback to a simpler shader because it's running on a lower-end system, you can optionally specify an additional block to override material variable values specified in the original block.

Here's an example:

    "$basetexture" "shadertest/LightmappedTexture"
    "$envmap" "shadertest/LightmappedTexture_envmap"

    // If the shader falls back to shader "LightmappedGeneric_DX7",
    // then the environment map defined in this block will be used instead of the
    // one defined above. Since $basetexture isn't defined in this block,
    // the original one will be used.
        "$envmap" "shadertest/OverrideEnvMap"
    // If the shader falls back to shader "LightmappedGeneric_DX6",
    // then the base texture defined in this block will be used instead of the
    // one defined above. Since $envmap isn't defined in this block, the original
    // one will be used.
        "$basetexture" "shadertest/OverrideTexture"

See Material choices and rendering performance in Controlling Geometry Visibility and Compile Times for more information on shader fallbacks.

One other thing you'll see in the .VMT file format is the occasional variable starting with a '%'.

For example:

    $envmap" "shadertest/shadertest_envmap"
    %tooltexture" "shadertest/shadertest_envmap"

This simply means that the variable is used by tools only and won't be loaded by the engine. The only variables that need '%' are '%tooltexture", "%keywords", "%detailtype", and all of the compile variables like "%compileWater" or "%compileHint".

Compiling Source Textures

The Source engine uses .VTF (Valve Texture) files to store its texture data. These files contain not only the basic source data, but also mip-levels used for rendering the texture over varying distances. .VTF files are created from .TGA files (16, 24, or 32-bits in depth). All .TGA files must have a resolution equal to a power of 2, although the height and width can be different (i.e. 16x16, 32x32, 64x128, 128x128, 128x256, 512x512, etc.).

The tool Vtex (located in sourcesdk/bin) is used to compile .TGA files into the .VTF format. Vtex takes a .TGA file and an optional text file that describes extra parameters for compiling the texture. Using these two files then it creates a .VTF file. The .TXT file containing the parameters must share the same base name and directory as the .TGA file being compiled. For example: the test.tga file must be in the same directory as the test.txt file for the tool to link the files properly.

If a .TXT file does not exist, Vtex will automatically create an empty file with the correct name and in the correct location. The following section describes the compile parameters that can be inserted in this .TXT file.

To compile a texture, simply drag either the .TXT or .TGA file onto the sourcesdk/bin/vtex.exe icon, or supply the filename of either file as a command-line parameter to Vtex. The tool will report that it created the file and a .VTF will be created in the parallel materials sub-directory to where the source texture resided. Note: For this to work properly, you must select the correct game directory for your MOD. If the destination directory in /materials does not exist, you must create it in both locations before continuing.

For example, if you’re compiling a TGA file named "sample.tga" that resides in "sourcesdk_content/hl2/materialsrc/test/MyTexture.tga", the resulting .VTF file will be placed in "/half-life 2/hl2/materials/test/MyTexture.vtf".

Vtex .TXT file compile parameters

The parameters Vtex can parse and understand from the .TXT file are:

$nolod Do not use lower quality versions of this texture in lower DirectX versions. Used for non-world graphics such as HUD art.
$nomip Do not make mip-levels for this texture. Used for materials like skyboxes and menu backgrounds.
Do not allow the texture to wrap in the S or T coordinate space, respectively. This is most often used for sprites that are not tiled.
$skybox Used for compiling skyboxes. This assures the edges match between each facet.
$startframe (integer)
$endframe (integer)
Used for animated textures. Textures must be named as texture000, texture001, texture002, etc. The $startframe defines the beginning frame and the $endframe defines the ending frame.
$nocompress Do not use compression on this texture. Useful for textures with fine gradation (like light halos).
$nonice Do not use NICE filtering on this texture’s lower mip-levels.

Creating a .VMT file

Once the .VTF file has been created, a .VMT file must be created to actually use the texture inside of the engine.

The .VMT will define how the .VTF file is rendered to the screen. There are many shaders that can be used to render a texture. To begin with, we'll use a simple shader: LightmappedGeneric. This shader is used for world surfaces that should receive lightmaps.

The simplest definition of this shader is:

    "$basetexture" "test/MyTexture"

This will render the < .VTF file opaquely and with lightmaps applied to it. This is most generally used for textures applied to brush surfaces (like walls). With a .VTF file and .VMT file created, we can use this texture inside of Hammer on surfaces.

One of the easiest methods of creating new .VMT files is to open an existing .VMT that has similar properties to the material you are creating. Edit the contents of the file and save it with a different name to create a new material.

Using Vtex on the command-line

For advanced users, vtex.exe can also be executed and scripted from a Windows command prompt. See Using Vtex on the command-line for more information.

Summary of creating materials

Here is a brief summary of the steps necessary to create a material for the Source engine:

1. Create the source texture in the .TGA format, in 16-, 24- or 32-bit format, with a resolution equal to a power of 2. The .TGA can also contain an alpha channel to be used with effects such as transparency or specularity. 2. Save your .TGA to a directory in /materialsrc that corresponds to the directory in /materials where you want the material to appear.

For example:

To have a material compile to Half-Life 2/hl2/materials/metal place the source .TGA into the sourcesdk_content/hl2/materialsrc/metal directory.

If the destination directory in /materials does not exist, you must create it in both locations before continuing.

3. Create a .TXT with any compile parameters in the same location, and name it the same as the source .TGA, but with the .TXT extension. If you don't need to add any compile parameters, skip this step, and the .TXT file will automatically be created for you in the next

4. Compile the .VTF file by dragging the .TGA file onto the vtex.exe icon in the /sourcesdk/bin directory. The .VTF file will be compiled to the target directory in /materials inside the current game directory. For advanced users, Vtex can also be run from a command prompt.

5. Create a .VMT file with a reference to the .VTF you've created.

6. Launch the Hammer editor and check that the new material works properly.