Difference between revisions of "Vertex animation"

From Valve Developer Community
Jump to: navigation, search
m (Fixed the templates)
(Updated info and revised article. Gmod now supports vertex animation as of 2021-06-09.)
Line 1: Line 1:
'''Vertex animation''' is the keyframed animation of individual [[vertex|vertices]] of a mesh. It's good for very complicated motion like that of cloth, hair, or water. It uses a flex controller bone to move the model through a series of flexes (one for each frame).
+
'''Vertex animation''' is the keyframed animation of the individual [[vertex|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 {{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:
 +
* {{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.
 +
:* Gmod supports vertex animation on both its own modified v48 MDLs with as well as v49 MDLs compiled with SFM, Alien Swarm, or similar.
 +
 
  
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]].
 
 
{{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.}}
  
  
== Implementation ==
+
== Compiling Models with Vertex Animation ==
{{todo | CLEANUP! OUTDATED!}}
+
=== Using SMD ===
# Create a vertex animation in your modelling tool.
+
* Create a vertex animation with your modeling package.
# Export a Vertex Cache file. Currently only the official Maya exporter can do this, and only to SMD.
+
* Export a Vertex Cache file. Currently, only the official Maya exporter can do this.
# Add the <code>vcafile</code> command to your [[$model (QC)|$model]] block (see example below).
+
* Include the vertex cache file in your <code>[[$model (QC)|$model]]</code> block with the <code>vcafile</code> command (see example below).
{{Note | DMX does not require a vertex cache file, so if you're using DMX ignore these two steps. The vertex animation data can be exported by Blender Source Tools to DMX.}}
+
<syntaxhighlight lang=php>
 +
$model "body" "reference_mesh.smd" {
 +
vcafile "my_vertex_animation.vta"
 +
}
 +
</syntaxhighlight>
  
 
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 animation. If you need to map the vertex animation to a standard animation sequence, perform these extra steps:
+
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'''.
 +
 
 +
=== 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 (QC)|$model]] to process the DMX file (see example below).
 +
<syntaxhighlight lang=php>
 +
$model "body" "reference_mesh_animated.dmx"
 +
</syntaxhighlight>
 +
 
 +
== 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.
 +
 
 +
* 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.
 +
* Add two <code>[[$boneflexdriver]]</code> commands to bind your vertex animation to the driver bone.
 +
* 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.
 +
:* 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.
  
# Add a new bone which will drive the vertex animation. It doesn't need to have any vertices attached.
+
{{bug|Currently the flex driver sequence '''must''' be defined with [[$upaxis|$upaxis Y]]. This doesn't affect the rest of the model.}}
# Add two <code>[[$boneflexdriver]]</code> commands to bind your vertex animation to the new bone (see example).
 
# Add at least one <code>[[$sequence]]</code> in which the new bone is animated in its X and Y axes. Its X position defines the blend weight of the vertex animation (0-1), and its Y position defines the frame of vertex animation (0-1). {{bug|Currently the flex driver sequence ''must'' be defined with [[$upaxis|$upaxis Y]]. This doesn't affect the rest of the model.}}
 
  
== Example ==
+
=== QC Example ===
  
 
<syntaxhighlight lang=php>
 
<syntaxhighlight lang=php>
$model "body" "ref_mesh.smd" {
+
$model "body" "reference_mesh.smd" {
vcafile "vertex_animation.vta"
+
vcafile "my_vertex_animation.vta"
 
}
 
}
 +
// If using DMX instead:
 +
// $model "body" "reference_mesh_animated.dmx"
  
// Optional:
+
$definebone "vertexAnimDriver" "" 0 0 0 0 0 0
  
$boneflexdriver "flexAnimBone" tx "vertex_animation" 0 1
+
$boneflexdriver "vertexAnimDriver" tx "my_vertex_animation" 0 1
$boneflexdriver "flexAnimBone" ty "multi_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
 
$upaxis Y // currently flex driver sequences must be Y-up
$sequence "vertex_animation" "flexAnimBone_anim.smd"
+
$sequence "idle" {
 +
"vertexAnimDriver_anim.smd" // SMD animation which moves the "vertexAnimDriver" bone
 +
fps 30
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 45: Line 81:
  
 
* <code>[[$boneflexdriver]]</code>
 
* <code>[[$boneflexdriver]]</code>
 +
* [[Flex animation]]
 
* [[Skeletal animation]]
 
* [[Skeletal animation]]
* [[Flex animation]]
+
 
 
[[Category:Modeling]]
 
[[Category:Modeling]]

Revision as of 15:47, 18 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

.

Other games which support vertex animation include:

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


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

Bug.png Bug: Using the $scale command breaks vertex animation.


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.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