VTEX (Valve Texture Tool)

Overview

Vtex, or Valve Texture Tool, is the standard application used to create VTF texture files from TGA bitmap files for use in the Source engine. It is located in the /Steam/SteamApps/username/sourcesdk/bin/ folder. Vtex can be used with "drag-and-drop" in Windows to easily create .VTF files, as described in Creating Materials. Vtex can also be used as a command-line tool.

Using Vtex on the command-line

The Vtex application can also be executed via the a command prompt to use advanced features. You can provide additional parameters to create a basic .VMT when the texture is compiled, as well as other options.

The syntax for vtex.exe is as follows:

vtex [-quiet] [-nopause] [-mkdir] [-shader ShaderName] [-vmtparam Param Value] texture1.tga texture2.tga ...

Basic Vtex usage

The Windows environment variable "%sourcesdk%" can be utilized to locate vtex.exe easily in a command-line statement. This variable contains the location of the Source SDK installation directory.

For example, to compile a Half-Life 2 material called "sample_material.tga" in the directory "sourcesdk_content/hl2/materialsrc/metal", you would open a command prompt, change to the directory to "sourcesdk_content/hl2/materialsrc/metal" and type this at the command-line:

"%sourcesdk%\bin\vtex" sample_material.tga

The compiled .VTF file would be compiled to this folder (assuming you had set Half-Life 2 as your current game directory):

SteamApps\username\half-life 2\hl2\materials\metal

Note:It is very important that you set the Current Game in either the SDK Launcher or VConfig to the correct game directory before you open a command prompt to compile textures. Changing the Current Game will not affect any command prompt windows that are already open. This is due to how Windows uses environment variables.

Vtex commands

-mkdir

You can add the -mkdir command to vtex, and it will add the destination directory if it does not exist. For example, if you had a .TGA at /sourcesdk_content/hl2/materialsrc/sample/sample_material.tga you would type this at the command-line:

"%sourcesdk%\bin\vtex" -mkdir sample_material.tga

This would create a new directory called "sample" in your Half-Life 2/hl2/materials directory, if it didn't already exist, and then place the compiled .VTF file in that new location. If the directory already exists, the -mkdir parameter is ignored.

-shader

You can use the -shader <shadername> command to have Vtex create a .VMT for the new material with the shader specified. For example, to create a basic LightmappedGeneric material, use the -shader command like this:

"%sourcesdk%\bin\vtex" -shader LightmappedGeneric sample_material.tga

This would compile the material sample_material.vtf in half-life 2/hl2/materials/metal as well as create a new material file sample_material.vmt in the same location, using the LightmappedGeneric shader, like this:

"LightmappedGeneric"
{
	"$baseTexture" "sample/lightmappedgeneric"
}

-vmtparam

You can use the -vmtparam <parameter> <value> command to additional material parameters to the created .VMT file. If a .VMT already exists in the same location, any new parameters will not be added. For example, to make a material translucent, you would type the following:

"%sourcesdk%\bin\vtex" -shader LightmappedGeneric -vmtparam $translucent 1 sample_material.tga

Which would create the following sample_material.vmt:

"LightmappedGeneric"
{
	"$baseTexture" "sample/lightmappedgeneric"
	"$translucent" 1
}

You can add multiple -vmtparam statements in the same Vtex command, like this:

"%sourcesdk%\bin\vtex" -shader LightmappedGeneric -vmtparam "$bumpmap" "sdk/bumpspecular_normal" -vmtparam "$envmap" "env_cubemap" sample_material.tga

This would create the following sample_material.vmt specifying parameters for a bumpmapped specular material:

 "LightmappedGeneric"
 {
 	"$baseTexture" "sample/sample_material"
 	"$bumpmap" "sdk/bumpspecular_normal"
 	"$envmap" "env_cubemap"
 }

-quiet

When added, this commands will cause Vtex to do its work without producing any output to the console and will not pause when finished.

-nopause

Removes the "Hit a key to continue" message that appears when Vtex has finished working.

Wildcards

Command-line wildcards can also be used with Vtex. This command-line would compile all .TGA files in the current directory:

"%sourcesdk%\bin\vtex" *.tga

This command-line would compile all .TGA files in the current directory with names than begin with "sample":

"%sourcesdk%\bin\vtex" sample*.tga

In this case, the files "sample_metal" and "sample3" would be compiled, but not "samp_metal" or "sampl_2".

Chaining

Vtex can compile multiple materials from the same command-line. Simply add the name of each .tga after the first, like this:

"%sourcesdk%\bin\vtex" sample_material1.tga sample_material2.tga sample_material3.tga

If a .VMT is generated on the command-line using the -shader command, a unique .VMT will be created for each .TGA in the chain, all with the same parameters specified by the -shader and -vmtparam commands. If you need more individual control of the shader parameters of each .TGA, use a batch (.BAT) file to run vtex multiple times instead.

Troubleshooting

Problem figuring out outputdir

Vtex will give the following error:

Problem figuring out outputdir for <path>

As a first step, check that the texture to convert is really in the \sourcesdk_content\hl2\materialsrc folder.

If the texture is in the correct folder, the error might instead be caused by a complication with the environment variables. Primarily, this should be able to be eliminated by using VConfig and ensuring the selected mod has been run at least once. However, there are cases where this doesn’t solve the problem. One solution is to remove the instance of the VProject Environment variable. In Windows XP this can be accomplished by the following:

1. Right-click on My computer and click on Properties.
2. Select the Advanced tab.
3. Click on Environment Variables near the bottom of the window.
4. In the System variables section scroll down and highlight the line VProject.
5. Click the Delete button.
6. Click OK twice to exit.

However, this solution will create the Unable to find gameinfo.txt error instead.

Todo: Delete this non-functioning solution alternative?

Unable to find gameinfo.txt

Vtex will give the following error and instructions:

Unable to find gameinfo.txt. Solutions:

1. Read http://www.valve-erc.com/srcsdk/faq.html#NoGameDir
2. Run vconfig to specify which game you're working on.
3. Add -game <path> on the command line where <path> is the directory that gameinfo.txt is in.

This error will occur after VProject has been removed using the steps above.

Open Source SDK and change the Current Game.

Note:The link at step 1 won't provide a solution. (The page is really old.)

TGA is Bogus

Vtex will give the following error:

TGA <path> is bogus!

The texture image you are trying to convert is not recognized as a valid targa (tga) file. Make sure that it is, and that it is either 24 bit/pixel or 32 bit/pixel. (16 bit/pixel is not recognized.)

See also

• Creating Materials
• Shader Types and Parameters