Vertex animation

Vertex animation is the keyframed animation of the individual vertices of a mesh. It is useful for complex motion, such as that of cloth, hair, or water. Each frame of the vertex animation is stored as a unique flex, and a special flex controller bone drives the animation by progressing through the flexes. This approach allows vertex animation to be combined with typical skeletal animation.

Vertex animation was added in Alien Swarm and is available in all games that branch from it, including Portal 2 , Counter-Strike: Global Offensive , Source Filmmaker , and Dota 2 .

Some games on older engine branches may support vertex animation through backported or custom implementations. Such games include:

• Garry's Mod supports vertex animation (since update 2021.06.09) on its own modified v48 MDLs and on v49 MDLs compiled with SFM, Alien Swarm, or similar.

 Note: Gmod's studiomdl creates models that extend the Source 2013 MDL v48 format with additional features, including vertex animation. These modified v48 MDLs are not compatible with other games. This studiomdl does not create v49 MDLs.

To do: Check if vertex animation was actually added in L4D or L4D2

 Bug: Using the $scale command breaks vertex animation. To do: In what way?

Compiling Models with Vertex Animation

Using SMD

• Create a vertex animation with your modeling package.
• Export a Vertex Cache file. Currently, only the official Maya exporter can do this.
• Include the vertex cache file in your $model block with the vcafile command (see example below).

$model "body" "reference_mesh.smd" {
	vcafile "my_vertex_animation.vta"
}

This produces two flex controllers named after your VCA file. The first defines the blend weight of the animation, the second (prefixed with multi_) defines the active frame.

A programmer can now control your vertex animation. If you want to use your vertex animation like an ordinary $sequence, you must define and animate a special driver bone. See the next section, Driving Vertex Animations.

Using DMX

• The DMX format can store vertex animations with the reference mesh and does not require an additional VCA file.
• Configure your modeling package to include your vertex animation in the DMX export. You can include multiple vertex animations in a single DMX file.

• In Blender Source Tools, use the Vertex Animation options under Scene > Source Engine Exportables.

• The exported DMX file contains both the reference mesh and one or more vertex animation(s). Use $model to include the DMX file (see example below).

$model "body" "reference_mesh_animated.dmx"

Driving Vertex Animations

A standard $sequence can drive a vertex animation without the need for a programmer. The position of a special driver bone in your model's skeleton is used to specify the frame and intensity of the vertex animation. By animating the driver bone, you can play the vertex animation, as well as combine it with regular skeletal animation.

• In your modeling package, create a bone at the origin (0,0,0). You do not have to weight any vertices to it.

• Alternatively, you can use $definebone in your QC file.

• Add two $boneflexdriver commands to bind your vertex animation to the driver bone. Each command requires specific names and parameters. Refer to the QC example below.

• The first $boneflexdriver must use axis tx and the name of your vcafile (or, if using DMX, the name of the vertex animation block inside the DMX).
• The second $boneflexdriver must use axis ty and the name of the your vcafile with "multi_" prepended.

• Add at least one $sequence in which the driver bone is animated on its X and Y axes.

• The driver bone's X position sets the blend weight (i.e. intensity) of the vertex animation, from 0.0 to 1.0.
• Its Y position sets the progress of vertex animation, from 0.0 to 1.0.

• For example, if your vertex animation is 120 frames long, frame 90 will be displayed when the driver bone's Y position is 0.75.
• If your modeling package is a Z-up world (like Blender or 3ds Max), you may need to translate the driver bone along its Z axis instead of Y. See the bug note below.

 Bug: Currently the flex driver sequence must be defined with $upaxis Y. This doesn't affect the rest of the model.

QC Example

$model "body" "reference_mesh.smd" {
	vcafile "my_vertex_animation.vta"
}
// If using DMX instead:
// 	$model "body" "reference_mesh_animated.dmx"

$definebone "vertexAnimDriver" "" 0 0 0 0 0 0

$boneflexdriver "vertexAnimDriver" tx "my_vertex_animation" 0 1
$boneflexdriver "vertexAnimDriver" ty "multi_my_vertex_animation" 0 1
// "my_vertex_animation" is the name of the vcafile when using SMD (or name of the vertex animation block embedded in the DMX when using DMX)

$upaxis Y // currently flex driver sequences must be Y-up
$sequence "idle" {
	"vertexAnimDriver_anim.smd"	// SMD animation which moves the "vertexAnimDriver" bone
	fps 30
}

Example Videos

• A simple video showing the use of Vertex animation for hair.
• A simple video showing the use of Vertex animation for cloth.
• Example of vertex animation in Source Filmmaker.
• Example of vertex animation in Portal 2's HLMV.

See also

• $boneflexdriver
• Flex animation
• Skeletal animation