VMT: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
m (→‎Summary of creating materials: adding texture pixels = hammer units conversion)
m (Setting bug notice hidetested=1 param on page where the bug might not need tested in param specified)
 
(82 intermediate revisions by 36 users not shown)
Line 1: Line 1:
{{merge|Creating a Material}}
{{LanguageBar}}


A '''material''' is what the [[Source]] engine uses to define which [[texture]] (.[[VTF]]) and [[shader]] (function which defines how materials are rendered to the screen) are used on a surface ([[:Category:World Models|models]], [[Brush|world surfaces]], [[env_sprite|sprites]], etc).
{{todo|Move engine-agnostic stuff to [[material]].}}
A '''VMT''' ("Valve Material") file defines the [[material]] used by a two-dimensional surface. It contains all of the information needed for {{src|4}} to simulate the surface visually, aurally, and physically.<br>If a material is missing, it will produce the infamous Source pink and black checkered pattern. A white wireframe is not a missing material, but instead a missing [[shader]].


==Summary of creating materials==
__TOC__


[[Image:TextureFlowchart.jpg]]


The contents of a material will fall into some or all of these categories:


Here is a brief summary of the steps necessary to create a material for the Source engine:
# [[Texture]] names
# [[$surfaceprop|Physical surface]] [[Material surface properties|types]]
# [[:Category:Shaders|Shader]] [[:Category:List of Shader Parameters|parameters]]
# [[Material Map Compile Flags|Special compile properties]]
# [[Material optimization|Fallbacks]]
# [[Material Proxy|Proxies]]


# Create the source texture in the .[[TGA]] format, in 16-, 24- or 32-bit format, with dimensions equal to powers of 2. For textures that appear on large surfaces a good scale is 512 pixels for 128 [[Dimensions|Hammer-units]]. This is the default scale at which Hammer will apply textures and equals about 10 feet or about 3 meters in the game. The .TGA can also contain an [[alpha|alpha channel]] to be used with effects such as transparency or specularity.
== A simple example ==
# Save your .TGA to a directory in <code>/materialsrc</code> that corresponds to the directory in <code>/materials</code> where you want the material to appear.<br>For example:<br>To have a material compile to <code>Half-Life 2/hl2/materials/metal</code> place the source .TGA into the <code>sourcesdk_content/hl2/materialsrc/metal</code> directory.<br>If the destination directory in <code>/materials</code> does not exist, you must create it in both locations before continuing.
{{CodeBlock|<nowiki>LightmappedGeneric
# (Optional) 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 step.
# Compile a .VTF file by dragging the .TGA file onto the [[Vtex|vtex.exe]] icon in the <code>/sourcesdk/bin directory</code>. The .VTF file will be compiled to the target directory in <code>/materials</code> inside the current game directory. For advanced users, Vtex can also be run from a command prompt.
# Create a .VMT material file with a reference to the .VTF you've created.  (See [[#Creating a .VMT file|below]].)
# Launch the Hammer editor and check that the new material works properly.
 
===Scale===
The default texture scale in Hammer is <code>.25</code>. This means that 4 pixels (in an image) = 1 Hammer unit = 1 inch (in game).
 
==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.). Square images are preferred by the engine, so use them when possible. Also try to use them when it doesn't seem the best way to go.
 
The tool [[Vtex]] (located in <code>sourcesdk/bin</code>) 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 <code>sourcesdk/bin/vtex.exe</code> 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 [[The Game Directory|Game Directory]] for your MOD. If the destination directory in <code>/materials</code> does not exist, you must create it in both locations before continuing.}}
 
For example, if you’re compiling a TGA file named <code>sample.tga</code> that resides in <code>sourcesdk_content/hl2/materialsrc/test/MyTexture.tga</code>, the resulting .VTF file will be placed in <code>/half-life&nbsp;2/hl2/materials/test/MyTexture.vtf</code>.
 
==Vtex .TXT file compile parameters==
 
Extra parameters can be put into the .TXT file when you compile the texture with [[Vtex]]. Some of the parameters Vtex can parse and understand from the .TXT file are:
 
{|
| <code>nolod</code> || Do not use lower quality versions of this texture in lower DirectX versions. Used for non-world graphics such as HUD art.
|-
| <code>nomip</code> || Do not make mip-levels for this texture. Used for materials like skyboxes and menu backgrounds.
|-
| <code>clamps</code><br><code>clampt</code> || 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.
|-
| <code>skybox</code> || Used for compiling skyboxes. This assures the edges match between each facet.
|-
| <code>startframe (integer)</code><br><code>endframe (integer)</code> || Used for animated textures. Textures must be named as texture000, texture001, texture002, etc. The startframe defines the beginning frame and the <i>endframe</i> defines the ending frame.
|-
| <code>nocompress</code> || Do not use compression on this texture. Useful for textures with fine gradation (like light halos).
|-
| <code>nonice</code> || Do not use NICE filtering on this texture’s lower mip-levels.
|- <code>dxt5</code> || Use DXT5 compression instead of full compression.
|}
example usage from one of the files for the console background:
"nonice" "1"
"nolod" "1"
"nomip" "1"
 
==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. Materials are defined inside of a .VMT (Valve Material) file. This is a high-level script that details how a texture is to be rendered.
 
There are many [[shader]]s that can be used to render a texture. To begin with, we'll use a simple shader: <code>LightmappedGeneric</code>. This shader is used for world surfaces that should receive [[lightmap]]s.
 
The simplest definition of this shader is:
 
<pre>
"LightmappedGeneric"
{
{
    "$basetexture" "test/MyTexture"
$basetexture "coast/shingle_01"
}
$surfaceprop gravel
</pre>
}</nowiki>}}
''This is a very basic [[Wikipedia:Shingle beach|shingle beach]] material.''


This will render the <code>"test/MyTexture"</code> .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.
#The <code>[[LightmappedGeneric]]</code> shader is used, which means that the material is for use on surfaces with [[lightmap]]s (i.e. [[brush]]es).
#''The opening curly brace ({{Code|<nowiki>{</nowiki>}}) opens a set of parameters''
#The <code>[[$basetexture]]</code> parameter is given with <code>coast\shingle_01</code>, which is the location of a texture. This is what will be drawn on the screen.
#<code>[[$surfaceprop]]</code> gives the material the physical properties of gravel.
#''The closing curly brace ({{Code|<nowiki>}</nowiki>}}) character closes a set of parameters''


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.
It's important to remember that this material can only be used on brushes. If it needed to be used on [[model]]s, for instance, another version would need to be created using the {{code|[[VertexLitGeneric]]}} shader.


==More about .VMT files==
Most of the time switching materials from one shader to another is as simple as changing their first line, since a great number of parameters are shared between them. Some params only work with certain shaders, like [[Phong]] effects, which are only available with {{code|[[VertexLitGeneric]]}}, but unfortunately you won't encounter any critical errors if a param isn't understood by the shader. It just won't have any effect.


Let’s start by looking at an example of a .[[VMT]] file:
{{tip|If you ever need to use a space, tab, or curly brace character in a parameter value, you must wrap the whole value with "quote marks". You'll often see absolutely everything wrapped like this - save yourself some typing, as that's unnecessary.}}
{{bug|hidetested=1|Sometimes{{when}}, the first parameter defined in the VMT will fail to load. If this happens, a dummy parameter such as {{code|$bug}} can be used.}}


<pre>
== Finding materials ==
"LightmappedGeneric"
{           
    // String values are quoted
    "$basetexture" "shadertest/LightmappedTexture"
    "$envmap" "shadertest/LightmappedTexture_envmap"


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


    "$alpha" 0.5
When Valve updated all {{src|4}} games to [[SteamPipe]], all materials were moved from [[GCF]] into [[VPK]] files. Third-party games (running on {{src04|1}} - {{src09|1}}) that previously used [[GCF]] files are also having it's materials moved to depot [[VPK]] files. VPK Files work with {{gcfscape|4}} and {{vpkedit|4}}.
    "$nocull" 1
}
</pre>
 
The first line of the .VMT file is the name of the [[Shader Types and Parameters|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 <i>fallback</i> 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:
 
<pre>
"LightmappedGeneric"
{              
    "$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.
    "LightmappedGeneric_DX7"
    {
        "$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.
    "LightmappedGeneric_DX6"
    {
        "$basetexture" "shadertest/OverrideTexture"
    }
}
</pre>
 
For information on shader fallbacks, see '''Material choices and rendering performance''' in [[Controlling Geometry Visibility and Compile Times]] and [[Half-Life 2 Shader Fallbacks]].
 
One other thing you'll see in the .VMT file format is the occasional variable starting with a '%'.
 
For example:
 
<pre>
"UnlitGeneric"
{
    $envmap" "shadertest/shadertest_envmap"
    %tooltexture" "shadertest/shadertest_envmap"
}
</pre>


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 <code>'%tooltexture"</code>, <code>"%keywords"</code>, <code>"%detailtype"</code>, and all of the compile variables like <code>"%compileWater"</code> or <code>"%compileHint"</code>.
More info on SteamPipe [https://support.steampowered.com/kb_article.php?ref=7388-QPFN-2491 here]


==Using Vtex on the command-line==
=== Non-SteamPipe Games ===


For advanced users, <code>vtex.exe</code> can also be executed and scripted from a Windows command prompt. See [[Vtex]] for more information.
In non [[SteamPipe]] {{src|4}} games, Materials are stored in the {{Path|materials\}} folder of your game or mod. The best way to browse them is from {{hammer|4}}'s texture selection screen.


==See Also==
If you want to edit or view the code of Valve's material files you will first need to extract them from their [[GCF]] package with {{gcfscape|4}}. They tend to be stored in GCFs with 'materials' in their name.


* [[Shader Types and Parameters]]
== See also ==
* [[Half-Life 2 Shader Fallbacks]]
* [[Normal Maps]]
* [[Reflective Materials]]
* [[Parallax]]
* [[:Category:Third Party Tools|Third Party Tools]]


== External links ==
* [[Creating a Material]]
* Creating materials, with transparency, in [http://www.sourcemapping.org/akg/tutorials/wisePSPtrans.asp Paint Shop Pro]
* [[Notepad++ VDF languages|Notepad++ syntax highlighting for materials]]
* [[Valve Texture Format]]
* [[Shader]]
* [[:Category:List of Shader Parameters|List of Shader Parameters]]
* [[Source VMT Editor]]
* [https://github.com/Xyphos/VMTGen VMTGen]
* [http://www.therazzerapp.de/tutorials/vmt_erstellen.html German Tutorial by TheRaZZeRApp]  


[[Category:Material System]]
[[Category:Material System]]
[[Category:Tutorials]]
[[Category:Source]]
[[Category:Glossary]]
[[Category:File formats]]

Latest revision as of 07:07, 20 May 2025

English (en)Deutsch (de)Español (es)Français (fr)한국어 (ko)Русский (ru)Translate (Translate)
Todo: Move engine-agnostic stuff to material.

A VMT ("Valve Material") file defines the material used by a two-dimensional surface. It contains all of the information needed for Source Source to simulate the surface visually, aurally, and physically.
If a material is missing, it will produce the infamous Source pink and black checkered pattern. A white wireframe is not a missing material, but instead a missing shader.


The contents of a material will fall into some or all of these categories:

  1. Texture names
  2. Physical surface types
  3. Shader parameters
  4. Special compile properties
  5. Fallbacks
  6. Proxies

A simple example

LightmappedGeneric { $basetexture "coast/shingle_01" $surfaceprop gravel }

This is a very basic shingle beach material.

  1. The LightmappedGeneric shader is used, which means that the material is for use on surfaces with lightmaps (i.e. brushes).
  2. The opening curly brace ({) opens a set of parameters
  3. The $basetexture parameter is given with coast\shingle_01, which is the location of a texture. This is what will be drawn on the screen.
  4. $surfaceprop gives the material the physical properties of gravel.
  5. The closing curly brace (}) character closes a set of parameters

It's important to remember that this material can only be used on brushes. If it needed to be used on models, for instance, another version would need to be created using the VertexLitGeneric shader.

Most of the time switching materials from one shader to another is as simple as changing their first line, since a great number of parameters are shared between them. Some params only work with certain shaders, like Phong effects, which are only available with VertexLitGeneric, but unfortunately you won't encounter any critical errors if a param isn't understood by the shader. It just won't have any effect.

Tip.pngTip:If you ever need to use a space, tab, or curly brace character in a parameter value, you must wrap the whole value with "quote marks". You'll often see absolutely everything wrapped like this - save yourself some typing, as that's unnecessary.
Icon-Bug.pngBug:Sometimes[When?], the first parameter defined in the VMT will fail to load. If this happens, a dummy parameter such as $bug can be used.

Finding materials

SteamPipe

When Valve updated all Source Source games to SteamPipe, all materials were moved from GCF into VPK files. Third-party games (running on Source 2004 - Source 2009) that previously used GCF files are also having it's materials moved to depot VPK files. VPK Files work with GCFScape GCFScape and VPKEdit VPKEdit.

More info on SteamPipe here

Non-SteamPipe Games

In non SteamPipe Source Source games, Materials are stored in the 🖿materials\ folder of your game or mod. The best way to browse them is from Hammer Hammer's texture selection screen.

If you want to edit or view the code of Valve's material files you will first need to extract them from their GCF package with GCFScape GCFScape. They tend to be stored in GCFs with 'materials' in their name.

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=VMT&oldid=478760"