Difference between revisions of "Vertex animation"

From Valve Developer Community
Jump to: navigation, search
(Updated info and revised article. Gmod now supports vertex animation as of 2021-06-09.)
m (Wording and clarity)
Line 3: Line 3:
 
Vertex animation was added in {{GameName|as}} and is available in all games that branch from it, including {{GameName|portal2}}, {{GameName|csgo}}, {{GameName|sfm}}, and {{GameName|dota2}}.
 
Vertex animation was added in {{GameName|as}} and is available in all games that branch from it, including {{GameName|portal2}}, {{GameName|csgo}}, {{GameName|sfm}}, and {{GameName|dota2}}.
  
Other games which support vertex animation include:
+
Some games on older engine branches may support vertex animation through backported or custom implementations. Such games include:
* {{GameName|GMOD}} Gmod's studiomdl creates models that extend the {{src13}} MDL v48 format with additional features (such as vertex animation). It does '''not''' create v49 MDLs.
+
* {{GameName|GMOD}} 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.
:* Gmod supports vertex animation on both its own modified v48 MDLs with as well as v49 MDLs compiled with SFM, Alien Swarm, or similar.
+
:{{Note|Gmod's studiomdl creates models that extend the {{src13}} 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.}}
  
  
 
{{todo|Check if vertex animation was actually added in L4D or L4D2}}
 
{{todo|Check if vertex animation was actually added in L4D or L4D2}}
  
{{bug|Using the [[$scale]] command breaks vertex animation.}}
+
{{bug|Using the [[$scale]] command breaks vertex animation. {{TODO|In what way?}}}}
  
  
Line 26: Line 26:
 
This produces two flex controllers named after your VCA file. The first defines the blend weight of the animation, the second (prefixed with <code>multi_</code>) defines the active frame.
 
This produces two flex controllers named after your VCA file. The first defines the blend weight of the animation, the second (prefixed with <code>multi_</code>) defines the active frame.
  
A programmer can now control your vertex animation. If you want to use your vertex animation like an ordinary <code>[[$sequence]]</code>, you must define driver bones and create a driver animation. See the next section, '''Driving Vertex Animations'''.
+
A programmer can now control your vertex animation. If you want to use your vertex animation like an ordinary <code>[[$sequence]]</code>, you must define and animate a special driver bone. See the next section, '''Driving Vertex Animations'''.
  
 
=== Using DMX ===
 
=== Using DMX ===
Line 32: Line 32:
 
* Configure your modeling package to include your vertex animation in the DMX export. You can include multiple vertex animations in a single DMX 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.
 
:* 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 (QC)|$model]] to process the DMX file (see example below).
+
* The exported DMX file contains both the reference mesh and one or more vertex animation(s). Use [[$model (QC)|$model]] to include the DMX file (see example below).
 
<syntaxhighlight lang=php>
 
<syntaxhighlight lang=php>
 
$model "body" "reference_mesh_animated.dmx"
 
$model "body" "reference_mesh_animated.dmx"
Line 38: Line 38:
  
 
== Driving Vertex Animations ==
 
== Driving Vertex Animations ==
A standard <code>[[$sequence]]</code> 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.
+
A standard <code>[[$sequence]]</code> 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.
 
* 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 <code>[[$definebone]]</code> in your QC file.
 
:* Alternatively, you can use <code>[[$definebone]]</code> in your QC file.
* Add two <code>[[$boneflexdriver]]</code> commands to bind your vertex animation to the driver bone.
+
* Add two <code>[[$boneflexdriver]]</code> 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 <code>$boneflexdriver</code> must use axis <code>tx</code> and the name of your vcafile (or, if using DMX, the name of the vertex animation block inside the DMX).
 +
:* The second <code>$boneflexdriver</code> must use axis <code>ty</code> and the name of the your vcafile with "multi_" prepended.
 
* Add at least one <code>[[$sequence]]</code> in which the driver bone is animated on its X and Y axes.
 
* Add at least one <code>[[$sequence]]</code> 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.
 
:* The driver bone's X position sets the blend weight (i.e. intensity) of the vertex animation, from 0.0 to 1.0.

Revision as of 01:11, 21 June 2021

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

and is available in all games that branch from it, including

,

,

, and

.

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

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.png Note: Gmod's studiomdl creates models that extend the Source 2013Source 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.png 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.png 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

See also