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. In this way, vertex animation is implemented as a superset of flex animation. This approach allows vertex animation to be combined with typical skeletal animation, just like flex animations.

Bug:Using the $scale command breaks vertex animation.

Todo: In what way?

  [todo tested in?]

Availability

Vertex animation was added in Alien Swarm and is available in all games that branch from it, including Portal 2, Source Filmmaker, Counter-Strike: Global Offensive, and Dota 2. Starting with Alien Swarm, the v49 MDL format (IDST1) was extended to include the additional data required for vertex animation. Only Alien Swarm's studiomdl or newer (SFM, Portal 2, etc) can compile v49 MDLs with vertex animation. Studiomdls from earlier IDST1 games, including Left 4 Dead and Left 4 Dead 2, compile v49 MDLs but do not support vertex animation.

Todo: Check if technological support for vertex animation is truly absent from L4D/L4D2 or if exists but is simply unused

Vertex Animation in Other Games

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 non-standard v48 MDL format and on v49 MDLs compiled with Alien Swarm, Source Filmmaker, or similar. Gmod's studiomdl creates MDLs that extend the Source 2013 v48 MDL format with additional features, including vertex animation. These non-standard v48 MDLs are not compatible with other games. Gmod's studiomdl does not create v49 MDLs.

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.  [todo tested in?]

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