Collapse Sidebar


Changes the weight of an animation, with the optional fadeTime parameter determining how long it takes for AnimationTrack/WeightCurrent to reach AnimationTrack/WeightTarget.

When weight is set in an AnimationTrack it does not change instantaneously but moves from WeightCurrent to AnimationTrack/WeightTarget. The time it takes to do this is determined by the fadeTime parameter given when the animation is played, or the weight is adjusted.

WeightCurrent can be checked against AnimationTrack/WeightTarget to see if the desired weight has been reached. Note that these values should not be checked for equality with the == operator, as both of these values are floats. To see if WeightCurrent has reached the target weight, it is recommended to see if the distance between those values is sufficiently small (see code sample below).

The animation weighting system is used to determine how AnimationTracks playing at the same priority are blended together. The default weight is one, and no movement will be visible on an AnimationTrack with a weight of zero. The pose that is shown at any point in time is determined by the weighted average of all the Poses and the WeightCurrent of each AnimationTrack. See below for an example of animation blending in practice.

Animation Weight Blending

In most cases blending animations is not required and using AnimationTrack/Priority is more suitable.


Name Type Default Description

The weight the animation is to be changed to.


The duration of time that the animation will fade between the old weight and the new weight for.


Return Type Summary

Code Samples

AnimationTrack Change Weight

This code sample includes a function that changes the weight of an AnimationTrack and yields until the weight has changed to the new target weight.

The purpose of this sample is to demonstrate how the fadeTime parameter of AnimationTrack.ChangeWeight works. In most cases, if a developer wishes to yield over the fadeTime it is recommended they use wait(fadeTime).

local function changeWeight(animationTrack, weight, fadeTime)
	animationTrack:AdjustWeight(weight, fadeTime)
	local startTime = tick()
	while math.abs(animationTrack.WeightCurrent - weight) > 0.001 do
	print("Time taken to change weight "..tostring(tick() - startTime))