Difference between revisions of "$sequence"

From Valve Developer Community
Jump to: navigation, search
(Simple: Factual changes, a bit of cleanup, added a few extra warnings/notes, properly documented localhierarchy, cleaned up todos, and spaced out each command so that the article is easier to edit.)
Line 58: Line 58:
 
; <code><[[string]]|name></code>
 
; <code><[[string]]|name></code>
 
: The name of the animation. Will appear in HLMV, Hammer, etc.
 
: The name of the animation. Will appear in HLMV, Hammer, etc.
 +
 
; <code>frame <start frame> <end frame></code>
 
; <code>frame <start frame> <end frame></code>
: Specifies the length of frames to use from the provided animation. The length will be moved back to 0, e.g. <code>frames 80 110</code> would be recognized as a length of 0-30.
+
: Specifies a range of frames to extract from the source animation. Useful for trimming off frames not used in in particular animation.
{{warning|Anything relying on specific frame numbers (such as [[Animation Events]]) is not re-mapped.}}
+
:: For example, if the source animation contains 80 frames but this animation should only play the last 30 frames, then <code>frames 50 80</code> will load only those frames.
:{{todo|Write a better explanation.}}
+
: Can also be used to extract a single frame of animation by making the start and end frames match.
; <code>origin <x> <y> <z></code>
+
: <code>frames</code> is an alias of <code>frame</code>, and can be used interchangeably with it.
 +
: {{warning|All frame numbers used elsewhere in the sequence (e.g. [[Animation Events|animation events]]) are relative to <code>start frame</code>.}}
 +
 
 +
; <code>origin <[[float]]|x> <[[float]]|y> <[[float]]|z></code>
 
: Adjusts the position of the animation within its own local space.
 
: Adjusts the position of the animation within its own local space.
; <code>rotate <x> <y> <z></code>
+
 
 +
; <code>angles <[[float]]|x> <[[float]]|y> <[[float]]|z></code>
 
: Adjusts the rotation of the animation within its own local space.
 
: Adjusts the rotation of the animation within its own local space.
; <code>angles</code>
+
 
: {{todo|Documentation}}
+
; <code>rotate <[[float]]|angle></code>
 +
: Identical to <code>angles</code>, but it only rotates along the Z axis.
 +
 
 
; <code>scale <[[float]]|scale></code>
 
; <code>scale <[[float]]|scale></code>
 
: Multiplies the size of the skeleton in this sequence. Negative values are accepted.
 
: Multiplies the size of the skeleton in this sequence. Negative values are accepted.
 +
 
; <code>reverse</code> {{CSGO add|}}
 
; <code>reverse</code> {{CSGO add|}}
 
: Reverses the animation.
 
: Reverses the animation.
 +
 
; <code><string|Skeletal animation SMD></code>
 
; <code><string|Skeletal animation SMD></code>
: Path to the $sequence's source SMD. ''By including this, you tell studiomdl that you are using the simple version of the command.''
+
: Path to the <code>$sequence</code>'s source SMD. ''By including this, you tell studiomdl that you are using the simple version of the command.''
 +
 
 
; <code>loop</code>
 
; <code>loop</code>
 
: Has three effects:
 
: Has three effects:
Line 79: Line 89:
 
:* Prevents the sequence from restarting if triggered while already playing.
 
:* Prevents the sequence from restarting if triggered while already playing.
 
:* Causes studiomdl to perform some cleanup between the first and last frames.
 
:* Causes studiomdl to perform some cleanup between the first and last frames.
; <code>noforceloop</code>
+
 
: {{todo|Documentation}}
+
; <code>hidden</code>
;<code>hidden</code>
+
: Prevents the $sequence from being listed in user interfaces. Useful for sequences which serve only as layers of others.
:Prevents the $sequence from being listed in user interfaces. Useful for sequences which serve only as layers of others.
+
 
;<code>fps <[[float]]|frames per second></code>
+
; <code>fps <[[float]]|frames per second></code>
:Override the speed at which the animation plays. Note that these are ''animation'' frames - not screen frames! {{TODO|Performance implications; sparse keyframes &#61; CPU load, dense keyframes &#61; memory load?}}
+
: Override the framerate of the animation. If unspecified, defaults to <code>30</code>.
;<code><[[string]]|motion extract axis></code>
+
: {{note|These are ''animation'' frames - not screen frames!}}
:Movement animations are easier to create if the model actually moves forwards, but for playback in-game it must "walk on the spot". This command resolves the issue by stripping root bone translation from an animation. Accepted axes are:
+
 
:*X, Y, and Z
+
; <code><[[string]]|motion extract axis></code>
:*LX, LY and LZ - the root bone moves along the axis until the animation is half complete, then moves back to its original position. {{tip|You can extract motion from any combination of axes. Just put a space between each one.}}
+
: Movement animations are easier to create if the model actually moves forwards, but for playback in-game it must "walk on the spot". This command resolves the issue by stripping root bone translation from an animation. Accepted axes are:
 +
: *X, Y, and Z
 +
: *LX, LY and LZ - the root bone moves along the axis until the animation is half complete, then moves back to its original position. {{tip|You can extract motion from any combination of axes. Just put a space between each one.}}
 
: This command is also available on [[$animation]]s.
 
: This command is also available on [[$animation]]s.
;<code>activity <[[string]]|name> <[[float]]|weight></code>
+
 
:Links the sequence to an [[activity]]. The name should be one recognised by the target NPC's code. <code>Weight</code> modifies how likely this particular sequence is to be picked when the activity is called; if a $sequence has a weight twice that of another, it is twice as likely to be used. If an activity name starts with "ACT_" then the activity keyword can be removed. When ACT_ is seen, it is implicitly an activity. {{tip|If there is only one sequence tied to the activity, use a weight of -1.}}
+
; <code>activity <[[string]]|name> <[[float]]|weight></code>
;<code>autoplay</code>
+
: Links the sequence to an [[activity]].
:Makes the $sequence play at all times, on top of any other animations, no matter what the model is doing. Good for blended breathing animations and other automated motion. If a model has multiple <code>autoplay</code> $sequences, they’re layered in the order that they appear in the QC. {{warning|Don't use this for an animation that might be played normally, or you'll end up with it playing twice and the motion doubling up.}}
+
: {{tip|If an activity name starts with "ACT_" then the activity keyword can be removed. When ACT_ is seen, it is implicitly an activity.}}
;<code>addlayer <[[string]]|other $sequence name></code>
+
: If more than one <code>$sequence</code> has the same [[activity]], then the <code>weight</code> specifies how likely this sequence is to be picked when that activity is called. The odds of any particular <code>$sequence</code> playing is simply its weight over the sum of all other weights.
:Play another sequence (probably <code>delta</code>-ed) at the same time as this one. The animations begin and end together. The other $sequence ''doesn't'' have to be above the current one.
+
:: For example, if a <code>$sequence</code> named <code>swing_a</code> has a weight of 2, and another <code>$sequence</code> named <code>swing_b</code> has a weight of 1, then there is a 2/3 chance for <code>swing_a</code> to play instead of <code>swing_b</code>.
;<code>blendlayer <[[string]]|other $sequence name> <[[int]]|startframe> <[[int]]|peakframe> <[[int]]|tailframe> <[[int]]|endframe> [spline] [xfade]</code>
+
:: {{note|If there is only one sequence tied to the activity, then its weight is irrelevant.}}
:Similar to <code>addlayer</code>, but the new $sequence only plays over specified frames.
+
 
:*<code>peakframe</code> is when the animation reaches 100% intensity, and <code>tailframe</code> is when it starts to fade away.
+
; <code>autoplay</code>
:*The <code>spline</code> option converts the linear start-peak and tail-end fades of the $sequence to a spline curve.
+
: Makes the sequence play at all times, on top of any other animations, no matter what the model is doing. Good for blended breathing animations and other automated motion. If a model has multiple <code>autoplay</code> $sequences, they’re layered in the order that they appear in the QC. {{warning|Don't use this for an animation that might be played normally, or you'll end up with it playing twice and the motion doubling up.}}
:*The <code>xfade</code> option causes the animation to only fade in and not back out.
+
 
;<code>snap</code>
+
; <code>addlayer <[[string]]|other $sequence name></code>
:Remove all blending when transitioning to this animation. This is useful for reaction animations that are the result of sudden and violent changes in the model's state, such as a creature flinching or a weapon firing.  
+
: Play another sequence (probably <code>delta</code>-ed) at the same time as this one. The animations begin and end together. The other $sequence ''doesn't'' have to be above the current one.
;<code>realtime</code>
+
 
:Ignore the $sequence's <code>fps</code> and time it with the global system clock instead. Useful when adding layers that shouldn't play at the same rate as their parent $sequence.  
+
; <code>blendlayer <[[string]]|other $sequence name> <[[int]]|startframe> <[[int]]|peakframe> <[[int]]|tailframe> <[[int]]|endframe> [spline] [xfade]</code>
;<code>fadein <[[float]]|seconds></code>
+
: Similar to <code>addlayer</code>, but the new $sequence only plays over specified frames.
:Override how long this animation spends fading in. Default is 0.2.
+
:: <code>peakframe</code> is when the animation reaches 100% intensity, and <code>tailframe</code> is when it starts to fade away.
;<code>fadeout <[[float]]|seconds></code>
+
:: <code>spline</code> (optional) converts the linear start-peak and tail-end fades of the $sequence to a spline curve.
:Override how long this animation spends fading out. Default is 0.2.
+
:: <code>xfade</code> (optional) causes the animation to only fade in and not back out.
;<code>weightlist <[[string]]|weightlist name></code>
+
: {{warning|Unless the blended sequence has the <code>realtime</code> option, the blended sequence's framerate will be adjusted relative to the parent sequence so that it starts on <code>startframe</code> and ends on <code>endframe</code>. For example, if both the parent and blended sequences play at 30 frames per second and last for 30 frames, but the blended sequence only plays during frames 5 through 20 (15 frames, only ''half'' of its original length), then the blended sequence will play at 60 frames per second ('''twice''' its original framerate!) so that it can start on frame 5 and end on frame 20.}}
:Selects a [[$weightlist]] to apply to this sequence.
+
 
;<code>localhierarchy "<bone name>" "<parent bone name>"</code>
+
; <code>snap</code>
:Changes a bone's parent for this animation only. "" can be used to remove the parent of a bone.
+
: Remove all blending when transitioning to this animation. This is useful for reaction animations that are the result of sudden and violent changes in the model's state, such as a creature flinching or a weapon firing.
:{{note|This does not affect animations during transitions, making <code>snap</code> necessary.}}
+
 
;<code>compress <[[int]]|frameskip></code>
+
; <code>realtime</code>
:Skip a given amount of frames to reduce model file size
+
: Instead of playing the animation from its first frame whenever it's asked to play, the animation always plays relative to the global system clock. Useful for adding layers that shouldn't play at the same rate as their parent $sequence, such as breathing.
 +
 
 +
; <code>fadein <[[float]]|seconds></code>
 +
: Override how long this animation spends fading in. Default is 0.2.
 +
: {{note|<code>fadein 0</code> achieves the same effect as <code>snap</code>, but [[HLMV]] will not recognize it as a snap when automatic blending is enabled, making <code>snap</code> necessary.}}
 +
 
 +
; <code>fadeout <[[float]]|seconds></code>
 +
: Override how long this animation spends fading out. Default is 0.2.
 +
 
 +
; <code>weightlist <[[string]]|weightlist name></code>
 +
: Selects a [[$weightlist]] to apply to this sequence.
 +
: If a [[$defaultweightlist|default weightlist]] is used, this weightlist will override it.
 +
 
 +
; <code>localhierarchy <[[string]]|bone name> <[[string]]|new parent name> [range <[[int]]|startframe> <[[int]]|peakframe> <[[int]]|tailframe> <[[int]]|endframe>]</code>
 +
: Changes a bone's parent for this animation only. "" can be used to remove the parent of a bone.
 +
: This is primarily useful for ensuring that a bone blends correctly. As an example, if a weapon is normally held in the right hand, but during this animation it's held in the left hand, it will blend as if it were being held by the right hand. This option can then be used to make it blend relative to the left hand instead, which will remove the jittering caused by blending.
 +
: <code>range</code> is optional, and requires four frame numbers that specify how the hierarchy should be blended over the specified frames.
 +
: {{note|This does not affect animations during transitions, making <code>snap</code> necessary.}}
 +
 
 +
; <code>compress <[[int]]|frameskip></code>
 +
: Skip a given amount of frames to reduce model file size
  
 
=== Advanced ===
 
=== Advanced ===

Revision as of 18:00, 22 November 2019

The QC command $sequence defines a skeletal animation. It can be used either on its own, or, to make use of Source's more advanced skeletal animation features, in conjunction with one or several $animations.

Note:All models that have any polygons must have at least one $sequence. If you don't actually want any movement, it's easiest to re-use your reference SMD. Models that solely use $includemodel do not require any $sequences.
To do: What happens if no $sequences exist in the $includemodel?

Usage

$sequence has two modes. One directly accesses a single skeletal animation (SMD or DMX), while the other needs intermediate $animations.

Note:a DMX skeletal animation may only be used if the game that the model is being compiled for has dmxconvert. a list of games which have dmxconvert can be found on this page: DMX
Note:A $sequence can only see $animations that come above it in the QC file.
$sequence <name> <skeletal animation SMD/DMX> <simple options>
$sequence <name> {		// opening brace must be on the same line as the command
	<$animation name(s)>
	<advanced options>
	<events>
	<simple options>
}

Examples

$modelname		"weapons/shell.mdl"
$cdmaterials		"models/weapons/"
$body		shell	"shell-ref.smd"
$sequence idle	"shell-idle.smd"
$animation a_strokechin "strokechin.smd" subtract idle 0

$sequence strokechin {
	a_strokechin
	delta
}
$sequence run_holding_all {
	a_runS a_runSE a_runE a_runNE a_runN_SMG a_runNW a_runW a_runSW a_runS

	blendwidth 9
	blend move_yaw -180 180
	addlayer layer_run_holding
	ACT_RUN_RIFLE 1
	node "running"
}

Options

Simple

<string|name>
The name of the animation. Will appear in HLMV, Hammer, etc.
frame <start frame> <end frame>
Specifies a range of frames to extract from the source animation. Useful for trimming off frames not used in in particular animation.
For example, if the source animation contains 80 frames but this animation should only play the last 30 frames, then frames 50 80 will load only those frames.
Can also be used to extract a single frame of animation by making the start and end frames match.
frames is an alias of frame, and can be used interchangeably with it.
Warning: All frame numbers used elsewhere in the sequence (e.g. animation events) are relative to start frame.
origin <float|x> <float|y> <float|z>
Adjusts the position of the animation within its own local space.
angles <float|x> <float|y> <float|z>
Adjusts the rotation of the animation within its own local space.
rotate <float|angle>
Identical to angles, but it only rotates along the Z axis.
scale <float|scale>
Multiplies the size of the skeleton in this sequence. Negative values are accepted.
reverse (New with Counter-Strike: Global Offensive)
Reverses the animation.
<string|Skeletal animation SMD>
Path to the $sequence's source SMD. By including this, you tell studiomdl that you are using the simple version of the command.
loop
Has three effects:
  • Causes the sequence to repeat endlessly until stopped.
  • Prevents the sequence from restarting if triggered while already playing.
  • Causes studiomdl to perform some cleanup between the first and last frames.
hidden
Prevents the $sequence from being listed in user interfaces. Useful for sequences which serve only as layers of others.
fps <float|frames per second>
Override the framerate of the animation. If unspecified, defaults to 30.
Note:These are animation frames - not screen frames!
<string|motion extract axis>
Movement animations are easier to create if the model actually moves forwards, but for playback in-game it must "walk on the spot". This command resolves the issue by stripping root bone translation from an animation. Accepted axes are:
*X, Y, and Z
*LX, LY and LZ - the root bone moves along the axis until the animation is half complete, then moves back to its original position.
Tip:You can extract motion from any combination of axes. Just put a space between each one.
This command is also available on $animations.
activity <string|name> <float|weight>
Links the sequence to an activity.
Tip:If an activity name starts with "ACT_" then the activity keyword can be removed. When ACT_ is seen, it is implicitly an activity.
If more than one $sequence has the same activity, then the weight specifies how likely this sequence is to be picked when that activity is called. The odds of any particular $sequence playing is simply its weight over the sum of all other weights.
For example, if a $sequence named swing_a has a weight of 2, and another $sequence named swing_b has a weight of 1, then there is a 2/3 chance for swing_a to play instead of swing_b.
Note:If there is only one sequence tied to the activity, then its weight is irrelevant.
autoplay
Makes the sequence play at all times, on top of any other animations, no matter what the model is doing. Good for blended breathing animations and other automated motion. If a model has multiple autoplay $sequences, they’re layered in the order that they appear in the QC. Warning: Don't use this for an animation that might be played normally, or you'll end up with it playing twice and the motion doubling up.
addlayer <string|other $sequence name>
Play another sequence (probably delta-ed) at the same time as this one. The animations begin and end together. The other $sequence doesn't have to be above the current one.
blendlayer <string|other $sequence name> <int|startframe> <int|peakframe> <int|tailframe> <int|endframe> [spline] [xfade]
Similar to addlayer, but the new $sequence only plays over specified frames.
peakframe is when the animation reaches 100% intensity, and tailframe is when it starts to fade away.
spline (optional) converts the linear start-peak and tail-end fades of the $sequence to a spline curve.
xfade (optional) causes the animation to only fade in and not back out.
Warning: Unless the blended sequence has the realtime option, the blended sequence's framerate will be adjusted relative to the parent sequence so that it starts on startframe and ends on endframe. For example, if both the parent and blended sequences play at 30 frames per second and last for 30 frames, but the blended sequence only plays during frames 5 through 20 (15 frames, only half of its original length), then the blended sequence will play at 60 frames per second (twice its original framerate!) so that it can start on frame 5 and end on frame 20.
snap
Remove all blending when transitioning to this animation. This is useful for reaction animations that are the result of sudden and violent changes in the model's state, such as a creature flinching or a weapon firing.
realtime
Instead of playing the animation from its first frame whenever it's asked to play, the animation always plays relative to the global system clock. Useful for adding layers that shouldn't play at the same rate as their parent $sequence, such as breathing.
fadein <float|seconds>
Override how long this animation spends fading in. Default is 0.2.
Note:fadein 0 achieves the same effect as snap, but HLMV will not recognize it as a snap when automatic blending is enabled, making snap necessary.
fadeout <float|seconds>
Override how long this animation spends fading out. Default is 0.2.
weightlist <string|weightlist name>
Selects a $weightlist to apply to this sequence.
If a default weightlist is used, this weightlist will override it.
localhierarchy <string|bone name> <string|new parent name> [range <int|startframe> <int|peakframe> <int|tailframe> <int|endframe>]
Changes a bone's parent for this animation only. "" can be used to remove the parent of a bone.
This is primarily useful for ensuring that a bone blends correctly. As an example, if a weapon is normally held in the right hand, but during this animation it's held in the left hand, it will blend as if it were being held by the right hand. This option can then be used to make it blend relative to the left hand instead, which will remove the jittering caused by blending.
range is optional, and requires four frame numbers that specify how the hierarchy should be blended over the specified frames.
Note:This does not affect animations during transitions, making snap necessary.
compress <int|frameskip>
Skip a given amount of frames to reduce model file size

Advanced

In addition to all simple options:

delta
Tells Source that the $animations referenced in this sequence have all been subtracted. The $sequence will be played on top of whatever sequences are currently playing, rather than overriding them. Warning: Using this with an $animation that hasn't been subtracted has bad results!
predelta
The compliment to the "presubtract" command, this tells the animation compositing system to add the current bone setup on top of a different frame of reference instead of overriding each bones’ animation based on the typical cross-fade weighting scheme.
blend <string|name> <float|min value> <float|max value>
blendwidth <int|width>
See Blend sequence.
ikrule
See $ikchain
iklock

Freezes the bone specified in an $ikchain

See $ikchain
activitymodifier <string|modifier> (New with Alien Swarm) (Also in Source 2013)
To do: Documentation

Miscellaneous

node (name)
Tags the sequence as belonging to a point on the sequence transition graph table. This is for animations which don’t change graph state, such as looping animations. Multiple sequences can be at the same entry in the graph table, at which point they won’t need transition animations to move between each other.
Alternatively, you can have them at different points and expressly skip transitions (see $skiptransition). Sequences with no declaration are assumed at the root node and the transition graph assumes any sequence can move from the root node or to the root node without a intermediate transition.
transition (from) (to)
This specifies that the animation enters from one point on the node graph and exits at another point. This is used to play transitional sequences such as walk_to_stand, run_to_crouch, etc.
rtransition (name1) (name2)
Same as transition, but flags the sequence as able to be run in reverse order. This was used by the tentacle in HL1 but I don’t recommend it be used except in special cases.
exitphase (phase)
When transitioning between looping animations, such as "stand_to_run", this tells the movement system where to start the next sequence, assuming it’s looping. It’s also assumed that you’ve made all the sequences that share the next node to be phase matched (see startloop).
$skiptransition (name1) (name2) [(name3) ...]
This adds a rule to the transition graph to allow direct movement between all the named nodes. This is useful for transitions between unique named nodes that that may not require any specific intermediate animation. This is how to avoid the transition graph from forcing "walk" to "run" to instead be a "walk" to "stand" to "run" transition.
keyvalues { [stuff] }
Add a keyvalue block (see $keyvalues) to a specific sequence. This is used for setting up gestures for Faceposer.

Events

Events are available when using $animations. See Animation Events.