$sequence

From Valve Developer Community
Revision as of 07:24, 11 October 2008 by Coder0xff (talk | contribs) (→‎Advanced: Added references to ikrule and iklock)
Jump to navigation Jump to search

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 any number of $animation commands.

Note.pngNote:A $sequence can only see $animations that come above it in the QC file.

Usage

Simple

$sequence <name> <Skeletal animation SMD> <simple options>

Advanced

$sequence <name> <options> {		// opening brace must be on the same line as the command
	<$animation name(s)>
	<advanced options>
	<events>
}

Options

Simple

<string|name>
The name of the animation. Will appear in HLMV, Hammer, etc.
<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
Is this animation designed to loop? (Any animation can be looped, this just performs a bit of cleanup.)
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 speed at which the animation plays. Note that these are animation frames - not screen frames!
Todo: Performance implications; sparse keyframes = CPU load, dense keyframes = memory load?
<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 (See $animation for making the model move in global co-ords during 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.pngTip:You can extract motion from any combination of axes. Just put a space between each one.
activity <string|name> <float|weight>
Links the sequence to an activity. The name should be one recognised by the target NPC's code. Weight 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.
Tip.pngTip:If there is only one sequence tied to the activity, use a weight of -1.
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.pngWarning: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.
  • The spline option converts the linear start-peak and tail-end fades of the $sequence to a spline curve.
  • Todo: Behaviour of xfade.
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
Ignore the $sequence's fps 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.
fadein <float|seconds>
Override how long this animation spends fading in. Default is 0.2.
fadeout <float|seconds>
Override how long this animation spends fading out. Default is 0.2.
weightlist <string|weightlist name>
select a $weightlist to apply to this sequence
Todo: verify this is correct

Advanced

In addition to all simple options except <Skeletal animation SMD>:

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.pngWarning: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
See $ikchain

Events

A further sub-key is available with $sequence: 'event'. See Animation Events for a full description.

Unclear

Todo: Which category are these?
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 be 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 expect 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.

Examples

Simple

$modelname		"weapons/shell.mdl"
$cdmaterials		"models/weapons/"
$body		shell	"shell-ref.smd"
$sequence	idle	"shell-idle.smd"

Advanced

$animation a_strokechin "strokechin.smd" subtract idle 0

$sequence strokechin delta {
	a_strokechin
}
$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"
}