Class AnimationPlayer
Namespace: ValveResourceFormat.Renderer
Assembly: Renderer.dll
Plays animations on a single skeleton: advances clip time, mixes the weighted clips into a frame and writes that frame's world-space pose. An owns one player per skeleton its model can be animated from.
public class AnimationPlayerInheritance
Constructors
AnimationPlayer(Skeleton, FlexController[], Matrix4x4[], Matrix4x4[])
Initializes a new for the given skeleton and flex controllers. The bind pose and pose buffers are supplied by the owner and may be shared with it.
public AnimationPlayer(Skeleton skeleton, FlexController[] flexControllers, Matrix4x4[] bindPose, Matrix4x4[] pose)Parameters
skeleton Skeleton
The skeleton whose bones define the rig.
flexControllers FlexController[]
The flex controllers used for facial/morph animation.
bindPose Matrix4x4[]
The skeleton's world-space bind pose, one entry per bone.
pose Matrix4x4[]
The pose buffer to write into, one entry per bone.
Properties
ActiveAnimation
Gets the currently active animation, or null if none is set.
public Animation? ActiveAnimation { get; }Property Value
ActiveClipFinished
Gets whether the active animation clip has finished playing (is not looping and has reached the end).
public bool ActiveClipFinished { get; }Property Value
AnimationFrame
Gets the decoded animation frame data for the current tick, or null when no animation is active.
public Frame? AnimationFrame { get; }Property Value
ApplyAdditive
Gets or sets whether the active animation is composed over the bind pose. Seeded from the animation's additive flag on activation. Changing the value forces a pose update.
public bool ApplyAdditive { get; set; }Property Value
BindPose
Gets the skeleton's world-space bind pose.
public Matrix4x4[] BindPose { get; }Property Value
BoneMaskDefinitions
Bone masks are used by clips to weigh transforms on a per-bone basis.
public Dictionary<string, Half[]> BoneMaskDefinitions { get; }Property Value
Dictionary<string, Half[]>
Clips
Gets the current clips.
public Dictionary<string, AnimationPlayer.PlaybackClip> Clips { get; }Property Value
Dictionary<string, AnimationPlayer.PlaybackClip>
Frame
Gets or sets the current frame index of the active animation. Seeking targets a position in the cycle being played rather than the first one, so scrubbing a looping animation walks within that cycle instead of unwinding everything played so far.
public int Frame { get; set; }Property Value
FrameCache
Gets the frame cache used to retrieve and interpolate animation frames.
public AnimationFrameCache FrameCache { get; }Property Value
IsPaused
Gets or sets whether animation playback is paused. Changing the value forces a pose update.
public bool IsPaused { get; set; }Property Value
IsUsingMixer
Gets whether the current animation frame is the result of blending multiple clips together.
public bool IsUsingMixer { get; }Property Value
Pose
Gets the world-space transform of each bone for the current animation frame.
public Matrix4x4[] Pose { get; }Property Value
ResolvePosition
Gets or sets the resolver from an attachment name to a world position, an empty name being the model itself.
public Func<string, Vector3?>? ResolvePosition { get; set; }Property Value
RootMotionDelta
Gets the root motion the active clip has moved through since this was last consumed, as a rigid transform. Seeking contributes too, backwards as the motion in reverse.
public Matrix4x4 RootMotionDelta { get; }Property Value
Skeleton
Gets the skeleton this player animates.
public Skeleton Skeleton { get; }Property Value
Time
Gets or sets the current playback time in seconds.
public float Time { get; set; }Property Value
Methods
ClearClips()
Clears all clips and blend state so a later transition starts from a clean state.
public void ClearClips()ConsumeRootMotionDelta()
Takes and clears it, so a caller running at a different rate than the animation neither applies a step twice nor loses one.
public Matrix4x4 ConsumeRootMotionDelta()Returns
GetFrame()
Returns the animation frame for the current time, using exact frame lookup when paused or interpolation during playback.
public Frame? GetFrame()Returns
The current animation frame, or null if no animation is active.
PrewarmAnimationSounds(Animation)
Pre-decodes every sound the animation's events can play. Call when the animation is loaded.
public static void PrewarmAnimationSounds(Animation animation)Parameters
animation Animation
RegisterBoneMask(string, Dictionary<string, float>)
Registers a bone mask for per-bone transform weighting.
public void RegisterBoneMask(string name, Dictionary<string, float> boneWeights)Parameters
name string
The name of the bone mask.
boneWeights Dictionary<string, float>
Dictionary mapping bone names to weight values (0.0 to 1.0).
SetAnimation(Animation?, float, bool, bool)
Sets the active animation with a blend-in time for smooth transitions.
public void SetAnimation(Animation? animation, float blendTime, bool looping, bool warp = false)Parameters
animation Animation?
The animation to activate, or null to clear.
blendTime float
The time in seconds to blend from previous animations to the new animation.
looping bool
Whether the clip should loop when reaching the end.
warp bool
Whether re-activating the animation already playing should cross over into a second instance of it rather than restarting it in place.
SetAnimationProperties(string, float?, bool?, string?)
Sets properties for a clip with the specified animation name.
public void SetAnimationProperties(string name, float? time = null, bool? looping = null, string? boneMask = null)Parameters
name string
The name of the animation.
time float?
Optional playback time to set.
looping bool?
Optional looping flag to set.
boneMask string?
Optional bone mask name to set.
SetAnimationWeight(string, float, bool)
Sets the blend weight for a clip with the specified animation name.
public void SetAnimationWeight(string name, float weight, bool restartIfNew = false)Parameters
name string
The name of the animation.
weight float
The weight value (0.0 to 1.0).
restartIfNew bool
Whether to restart the animation if it's just now fading in.
Update(float, Matrix4x4)
Advances the animation by timeStep seconds and writes the skeleton's world-space pose under rootTransform.
public bool Update(float timeStep, Matrix4x4 rootTransform)Parameters
timeStep float
Elapsed time in seconds since the last update.
rootTransform Matrix4x4
The transform applied to the skeleton roots.
Returns
true if the pose was updated; false if nothing changed.
ClipEventFired
Raised for every event of an animation graph clip crossed while the player advances its clips. Consumers filter for the event types they handle.
public event Action<NmClipEvent>? ClipEventFiredEvent Type
SequenceEventFired
Raised for every event of a sequence animation crossed while the player advances its clips. Kept apart from because sequence events are a struct, which handing to a delegate of their shared interface would box on every fire.
public event Action<AnimationEvent>? SequenceEventFired