Shader authoring/Quick Start

High Level Concepts

The two major pieces of code that have to be written to create a new shader are the HLSL code and the C++ code:

• HLSL code is compiled into files that are put under a mod directory's shaders directory. The specifics of HLSL are described in the DirectX docs here.
• The C++ code is compiled into a "shader DLL" that fits the pattern game_shader_dx*.dll or game_shader_generic*.dll. The shader DLL goes in the mod's bin directory (the same place where the client.dll and server.dll goes). The C++ code describes the high-level operation of the shader to the Source Engine. It tells the engine things like:
  • Which textures the shader wants to use (texture names usually come from the .VMT [material] file).
  • How many rendering passes the shader will use.
  • Which HLSL code the shader will use.
  • Which parameters to pass into the HLSL code from the material file.
  • What shader to fallback to if the user's system can't support the shader.

Every shader has one C++ class and one or more HLSL files that it uses to render.

Additionally certain types of effects, such as full screen postprocessing effects, may require a certain amount of C++ code to be written in the general game .dll to setup the texture and render it at the appropriate times.

Quick Start - Sample Shaders

Note:As of the Source SDK update on 9/14/2006 the sdkshaders that were shipped previously have been replaced by a subset of our production shaders located in the src\materialsystem\stdshaders directory under the mod's root dir.

The Source SDK ships with some of our production shaders that can be copied or modified to use in your own mod. To compile them and use them in a game read the following instructions:

1. Make sure that you have installed the Microsoft Direct X 9 SDK on your machine as well as some flavor of Perl. In addition, make sure that you have followed all of the setup instructions in Introduction, including setting your path and fixing the outdated files runvmpi.pl and common_fxc.h. You can verify that the folders containing perl.exe, nmake.exe and fxc.exe are included in your "path" environmental variable by entering path into a command line. This is a one-time step and will allow you to update this third-party software independent of a Source SDK release.

2. Install a copy of the source code by running the Create a Mod from the SDK launcher. If the latest version of the source code is already installed, this step can be skipped.

Note:In this document, we refer to the mod's source directory as C:\MyMod\src and the mod's game directory as C:\Steam\steamapps\SourceMods\MyMod (replace them as appropriate).

3. Open a Windows command prompt (enter cmd in the start menu 'run' dialogue, change to the C:\MyMod\src\materialsystem\stdshaders directory with the cd command. Then type:

buildsdkshaders.bat

This will compile the DirectX 8 and 9 sample HLSL code and copy the resulting files into a directory called shaders in the specified mod game directory.

4. If you wish to build a DirectX 8 shader DLL open stdshader_dx8-2003.vcproj in Visual Studio 2003 or stdshader_dx8-2005.vcproj in Visual Studio 2005 and build it. This will build the C++ part of each shader into a DLL and it will automatically copy the DLL into the game's bin directory (where the client.dll and server.dll are stored).

Note:If this is the first time that you are building this project you will need to delete the 'd3dx9.lib' library from the project and add it from the proper location depending on the location of your DirectX SDK installation. This is an annoying step, but we decided it would be best not to distribute DirectX binaries anymore since they are freely available and may be updated independent of the Source SDK.

Build the solution and verify that game_shader_dx8.dll is now in your game's bin directory.

5. If you wish to build a DirectX 9 shader DLL open stdshader_dx9-2003.vcproj in Visual Studio 2003 or stdshader_dx9-2005.vcproj in Visual Studio 2005 and build it. This will build the C++ part of each shader into a DLL and it will automatically copy the DLL into the game's bin directory (where the client.dll and server.dll are stored).

Note:If this is the first time that you are building this project you will need to delete the 'd3dx9.lib' and 'd3d9.lib' libraries from the project and add it from the proper location depending on the location of your DirectX SDK installation.

Build the solution and verify that game_shader_dx9.dll is now in your game's bin directory.

6. Now modify a material (.VMT) file to use the new shaders at the top. Something like the following:

"SDK_UnlitGeneric"
{
  "$basetexture" "Brick/brickwall003a"
  "$surfaceprop" "brick"
}

7. The SDK includes some example files that can be copied into a mod to see how to refer to the sample shaders that were just compiled. The relevant sample files are listed below:

Filename	Use
[steam]\half-life 2\hl2\maps\sdk_shader_samples.bsp	Small map that refers to the shaders
[steam]\sourcesdk_content\hl2\mapsrc\sdk_shader_samples.vmf	Map source
[steam]\half-life 2\hl2\materials\sdk\sdk_lightmap.vmt	Material sample 1
[steam]\half-life 2\hl2\materials\sdk\sdk_particle.vmt	Material sample 2

These files are automatically installed by the SDK, but they will need to be copied into the same relative locations in the mod's own folder. For example, if Steam was installed in C:\Program Files\Valve\Steam, and the mod is called MyMod, the files would have to be copied like this:

C:\Program Files\Valve\Steam\steamapps\username\half-life 2\hl2\materials\sdk\sdk_lightmap.vmt

into

C:\Program Files\Valve\Steam\steamapps\SourceMods\MyMod\materials\sdk\sdk_lightmap.vmt

Note:Using the newly compiled shaders is just like referring to any other shader. See Creating_a_Material for more information.