PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar
  1. apireference
  2. animations
  3. animationtrack

KeyframeReached

AnimationTrack

Fires every time playback of an AnimationTrack reaches a Keyframe that does not have the default name - “Keyframe”.

This event allows a developer to run code at predefined points in an animation (set by Keyframe names). This allows the default functionality of Roblox animations to be expanded upon by adding Sounds or ParticleEffects at different points in an animation.

Keyframe names do not need to be unique. For example, if an Animation has three keyframes named “Particles” the KeyframeReached event 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.

Parameters

Name Type Default Description

keyframeName

string

The name of the Keyframe reached.

Code Samples

AnimationTrack KeyframeReached

Create a localscript in StarterGui and paste the following code to try out this example.

The code in this sample will play an animation on the local character and print whenever a keyframe that is not named “Keyframe” is reached.

local player = game.Players:GetChildren()[1]
local character = game.Workspace:WaitForChild(player.Name)
local humanoid = character:WaitForChild("Humanoid")
 
local anim = Instance.new("Animation")
anim.AnimationId = "rbxassetid://437855404"
local animTrack = humanoid:LoadAnimation(anim)
 
animTrack.KeyframeReached:Connect(function(keyframeName)
	print("Keyframe reached:"..keyframeName)
end)
animTrack:Play()

Listen For Animation Effects

The function in the following code sample provides an example of how the AnimationTrack.KeyframeReached event can be used to link different effects to an animation.

The function listens for any animations being played on the Humanoid (or AnimationController), and when a new animation is played listens for a keyframe named ‘Effect’ being reached. When a keyframe named ‘Effect’ is reached some basic particles will be emitted. Once the animation has stopped the connections used by the function are disconnected, in line with best practice to avoid memory leaks.

Although the particle effect in this sample is very simple, it could be substituted for a range of more complicated effects using the Sound, Beam, ParticleEffect or other objects. Additionally, in many cases the developer may only care about effects on one specific animation (rather than every animation played on a Humanoid). In this case, only the KeyframeReached portion of this sample would be needed.

local Debris = game:GetService("Debris")

local function listenForAnimationEffects(humanoid) -- would also work for an AnimationController
	-- listen for new animations being played on the Humanoid
	humanoid.AnimationPlayed:Connect(function(animationTrack)
		local keyframeConnection = nil
		-- listen for the 'Effect' keyframe being reached
		keyframeConnection = animationTrack.KeyframeReached:Connect(function(keyframeName)
			if keyframeName == "Effect" then
				-- make sure the Humanoid RootPart exists
				if humanoid.RootPart then
					-- create a basic particle effect
					local particles = Instance.new("ParticleEmitter", humanoid.RootPart)
					particles.Rate = 0
					particles:Emit(10)
					Debris:AddItem(particles, 2)
				end
			end
		end)
		local stoppedConnection = nil
		stoppedConnection = animationTrack.Stopped:Connect(function()
			-- clean up old connections to stop memory leaks
			keyframeConnection:Disconnect()
			stoppedConnection:Disconnect()
		end)
	end)
end