Keyframe

Show Deprecated

A Keyframe holds the Poses applied to joints in a Model at a given point of time in an animation. Keyframes are interpolated between during animation playback.

Note, in most cases developers do not need to manipulate KeyframeSequences as the animation editor covers most animation functionality. However, in some cases a developer may wish to generate an animation from a Script or build their own plugin.

Structure

Keyframes are held within a KeyframeSequence and contain Pose objects. The poses are named in accordance with the BaseParts they correspond to and are structured in terms of joint hierarchy. This means each Pose is parented to the Pose corresponding to the part it is attached to. See below for a visual example.

Note, as Poses are named in accordance with the BaseParts they correspond to, animations require distinct part names to play correctly.

Interpolation

During animation playback the poses in different keyframes are interpolated between. This allows a smooth animation to be created without needing to define every frame. Note, the style of interpolation is determined in the Pose object. The Keyframe object merely holds the Poses at a defined point of time in the animation (Keyframe.Time).

Code Samples

Keyframe Generate Poses

1local function generateKeyframe(model)
2 if not model.PrimaryPart then
3 warn("No primary part set")
4 return
5 end
6
7 local rootPart = model.PrimaryPart:GetRootPart()
8
9 if not rootPart then
10 warn("Root part not found")
11 return
12 end
13
14 local partsAdded = {}
15 partsAdded[rootPart] = true
16
17 local function addPoses(part, parentPose)
18 -- get all of the joints attached to the part
19 for _, joint in pairs(part:GetJoints()) do
20 -- we're only interested in Motor6Ds
21 if joint:IsA("Motor6D") then
22 -- find the connected part
23 local connectedPart = nil
24 if joint.Part0 == part then
25 connectedPart = joint.Part1
26 elseif joint.Part1 == part then
27 connectedPart = joint.Part0
28 end
29 if connectedPart then
30 -- make sure we haven't already added this part
31 if not partsAdded[connectedPart] then
32 partsAdded[connectedPart] = true
33 -- create a pose
34 local pose = Instance.new("Pose")
35 pose.Name = connectedPart.Name
36 parentPose:AddSubPose(pose)
37 -- recurse
38 addPoses(connectedPart, pose)
39 end
40 end
41 end
42 end
43 end
44
45 local keyframe = Instance.new("Keyframe")
46
47 -- populate the keyframe
48 local rootPose = Instance.new("Pose")
49 rootPose.Name = rootPart.Name
50 addPoses(rootPart, rootPose)
51 keyframe:AddPose(rootPose)
52
53 return keyframe
54end
55
56local character = script.Parent
57
58local keyframe = generateKeyframe(character)
59
60print(keyframe)

Summary

Properties

The Keyframe's time position (in seconds) in an animation. This determines the time at which the Poses inside the keyframe will be shown.

Events

Methods

AddMarker(marker: Instance): void  

Adds a KeyframeMarker to the Keyframe by parenting it to the keyframe.

AddPose(pose: Instance): void  

Adds a Pose to the Keyframe by parenting it to the keyframe.


Returns an array containing all KeyframeMarkers that have been added to the Keyframe.


Returns an array containing all Poses that have been added to a Keyframe.

RemoveMarker(marker: Instance): void  

Removes a KeyframeMarker from the Keyframe by settings its Instance.Parent to nil.

RemovePose(pose: Instance): void  

Removes a Pose from the Keyframe by setting its Instance.Parent to nil.

Properties

Time

This property gives the Keyframe's time position (in seconds) in an animation. This determines the time at which the Poses inside the keyframe will be shown.

Note the Keyframe with the highest time value in a KeyframeSequence is used to determine the length of the animation.

Events

Methods

AddMarker

void

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

Note, this function will not error when an instance other than a KeyframeMarker is given as the parameter and will parent it successfully.

More about Keyframes

Keyframe names do not need to be unique. For example, if an Animation has three keyframes named "Particles" the connected event returned by AnimationTrack:GetMarkerReachedSignal() will fire each time one of these keyframes is reached.

Keyframe names can be set in the Roblox Animation Editor when creating or editing an animation. They cannot however be set by a Script on an existing animation prior to playing it.

See also:

Parameters

marker: Instance

The KeyframeMarker being parented to the Keyframe.


Returns

void

No return.

Code Samples

Add Marker/Remove Marker

1local keyframe = Instance.new("Keyframe")
2keyframe.Parent = workspace
3
4local marker = Instance.new("KeyframeMarker")
5marker.Name = "FootStep"
6marker.Value = 100
7
8keyframe:AddMarker(marker) --marker.Parent = keyframe
9
10task.wait(2)
11
12keyframe:RemoveMarker(marker) --marker.Parent = nil

AddPose

void

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

Note, this function will not error when an instance other than a Pose is given as the pose parameter and will parent it successfully.

Parameters

pose: Instance

The Pose to be added.


Returns

void

Code Samples

Keyframe Generate Poses

1local function generateKeyframe(model)
2 if not model.PrimaryPart then
3 warn("No primary part set")
4 return
5 end
6
7 local rootPart = model.PrimaryPart:GetRootPart()
8
9 if not rootPart then
10 warn("Root part not found")
11 return
12 end
13
14 local partsAdded = {}
15 partsAdded[rootPart] = true
16
17 local function addPoses(part, parentPose)
18 -- get all of the joints attached to the part
19 for _, joint in pairs(part:GetJoints()) do
20 -- we're only interested in Motor6Ds
21 if joint:IsA("Motor6D") then
22 -- find the connected part
23 local connectedPart = nil
24 if joint.Part0 == part then
25 connectedPart = joint.Part1
26 elseif joint.Part1 == part then
27 connectedPart = joint.Part0
28 end
29 if connectedPart then
30 -- make sure we haven't already added this part
31 if not partsAdded[connectedPart] then
32 partsAdded[connectedPart] = true
33 -- create a pose
34 local pose = Instance.new("Pose")
35 pose.Name = connectedPart.Name
36 parentPose:AddSubPose(pose)
37 -- recurse
38 addPoses(connectedPart, pose)
39 end
40 end
41 end
42 end
43 end
44
45 local keyframe = Instance.new("Keyframe")
46
47 -- populate the keyframe
48 local rootPose = Instance.new("Pose")
49 rootPose.Name = rootPart.Name
50 addPoses(rootPart, rootPose)
51 keyframe:AddPose(rootPose)
52
53 return keyframe
54end
55
56local character = script.Parent
57
58local keyframe = generateKeyframe(character)
59
60print(keyframe)
Keyframe Add/Remove Pose

1local keyframe = Instance.new("Keyframe")
2keyframe.Parent = workspace
3
4local pose = Instance.new("Pose")
5pose.EasingStyle = Enum.PoseEasingStyle.Cubic
6pose.EasingDirection = Enum.PoseEasingDirection.Out
7
8local pose2 = Instance.new("Pose")
9pose2.EasingStyle = Enum.PoseEasingStyle.Cubic
10pose2.EasingDirection = Enum.PoseEasingDirection.Out
11
12keyframe:AddPose(pose) -- pose.Parent = keyframe
13
14task.wait(2)
15
16keyframe:RemovePose(pose) -- pose.Parent = nil
17
18task.wait(2)
19
20keyframe:AddPose(pose) -- pose.Parent = keyframe
21
22task.wait(2)
23
24pose:AddSubPose(pose2) -- pose2.Parent = pose
25
26task.wait(2)
27
28pose:RemoveSubPose(pose2) -- pose2.Parent = nil

GetMarkers

This function returns an array containing all KeyframeMarkers that have been added to the Keyframe. Note, this function will only return instances of type KeyframeMarker.

More about Keyframes

Keyframe names do not need to be unique. For example, if an Animation has three keyframes named "Particles" the connected event returned by AnimationTrack:GetMarkerReachedSignal() will fire each time one of these keyframes is reached.

Keyframe names can be set in the Roblox Animation Editor when creating or editing an animation. They cannot however be set by a Script on an existing animation prior to playing it.

See also:


Returns

An array containing all KeyframeMarkers that have been added to the Keyframe.

Code Samples

Get Keyframe Markers Attached to a Keyframe

1local keyframe = Instance.new("Keyframe")
2keyframe.Parent = workspace
3
4local marker1 = Instance.new("KeyframeMarker")
5marker1.Name = "FootStep"
6marker1.Value = 100
7
8local marker2 = Instance.new("KeyframeMarker")
9marker2.Name = "Wave"
10marker2.Value = 100
11
12keyframe:AddMarker(marker1) --marker.Parent = keyframe
13keyframe:AddMarker(marker2) --marker.Parent = keyframe
14
15local markers = keyframe:GetMarkers()
16for _, marker in pairs(markers) do
17 print(marker.Name)
18end

GetPoses

This function returns an array containing all Poses that have been added to a Keyframe.


Returns

An array of Poses.

Code Samples

Keyframe Reset Poses

1local function resetPoses(parent)
2 -- both functions are equivalent to GetChildren
3 local poses = parent:IsA("Keyframe") and parent:GetPoses() or parent:IsA("Pose") and parent:GetSubPoses()
4
5 for _, pose in pairs(poses) do
6 if pose:IsA("Pose") then
7 pose.CFrame = CFrame.new()
8 -- recurse
9 resetPoses(pose)
10 end
11 end
12end

RemoveMarker

void

This function removes a KeyframeMarker from the Keyframe by settings its Instance.Parent to nil.

The KeyframeMarker's Instance.Parent is set to nil but it is not destroyed. This means, provided the marker is referenced it can be re-parented later.

Note, this function will not error when an instance other than a KeyframeMarker is given as the parameter.

More about Keyframes

Keyframe names do not need to be unique. For example, if an Animation has three keyframes named "Particles" the connected event returned by AnimationTrack:GetMarkerReachedSignal() will fire each time one of these keyframes is reached.

Keyframe names can be set in the Roblox Animation Editor when creating or editing an animation. They cannot however be set by a Script on an existing animation prior to playing it.

See also:

Parameters

marker: Instance

The marker being removed from the Keyframe.


Returns

void

No return.

Code Samples

Add Marker/Remove Marker

1local keyframe = Instance.new("Keyframe")
2keyframe.Parent = workspace
3
4local marker = Instance.new("KeyframeMarker")
5marker.Name = "FootStep"
6marker.Value = 100
7
8keyframe:AddMarker(marker) --marker.Parent = keyframe
9
10task.wait(2)
11
12keyframe:RemoveMarker(marker) --marker.Parent = nil

RemovePose

void

This function removes a Pose from the Keyframe by setting its Instance.Parent to nil.

The Pose's Instance.Parent is set to nil, but it is not destroyed. This means, provided the pose is referenced it can be re-parented later.

Note, this function will not error when an instance other than a Pose is given as the pose parameter.

Parameters

pose: Instance

The Pose to be removed.


Returns

void

Code Samples

Keyframe Add/Remove Pose

1local keyframe = Instance.new("Keyframe")
2keyframe.Parent = workspace
3
4local pose = Instance.new("Pose")
5pose.EasingStyle = Enum.PoseEasingStyle.Cubic
6pose.EasingDirection = Enum.PoseEasingDirection.Out
7
8local pose2 = Instance.new("Pose")
9pose2.EasingStyle = Enum.PoseEasingStyle.Cubic
10pose2.EasingDirection = Enum.PoseEasingDirection.Out
11
12keyframe:AddPose(pose) -- pose.Parent = keyframe
13
14task.wait(2)
15
16keyframe:RemovePose(pose) -- pose.Parent = nil
17
18task.wait(2)
19
20keyframe:AddPose(pose) -- pose.Parent = keyframe
21
22task.wait(2)
23
24pose:AddSubPose(pose2) -- pose2.Parent = pose
25
26task.wait(2)
27
28pose:RemoveSubPose(pose2) -- pose2.Parent = nil