Material proxies

The Basics

Material proxies allow materials to change their rendering properties (color, alpha values, etc) using game state and scripted equations. Proxies are defined as a block of text, using key/value pairing, inside of the VMT description of a material. Proxies are available for all materials. A proxy is defined as in the following example:

"LightmappedGeneric"
{
     "$basetexture" "shadertest/LightmappedTexture"
    
     // Inside these braces are where all the proxies go 
    "Proxies" 
     { 
            // This is a sine proxy 
            "Sine" 
            { 
                   // This is the data for the sine proxy 
                   // Notice there is no '$' on the proxy variables 
                   "resultVar"    "$alpha" 
                   "sineperiod"   8 
                   "sinemin"      0 
                   "sinemax"      1 
            } 
     } 
}

The above block of text instructs the material to use the Sine material proxy to modify the alpha value of the material when rendered. The other entries define parameters for the proxy to use in its calculations. Here the sine wave has a sineperiod of 8 seconds and oscillates between a value of "0" and "1".

It is possible to define multiple proxies in one material within the Proxies section of that material's definition. If multiple proxies are defined, they are executed in a top to bottom order.

"Proxies" 
{ 
      // This is executed first 
      "A" 
      { 
             . . . 
      } 
      // This is executed second 
      "B" 
      { 
          . . . 
      } 
}

Variables

Like a standard programming language, the material proxies may declare temporary local variables to be used to store intermediate values for further use later in the proxy. Variables are declared outside of the Proxies block and have default values specified on their right-hand side.

"LightmappedGeneric" 
{ 
       "$basetexture" "shadertest/LightmappedTexture" 
       
       // A local variable for this material, defaulting to “0.5‿ 
       "$myScale" 0.5 
       "Proxies" 
       { 
            . . .
       } 
}

There is no practical limit to the number of local variables declared. Local variables may be used to store results from proxies, or to pass data into proxies as parameters. They are often employed to chain mathematic function proxies (i.e. Add, Subtract, etc) together into longer equations for rendering values.

Common Result Variables

The following values are commonly used as $resultVar variables.

$alpha	Fade value (0 = transparent, 1 = opaque)
$color	Modulation color (R,G,B) (1,1,1) = white, (0,0,0) = black
$envmapmaskscale	An amount to scale the environment map mask
$frame	Frame number of an animated texture
$envmaptint	Modulation color for the environment map
$selfillumtint	Modulation color for the self-illumination

Note:$alpha and $color values are clamped between 0 and 1.

Note:Certain variables like $color and $baseTextureOffset can be accessed like an array. "$color[0]" would access the red component of the variable.

Writing Material Proxy Implementations

Although many generic proxies are included in the client already, it will sometimes be necessary to create a custom material proxy for your MOD. To do this, code will be required on the client-side. Material proxies are descended from the IMaterialProxy interface class. The proxy has three main functions to do its work in. The first is the Init() function, defined as:

bool Init( IMaterial *pMaterial, KeyValues *pKeyValues );
 pMaterial
 Material we’re acting on

 pKeyValues
 List of key-value pairs for this material

The Init() function is called when a material is first created in a session. This function allows you to setup internal state for the material proxy, usually consisting of obtaining references to material variables for later use.

void OnBind( void *pC_BaseEntity );
 pC_BaseEntity
 Entity this material is being applied to (if any)

The OnBind() function is called every time Bind() is called on a material. This is where most of the material proxy’s work is done.

Finally, the proxy must expose its interface so that the named reference to the proxy can be linked up to the class implementation. This is done via the EXPOSE_INTERFACE macro.

EXPOSE_INTERFACE( className, interfaceName, proxyName, IMATERIAL_PROXY_INTERFACE_VERSION );

Note:See DummyProxy.cpp for an example of a simple material proxy.

Proxy List

The following proxies are already defined in the Source engine for MOD author’s use.

Proxy Name	Description	Variables
Add	Adds two variables together.	srcVar1 Name of the first source variable. srcVar2 Name of the second source variable. resultVar ( srcVar1 + srcVar2)
Multiply	Multiplies two variables together.	srcVar1 Name of the first source variable. srcVar2 Name of the second source variable. resultVar ( srcVar1 * srcVar2)
Subtract	Subtracts the second variable from the first.	srcVar1 Name of the first source variable. srcVar2 Name of the second source variable. resultVar ( srcVar1 - srcVar2)
Divide	Divides the first variable by the second.	srcVar1 Name of the first source variable. srcVar2 Name of the second source variable. resultVar ( srcVar1 / srcVar2)
Equals	Copies a variable to the result variable.	srcVar1 Name of the source variable. resultVar Set equal to srcVar1
Abs	Computes the absolute value of a variable.	srcVar1 Name of the source variable. resultVar abs( srcVar1)
Frac	Returns the fractional component of a number. Note:If a vector type variable is provided, this function will return the fractional component of each member of the array.	srcVar1 Number to find the fractional component of
Exponential	Computes ( A * e (srcVar1+B) ).	srcVar1 Name of the source variable. scale Specifies the value of A offset Specifies the value of B minVal Minimum clamping value maxVal Maximum clamping value resultVar ( A * e (srcVar1+B) )
Clamp	Clamps a variable to a specified range of values.	srcVar1 Name of the source variable. min Minimum clamping value max Maximum clamping value resultVar clamp( srcVar1, Min, Max )
LessOrEqual	Returns different values based relation of supplied variables.	srcVar1 Name of the first source variable. srcVar1 Name of the second source variable. lessEqualVar Name of material variable to copy to result if (srcVar1 <= srcVar2) greaterVar Name of material var to copy to result if (srcVar1 > srcVar2) resultVar Resulting value
Sine	Creates a sine wave.	sineperiod Period of the sine wave in seconds. sinemin Minimum value of the sine wave. sinemax Maximum value of the sine wave. timeoffset Used to start the sine wave at a different point in time resultVar Resulting value.
LinearRamp	Produces an ever increasing value.	rate Rate of increase of the value. initialValue Initial value to increase. resultVar Resulting value.
UniformNoise	Produces a noisy signal where each value is equally likely to occur	minVal Minimum value range. maxVal Maximum value range. resultVar Resulting value.
GaussianNoise	Produces a noisy signal where values are near the average.	mean The average random value. halfWidth The distance from the average at which it’s only 30% likely to occur. minVal Minimum value range (clamped). maxVal Maximum value range (clamped). resultVar Resulting value.
MatrixRotate	Creates a rotation matrix from the provided axis and angle.	axisVar Axis of rotation (x,y,z) = (0,1,2). angle Degrees of rotation around axis. resultVar Rotation matrix.
PlayerProximity	Stores the distance from the entity the material is on to the player into a variable. Note:Does not work on world surfaces.	scale An amount to scale the distance by. resultVar Resulting value.
PlayerView	Stores the dot product of the view direction + the direction from the camera to the entity the material is on. Note:Does not work on world surfaces.	scale Amount to scale the dot product by. resultVar Resulting value.
PlayerSpeed	Stores the speed of the player into a variable.	scale<i> Amount to scale the speed by. resultVar Resulting value.
PlayerPosition	Stores the player’s position into a variable. Note:Only works for vector variables like $baseTextureOffset or $color. scale An amount to scale the position by. resultVar Resulting value.
EntitySpeed	Stores the entity’s speed into a variable. Note:Does not work on world surfaces.	scale An amount to scale the speed by. resultVar Resulting value.
TextureTransform	Generates a texture transform matrix.	centerVar Name of a variable holding the center of rotation and scaling. [Optional] scaleVar Name of scale variable (2D vector). [Optional] rotateVar Name of rotation angle variable (float). [Optional] translateVar Name of the translation variable (2D vector). resultVar Resulting value.
Empty	Used to comment out proxies. Surround a bunch of proxies with the empty proxy to cause those proxies to not operate.
TextureScroll	Returns a transform matrix or vector that will translate a texture at a given angle at a given rate.	textureScrollVar Destination for the resulting transformation. textureScrollRate Rate of scroll in units per second. textureScrollAngle Angle of rotation to move along. (90 = right, 180 = left, etc)
ToggleTexture	Toggles a texture based on the frame number set by the attached entity. Note:Must be attached to an entity.	toggleTextureVar Texture to modify based on frames. toggleTextureFrameNumVar Variable used for frame number. toggleShouldWrap Whether the animation should wrap over not.
RandomEntity	A proxy that returns a random number associated with the entity the material is applied to. Can be helpful for making animated textures not all be in sync.	scale Amount to scale the random number by. resultVar Resulting value.
CurrentTime	Returns the current time as a float.	resultVar The current time.
PlayerHealth	Stores the player health (0-1) in a variable.	scale Amount to scale the health value by. resultVar Resulting value.
PlayerDamageTime	Stores the time since the player was last damaged, in a variable.	scale Amount to scale the time by. resultVar Resulting value.
MaterialModify	Sets the base texture to a value held by the entity (used for entity controlled texture animations). Note:Only works when attached to an entity.	No return value.
WaterLOD	Coordinates water LOD values between the map’s env_waterlod entity and the materials internal values.	$CHEAPWATERSTARTDISTANCE Start distance for cheap water Note:must be set outside of proxy block. $CHEAPWATERENDDISTANCE End distance for cheap water Note:must be set outside of proxy block. No return value.
BreakableSurface	Sets the base texture to a material name held by the entity (used for switching surface material on shatter) Note:Must be attached to a func_breakablesurface entity.	No return value.
ConveyorScroll	Returns the scroll parameters for a texture used as a conveyor. Note:Must be attached to func_conveyor entity.	textureScrollVar Name of variable to place result in. Note:must be a matrix or vector type variable (i.e. $baseTextureOffset).
LampBeam	Modulates the material’s alpha value based on angle between the beam’s direction and the viewer’s eye point. This is used to make the beams of volumetric light on lights fade as you look at them dead on. Note:Must be attached to entity for angle use.	No return value.
LampHalo	Modulates the material’s alpha value based on angle between the beam’s direction and the viewer’s eye point. Like the LampBeam proxy, but used for the halo at the beam’s base. Note:Must be attached to entity for angle use.	No return value.

See also

Creating Materials

External Links

Scrolling Materials