KeyframeSequence

Show Deprecated

This object stores all the Keyframes for an animation, determines if the animation is looped, and determines its priority against other animations.

What is a KeyframeSequence?

Roblox constructs the animation data it uses in the playback of an animation, referenced by the Animation.AnimationId property from a KeyframeSequence. Every animation refers to a KeyframeSequence or to a CurveAnimation internally. Although, usually created by the Roblox Animation Editor, KeyframeSequence can also be created by other plugins or even manually. Once uploaded to Roblox, Roblox assigns a Content ID that Animations use for the Animation.AnimationId property to refer to the uploaded KeyframeSequence.

Note, in most cases, you do not need to manipulate KeyframeSequences, as the animation editor covers most animation functionality. However, in some cases you may wish to generate an animation from a Script or build your own plugin. However, only Roblox Studio can use a KeyframeSequence created in such a way. If you wish to use such a KeyframeSequence, you will need to upload it to Roblox as described below.

KeyframeSequence Properties

KeyframeSequence.Priority and KeyframeSequence.Loop save the priority and looped animation settings for the sequence. Note that AnimationTrack properties can eventually overwrite these properties at playback time.

The last Keyframe in the sequence, meaning the Keyframe with the highest Keyframe.Time property, determines the length of an animation.

KeyframeSequence Structure

KeyframeSequences act as a container that hold Keyframes. Keyframes represent a 'key' frame in the animation, that are interpolated between during playback.

Keyframes contain Poses. Poses, specific to each BasePart being animated, contain the CFrame applied to the Motor6D connecting two parts. Poses match the BasePart they correspond with by name and apply their data to the Motor6D with this same-named part identified as Motor6D.P1 . For this reason, animations require distinct part names to play correctly.

Poses follow a structure based on joint hierarchy. The parent of each Pose corresponds to the Pose of the part it is attached to. In practice, this means the poses branch out from the root part. See below for a visual example.

Using KeyframeSequences when making animations

You must first upload KeyframeSequences to Roblox before they can be played in an experience. In Studio, right click on the KeyframeSequence and click 'Save to Roblox'. Alternatively, you can use the Plugin:SaveSelectedToRoblox() function. Either method will bring up the animation upload window and allow you to upload your KeyframeSequence as an animation.

In some cases, you may want to preview an Animation before uploading it to the Roblox site. You can generate a temporary id using KeyframeSequenceProvider:RegisterKeyframeSequence(). This will generate a hash id that can be used for localized animation testing.

Obtaining KeyframeSequences

In some cases you may wish to download the KeyframeSequence corresponding to an existing uploaded Animation. You can use AnimationClipProvider:GetAnimationClipAsync() to download an animation.

Code Samples

Create temporary animation

1local KeyframeSequenceProvider = game:GetService("KeyframeSequenceProvider")
2
3local function createPreviewAnimation(keyframeSequence)
4 local hashId = KeyframeSequenceProvider:RegisterKeyframeSequence(keyframeSequence)
5 if hashId then
6 local Animation = Instance.new("Animation")
7 Animation.AnimationId = hashId
8 return Animation
9 end
10end
11
12local keyframeSequence = Instance.new("KeyframeSequence")
13
14local animation = createPreviewAnimation(keyframeSequence)
15
16print(animation)
Get KeyframeSequence Length

1local function getSequenceLength(keyframeSequence)
2 local length = 0
3 for _, keyframe in pairs(keyframeSequence:GetKeyframes()) do
4 if keyframe.Time > length then
5 length = keyframe.Time
6 end
7 end
8 return length
9end
10
11local keyframeSequence = Instance.new("KeyframeSequence")
12
13getSequenceLength(keyframeSequence)
KeyframeSequence Instantiation

1-- create the keyframesequence
2local keyframeSequence = Instance.new("KeyframeSequence")
3keyframeSequence.Loop = false
4keyframeSequence.Priority = Enum.AnimationPriority.Action
5
6-- create a keyframe
7local keyframe = Instance.new("Keyframe")
8keyframe.Time = 0
9
10-- create sample poses
11local rootPose = Instance.new("Pose")
12rootPose.Name = "HumanoidRootPart"
13rootPose.Weight = 0
14
15local lowerTorsoPose = Instance.new("Pose")
16lowerTorsoPose.Name = "LowerTorso"
17lowerTorsoPose.Weight = 1
18
19-- set the sequence hierarchy
20rootPose:AddSubPose(lowerTorsoPose) -- lowerTorsoPose.Parent = rootPose
21keyframe:AddPose(rootPose) -- rootPose.Parent = keyframe
22keyframeSequence:AddKeyframe(keyframe) -- keyframe.Parent = keyframeSequence
23
24-- parent the sequence
25keyframeSequence.Parent = workspace

Summary

Properties

Contains the hip height of the Humanoid of the model that was used to author this KeyframeSequence.

HIDDEN

Events

Methods

AddKeyframe(keyframe: Instance): void  

Adds a Keyframe to the KeyframeSequence by parenting it to the KeyframeSequence.


Returns an array that contains all Keyframes contained in a KeyframeSequence.

RemoveKeyframe(keyframe: Instance): void  

This function removes a Keyframe from the KeyframeSequence by setting its parent to nil.

Properties

AuthoredHipHeight

Contains the hip height of the Humanoid of the model that was used to author this KeyframeSequence. Default value is 1.35 since that is the hip height set for a standard R15 Character|character.

Events

Methods

AddKeyframe

void

This function adds a Keyframe to the KeyframeSequence by parenting it to the KeyframeSequence. It is functionally identical to setting the Keyframe's Instance.Parent to the KeyframeSequence.

Note, this function will not error when called with an instance other than a Keyframe as the keyframe parameter and will parent it successfully.

Parameters

keyframe: Instance

The Keyframe to be added.


Returns

void

Code Samples

KeyframeSequence Instantiation

1-- create the keyframesequence
2local keyframeSequence = Instance.new("KeyframeSequence")
3keyframeSequence.Loop = false
4keyframeSequence.Priority = Enum.AnimationPriority.Action
5
6-- create a keyframe
7local keyframe = Instance.new("Keyframe")
8keyframe.Time = 0
9
10-- create sample poses
11local rootPose = Instance.new("Pose")
12rootPose.Name = "HumanoidRootPart"
13rootPose.Weight = 0
14
15local lowerTorsoPose = Instance.new("Pose")
16lowerTorsoPose.Name = "LowerTorso"
17lowerTorsoPose.Weight = 1
18
19-- set the sequence hierarchy
20rootPose:AddSubPose(lowerTorsoPose) -- lowerTorsoPose.Parent = rootPose
21keyframe:AddPose(rootPose) -- rootPose.Parent = keyframe
22keyframeSequence:AddKeyframe(keyframe) -- keyframe.Parent = keyframeSequence
23
24-- parent the sequence
25keyframeSequence.Parent = workspace

GetKeyframes

GetKeyframes returns an array that contains all Keyframes that have been added to a KeyframeSequence.


Returns

An array of Keyframes.

Code Samples

Get KeyframeSequence Length

1local function getSequenceLength(keyframeSequence)
2 local length = 0
3 for _, keyframe in pairs(keyframeSequence:GetKeyframes()) do
4 if keyframe.Time > length then
5 length = keyframe.Time
6 end
7 end
8 return length
9end
10
11local keyframeSequence = Instance.new("KeyframeSequence")
12
13getSequenceLength(keyframeSequence)

RemoveKeyframe

void

This function removes a Keyframe from the KeyframeSequence by setting its parent to nil. It is functionally identical to setting the keyframe's parent to nil.

This sets the Keyframe's parent to nil, but does not destroy it. This means, provided another reference to the keyframe remains, it can be re-parented later.

Note, this function will not error when called with an Instance other than a Keyframe as the keyframe parameter.

Parameters

keyframe: Instance

The Keyframe to be removed.


Returns

void

Code Samples

KeyframeSequence RemoveKeyframe

1local keyframeSequence = Instance.new("KeyframeSequence")
2keyframeSequence.Parent = workspace
3
4local keyframe = Instance.new("Keyframe")
5
6keyframeSequence:AddKeyframe(keyframe)
7
8task.wait(2)
9
10keyframeSequence:AddKeyframe(keyframe)