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 Template:GameName and is available in all games that branch from it, including Template:GameName, Template:GameName, Template:GameName, and Template:GameName.

Other games which support vertex animation include:

• Template:GameName Gmod's studiomdl creates models that extend the MDL v48 format with additional features (such as vertex animation). It does not create v49 MDLs.

• Gmod supports vertex animation on both its own modified v48 MDLs with as well as v49 MDLs compiled with SFM, Alien Swarm, or similar.

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

Bug:Using the $scale command breaks vertex animation.  [todo tested in ?]

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 driver bones and create a driver animation. 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 process 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 this special 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.
• 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