AnimationTrack

顯示已棄用項目

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

無法建立

在 Animator 上控制動畫的播放。此對象無法創建，而是由 Animator:LoadAnimation() 方法返回。

概要

屬性

檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目

方法

檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目

活動

檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目

屬性

Animation

Animation
唯讀
未複製
平行讀取

用於創建此 AnimationTrack 的 Animation 對象。要創建 AnimationTrack ，您必須使用 Animation 方法將 Animator 對象載入到 Animator:LoadAnimation() 上。

範例程式碼

The following code sample prints the name of an animation whenever an AnimationTrack plays on a Humanoid. This script can be placed in a model with a Humanoid child.

Listen For New Animations
local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



animator.AnimationPlayed:Connect(function(animationTrack)

	local animationName = animationTrack.Animation.Name

	print("Animation playing " .. animationName)

end)

IsPlaying

boolean
唯讀
未複製
平行讀取

一個只讀屬性，在 AnimationTrack 播放時返回真值。

開發人員可以使用此屬性來檢查是否已經播放動畫（因為這會導致它重新啟動）。如果開發者想要獲得所有播放 AnimationTracks 在 Animator 或 Humanoid 上，他們應該使用 Animator:GetPlayingAnimationTracks()

範例程式碼

This code sample includes a simple function that will play an AnimationTrack if it is not playing, or otherwise adjust its speed and weight to match the new parameters given.

AnimationTrack IsPlaying
local function playOrAdjust(animationTrack, fadeTime, weight, speed)

	if not animationTrack.IsPlaying then

		animationTrack:Play(fadeTime, weight, speed)

	else

		animationTrack:AdjustSpeed(speed)

		animationTrack:AdjustWeight(weight, fadeTime)

	end

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



playOrAdjust(animationTrack, 1, 0.6, 1)

Length

number
唯讀
未複製
平行讀取

一個只讀屬性，返回 AnimationTrack 的長度（以秒為單位）。直到動畫完全載入為止，此會返回 0，因此可能無法立即使用。

當 AnimationTrack.Speed 的 AnimationTrack 等於 1 時，動畫將需要 AnimationTrack.Length 秒才能完成。

範例程式碼

The following function will play an AnimationTrack for a specific duration. This is done by changing the speed of the animation to the length of the animation divided by the desired playback duration. This could be used in situations where a developer wants to play a standard animation for different duration (for example, recharging different abilities).

Playing Animation for a Specific Duration
local function playAnimationForDuration(animationTrack, duration)

	local speed = animationTrack.Length / duration

	animationTrack:Play()

	animationTrack:AdjustSpeed(speed)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765000"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animationTrack = animator:LoadAnimation(animation)



playAnimationForDuration(animationTrack, 3)

Looped

boolean
平行讀取

此屬性設置動畫在完成後是否會重複。如果在播放結果時變更，動畫結束後才會生效。

循環屬性對於 AnimationTrack 默認使用在動畫編輯器中設置的方式。但是，此屬性可以更改，允許在遊戲運行時控制 AnimationTrack 。循環也正確地處理反向播放的動畫（負 AnimationTrack.Speed）。在第一個關鍵幀被達到之後，它將在最後一個關鍵格重新啟動。

這個屬性讓開發人員可以擁有一個循環和非循環的同一動畫變體，而無需上傳兩個版本到 Roblox。

範例程式碼

The animation in this example normally loops. After the player and the animation are loaded the animation is played in a non-looped fashion then in a looped fashion.

Animation Looping
local Players = game:GetService("Players")



local localPlayer = Players.LocalPlayer



while not localPlayer.Character do

	task.wait()

end



local character = localPlayer.Character

local humanoid = character:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507770453"



local animationTrack = animator:LoadAnimation(animation)

animationTrack.Looped = false

task.wait(3)

animationTrack:Play()

task.wait(4)

animationTrack.Looped = true

animationTrack:Play()

The function in this code sample will play an AnimationTrack on a loop, for a specific number of loops, before stopping the animation.

In some cases the developer may want to stop a looped animation after a certain number of loops have completed, rather than after a certain amount of time. This is where the DidLoop event can be used.

Play AnimationTrack for a Number of Loops
local function playForNumberLoops(animationTrack, number)

	animationTrack.Looped = true

	animationTrack:Play()

	local numberOfLoops = 0

	local connection = nil

	connection = animationTrack.DidLoop:Connect(function()

		numberOfLoops = numberOfLoops + 1

		print("loop: ", numberOfLoops)

		if numberOfLoops >= number then

			animationTrack:Stop()

			connection:Disconnect() -- it's important to disconnect connections when they are no longer needed

		end

	end)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



playForNumberLoops(animationTrack, 5)

Priority

Enum.AnimationPriority
平行讀取

此屬性設置 AnimationTrack 的優先級。取決於這個設置是什麼，一次播放多個動畫時，將查看此屬性來決定哪個 Keyframe Poses 應該在一個上面播放。

對於 AnimationTrack 的優先級屬性預設為從 Studio 的 動畫編輯器 設置和發布的方式。它使用 Enum.AnimationPriority ，它有 7 個優先級：

  1. 行動4（最高優先級）
  2. 行動3
  3. 行動2
  4. 行動
  5. 運動
  6. 閒置
  7. 核心 (最低優先級)

正確設置動畫優先級，通過編輯器或通過此屬性，可以讓多個動畫無需碰撞即可播放。當兩個正在播放的動畫將目標指向以不同方式移動相同的肢體時，最高優先級的 AnimationTrack 將會顯示。如果兩個動畫都有相同的優先級，軌道的重量將用於結合動畫。

此屬性也允許開發人員在不同優先級下播放相同的動畫，無需上傳額外版本到 Roblox。

Speed

number
唯讀
未複製
平行讀取

一個 AnimationTrack 的速度是一個只能讀取的屬性，可以提供 AnimationTrack 的當前播放速度。這有一個預設值 1。當速度等於 1 時，動畫完成所需的時間等於 AnimationTrack.Length (以秒為單位)。

如果速度被調整，則實際播放所需的時間可以通過將長度除以速度來計算。速度是一個沒有單位的數量。

速度可用於將動畫長度與不同遊戲事件鏈結（例如重新充能能力），無需上傳不同版本的相同動畫。

此屬性只能閱讀，您可以使用 AnimationTrack:AdjustSpeed() 來更改它。

範例程式碼

In this example a player and an animation is loaded. The Length of an AnimationTrack determines how long the track would take to play if the speed is at 1. If the speed is adjusted, then the actual time it will take a track to play can be computed by dividing the length by the speed.

Animation Speed
local ContentProvider = game:GetService("ContentProvider")

local Players = game:GetService("Players")



local localPlayer = Players.LocalPlayer

while not localPlayer.Character do

	task.wait()

end

local character = localPlayer.Character

local humanoid = character:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507770453"



ContentProvider:PreloadAsync({ animation })



local animationTrack = animator:LoadAnimation(animation)



local normalSpeedTime = animationTrack.Length / animationTrack.Speed

animationTrack:AdjustSpeed(3)

local fastSpeedTime = animationTrack.Length / animationTrack.Speed



print("At normal speed the animation will play for", normalSpeedTime, "seconds")

print("At 3x speed the animation will play for", fastSpeedTime, "seconds")

The following function will play an AnimationTrack for a specific duration. This is done by changing the speed of the animation to the length of the animation divided by the desired playback duration. This could be used in situations where a developer wants to play a standard animation for different duration (for example, recharging different abilities).

Playing Animation for a Specific Duration
local function playAnimationForDuration(animationTrack, duration)

	local speed = animationTrack.Length / duration

	animationTrack:Play()

	animationTrack:AdjustSpeed(speed)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765000"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animationTrack = animator:LoadAnimation(animation)



playAnimationForDuration(animationTrack, 3)

TimePosition

number
未複製
平行讀取

返回 AnimationTrack 在播放其源動畫時在秒鐘內的位置，該動畫會通過播放其源動畫來傳達。可設為使軌道跳到動畫中特定時刻。

時間位置可以設為前往動畫的特定點，但必須播放才能如此。它也可以與 AnimationTrack:AdjustSpeed() 一起使用，以在指定點凍結動畫 (將速度設為 0)。

範例程式碼

The following code sample includes two functions that demonstrate how AdjustSpeed and TimePosition can be used to freeze an animation at a particular point.

The first function freezes an animation at a particular point in time (defined in seconds). The second freezes at it at a percentage (between 0 or 100) by multiplying the percentage by the track length.

As TimePosition can not be used when an AnimationTrack is not playing, the functions check to make sure the animation is playing before proceeding.

Freeze Animation at Position
function freezeAnimationAtTime(animationTrack, timePosition)

	if not animationTrack.IsPlaying then

		-- Play the animation if it is not playing

		animationTrack:Play()

	end

	-- Set the speed to 0 to freeze the animation

	animationTrack:AdjustSpeed(0)

	-- Jump to the desired TimePosition

	animationTrack.TimePosition = timePosition

end



function freezeAnimationAtPercent(animationTrack, percentagePosition)

	if not animationTrack.IsPlaying then

		-- Play the animation if it is not playing

		animationTrack:Play()

	end

	-- Set the speed to 0 to freeze the animation

	animationTrack:AdjustSpeed(0)

	-- Jump to the desired TimePosition

	animationTrack.TimePosition = (percentagePosition / 100) * animationTrack.Length

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



freezeAnimationAtTime(animationTrack, 0.5)

freezeAnimationAtPercent(animationTrack, 50)

WeightCurrent

number
唯讀
未複製
平行讀取

當在 AnimationTrack 設置重量時,重量不會立即變更,但會從重量當前移動到AnimationTrack.WeightTarget。執行此操作所需的時間由播放動畫或調整重量時提供的 fadeTime 參數決定。

重量當前可以與 AnimationTrack.WeightTarget 對比，以查看是否已達到所需重量。請注意，這些值不應與 == 運算符進行等值檢查，因為這兩個值都是浮點。若要查看 WeightCurrent 是否已達到目標重量，建議查看這些值之間的距離是否足夠小 (見下方代碼示例)。

動畫權重系統用於確定如何AnimationTracks在同一優先級下播放的動畫會融合在一起。預設重量是一，在重量為零的 AnimationTrack 上沒有運動可見。在任何時間點顯示的姿勢由所有 Poses 和每個 AnimationTrack 的重量平均值決定。在大多數情況下，混合動畫不需要，使用 AnimationTrack.Priority 更適合。

範例程式碼

This code sample loads two animations onto the local player's Humanoid and demonstrates how the fadeTime paramater in AnimationTrack.Play determines how long it takes for an AnimationTrack's WeightCurrent to reach it's WeightTarget.

As WeightCurrent and WeightTarget are floats the == operator cannot be used to compare, instead it is more appropriate to check that the difference between them is sufficiently small to assume the weight fade has completed.

WeightCurrent and WeightTarget
local Players = game:GetService("Players")



local localPlayer = Players.LocalPlayer



while not localPlayer.Character do

	task.wait()

end

local character = localPlayer.Character



local humanoid = character:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animation1 = Instance.new("Animation")

animation1.AnimationId = "rbxassetid://507770453"



local animation2 = Instance.new("Animation")

animation2.AnimationId = "rbxassetid://507771019"



task.wait(3) -- arbitrary wait time to allow the character to fall into place



local animationTrack1 = animator:LoadAnimation(animation1)

local animationTrack2 = animator:LoadAnimation(animation2)



animationTrack1.Priority = Enum.AnimationPriority.Movement

animationTrack2.Priority = Enum.AnimationPriority.Action



animationTrack1:Play(0.1, 5, 1)

animationTrack2:Play(10, 3, 1)



local done = false

while not done and task.wait(0.1) do

	if math.abs(animationTrack2.WeightCurrent - animationTrack2.WeightTarget) < 0.001 then

		print("got there")

		done = true

	end

end

WeightTarget

number
唯讀
未複製
平行讀取

動畫跟蹤。重量目標是一個只能讀取的屬性，可以提供 AnimationTrack 的當前重量。它的默认值為 1，當 AnimationTrack:Play() 、 AnimationTrack:Stop() 或 AnimationTrack:AdjustWeight() 被呼叫時設置。當在 AnimationTrack 設置重量時,重量不會立即變更,但會從重量當前移動到AnimationTrack.WeightTarget 。執行此操作所需的時間由播放動畫或調整重量時提供的 fadeTime 參數決定。

重量當前可以與 AnimationTrack.WeightTarget 對比，以查看是否已達到所需重量。請注意，這些值不應與 == 運算符進行等值檢查，因為這兩個值都是浮點。若要查看 WeightCurrent 是否已達到目標重量，建議查看這些值之間的距離是否足夠小 (見下方代碼示例)。

動畫權重系統用於確定如何AnimationTracks在同一優先級下播放的動畫會融合在一起。預設重量是一，在重量為零的 AnimationTrack 上沒有運動可見。在任何時間點顯示的姿勢由所有 Poses 和每個 AnimationTrack 的重量平均值決定。在大多數情況下，混合動畫不需要，使用 AnimationTrack.Priority 更適合。

範例程式碼

This code sample loads two animations onto the local player's Humanoid and demonstrates how the fadeTime paramater in AnimationTrack.Play determines how long it takes for an AnimationTrack's WeightCurrent to reach it's WeightTarget.

As WeightCurrent and WeightTarget are floats the == operator cannot be used to compare, instead it is more appropriate to check that the difference between them is sufficiently small to assume the weight fade has completed.

WeightCurrent and WeightTarget
local Players = game:GetService("Players")



local localPlayer = Players.LocalPlayer



while not localPlayer.Character do

	task.wait()

end

local character = localPlayer.Character



local humanoid = character:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animation1 = Instance.new("Animation")

animation1.AnimationId = "rbxassetid://507770453"



local animation2 = Instance.new("Animation")

animation2.AnimationId = "rbxassetid://507771019"



task.wait(3) -- arbitrary wait time to allow the character to fall into place



local animationTrack1 = animator:LoadAnimation(animation1)

local animationTrack2 = animator:LoadAnimation(animation2)



animationTrack1.Priority = Enum.AnimationPriority.Movement

animationTrack2.Priority = Enum.AnimationPriority.Action



animationTrack1:Play(0.1, 5, 1)

animationTrack2:Play(10, 3, 1)



local done = false

while not done and task.wait(0.1) do

	if math.abs(animationTrack2.WeightCurrent - animationTrack2.WeightTarget) < 0.001 then

		print("got there")

		done = true

	end

end
檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目

方法

AdjustSpeed

()

此功能會更改動畫的 AnimationTrack.Speed 。速度的正值播放動畫向前，負值播放向後，0則暫停它。

動畫軌道的初始速度設為 AnimationTrack:Play() 中的參數。但播放時，可以使用「調整速度」來變更軌道的速度。當速度等於 1 時，動畫完成所需的時間等於 AnimationTrack.Length (以秒為單位)。

調整時，實際播放所需的時間可以通過將長度除以速度來計算。速度是一個無單位數量。

速度可以用來將動畫長度與不同的遊戲事件鏈結（例如重新充能能力），而無需上傳不同版本的相同動畫。

參數

speed: number

動畫的播放速度將更改為。

預設值：1

返回

()

範例程式碼

The following function will play an AnimationTrack for a specific duration. This is done by changing the speed of the animation to the length of the animation divided by the desired playback duration. This could be used in situations where a developer wants to play a standard animation for different duration (for example, recharging different abilities).

Playing Animation for a Specific Duration
local function playAnimationForDuration(animationTrack, duration)

	local speed = animationTrack.Length / duration

	animationTrack:Play()

	animationTrack:AdjustSpeed(speed)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765000"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animationTrack = animator:LoadAnimation(animation)



playAnimationForDuration(animationTrack, 3)

In this example a player and an animation is loaded. The Length of an AnimationTrack determines how long the track would take to play if the speed is at 1. If the speed is adjusted, then the actual time it will take a track to play can be computed by dividing the length by the speed.

Animation Speed
local ContentProvider = game:GetService("ContentProvider")

local Players = game:GetService("Players")



local localPlayer = Players.LocalPlayer

while not localPlayer.Character do

	task.wait()

end

local character = localPlayer.Character

local humanoid = character:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507770453"



ContentProvider:PreloadAsync({ animation })



local animationTrack = animator:LoadAnimation(animation)



local normalSpeedTime = animationTrack.Length / animationTrack.Speed

animationTrack:AdjustSpeed(3)

local fastSpeedTime = animationTrack.Length / animationTrack.Speed



print("At normal speed the animation will play for", normalSpeedTime, "seconds")

print("At 3x speed the animation will play for", fastSpeedTime, "seconds")

AdjustWeight

()

變更動畫的重量，其中可選擇的 fadeTime 參數決定 AnimationTrack.WeightCurrent 到達 AnimationTrack.WeightTarget 所需的時間長度。

當在 AnimationTrack 設置重量時,重量不會立即變更,但會從重量當前移動到AnimationTrack.WeightTarget。執行此操作所需的時間由播放動畫或調整重量時提供的 fadeTime 參數決定。

重量當前可以與 AnimationTrack.WeightTarget 對比，以查看是否已達到所需重量。請注意，這些值不應與 == 運算符進行等值檢查，因為這兩個值都是浮點。若要查看 WeightCurrent 是否已達到目標重量，建議查看這些值之間的距離是否足夠小 (見下方代碼示例)。

動畫權重系統用於確定如何AnimationTracks在同一優先級下播放的動畫會融合在一起。預設重量是一，在重量為零的 AnimationTrack 上沒有運動可見。在任何時間點顯示的姿勢由所有 Poses 和每個 AnimationTrack 的重量平均值決定。請參見下方的動畫融合實例。在大多數情況下，混合動畫不需要，使用 AnimationTrack.Priority 更適合。

參數

weight: number

動畫要變更的重量。

預設值：1
fadeTime: number

動畫會在舊重量和新重量之間消失的時間長度。

預設值：0.100000001

返回

()

範例程式碼

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.AdjustWeight works. In most cases, if a developer wishes to yield over the fadeTime it is recommended they use wait(fadeTime).

AnimationTrack Change Weight
local function changeWeight(animationTrack, weight, fadeTime)

	animationTrack:AdjustWeight(weight, fadeTime)

	local startTime = tick()

	while math.abs(animationTrack.WeightCurrent - weight) > 0.001 do

		task.wait()

	end

	print("Time taken to change weight " .. tostring(tick() - startTime))

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



changeWeight(animationTrack, 0.6, 1)

GetMarkerReachedSignal

RBXScriptSignal

此功能返回與 event 事件相似的 AnimationTrack.KeyframeReached，除了只在 KeyframeMarker 中發射時，指定的 animation 被擊中時才會發射外。差異允許更大控制事件何時發觸發。

要了解有關使用此功能的更多信息，請參閱 動畫事件 在 動畫編輯器 文章中。

也見：

參數

name: string

用於創建信號名稱的 KeyframeMarker 名稱正在被創建。與 Keyframe 的名稱不要混淆。

預設值：""

返回

RBXScriptSignal

當動畫達到創建的 KeyframeMarker 時創建和發射的信號。與 Keyframe 的名稱不要混淆。

範例程式碼

This LocalScript code waits for the local player's Humanoid object to load, then it creates a new Animation instance with the proper Animation.AnimationId. The animation is then loaded onto the humanoid, creating an AnimationTrack, and the track is played with AnimationTrack:Play(). Following that, the AnimationTrack:GetMarkerReachedSignal() function detects when the "KickEnd" marker is hit.

Listening to Keyframe Markers
local Players = game:GetService("Players")



local player = Players.LocalPlayer

local character = player.Character or player.Character:Wait()

local humanoid = character:WaitForChild("Humanoid")



-- Create new "Animation" instance

local kickAnimation = Instance.new("Animation")

-- Set its "AnimationId" to the corresponding animation asset ID

kickAnimation.AnimationId = "rbxassetid://2515090838"



-- Load animation onto the humanoid

local kickAnimationTrack = humanoid:LoadAnimation(kickAnimation)



-- Play animation track

kickAnimationTrack:Play()



-- If a named event was defined for the animation, connect it to "GetMarkerReachedSignal()"

kickAnimationTrack:GetMarkerReachedSignal("KickEnd"):Connect(function(paramString)

	print(paramString)

end)

GetTargetInstance

Instance

參數

name: string
預設值：""

返回

Instance

GetTargetNames

Array

返回

Array

GetTimeOfKeyframe

number

返回指定名稱的第一個 Keyframe 在 AnimationTrack 的時間位置。如果多個 Keyframes 分享相同名稱，將返回動畫中最早的一個。

此功能會在使用無效的鑰匙框名稱 (例如不存在) 或基礎的 Animation 尚未載入時返回錯誤。為了解決這個問題，請確保只使用正確的鑰匙框名稱，並在呼叫此函數之前載入動畫。

要檢查動畫是否已加載，請確認 AnimationTrack.Length 是否大於零。

參數

keyframeName: string

與 Keyframe 相關的名稱，需要找到。

預設值：""

返回

number

時間，以秒為單位，Keyframe在正常播放速度下發生。

範例程式碼

This sample includes a function that will jump to the first keyframe of a specified name in an AnimationTrack.

As AnimationTrack.TimePosition cannot be set while the animation is not playing the function first checks to see if the animation is playing.

This sample will only work once an Animation has loaded.

Jump To Keyframe
local function jumpToKeyframe(animationTrack, keyframeName)

	local timePosition = animationTrack:GetTimeOfKeyframe(keyframeName)

	if not animationTrack.IsPlaying then

		animationTrack:Play()

	end

	animationTrack.TimePosition = timePosition

end



local ANIMATION_ID = 0

local KEYFRAME_NAME = "Test"



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://" .. ANIMATION_ID



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



jumpToKeyframe(animationTrack, KEYFRAME_NAME)

Play

()

當 AnimationTrack:Play() 被呼叫時，軌道的動畫將開始播放，動畫重量將從 0 增加到指定重量(默認為 1)，過渡時間為指定時間(默認為 0.1)。

AnimationTrack 將播放的速度由速度參數決定(默認為 1)。當速度等於 1 時，軌道完成所需的秒數等於軌道的 AnimationTrack.Length 屬性。例如，2的速度會讓軌道播放速度翻倍。

動畫的重量和速度也可以在動畫開始播放後使用 AnimationTrack:AdjustWeight() 和 AnimationTrack:AdjustSpeed() 方法進行更改。

如果開發者想使用 AnimationTrack.TimePosition 在特定點開始動畫，這很重要，動畫必須在此之前播放。

參數

fadeTime: number

動畫的重量應在何時褪色。

預設值：0.100000001
weight: number

動畫將播放的重量。

預設值：1
speed: number

動畫的播放速度。

預設值：1

返回

()

範例程式碼

The following function will play an AnimationTrack for a specific duration. This is done by changing the speed of the animation to the length of the animation divided by the desired playback duration. This could be used in situations where a developer wants to play a standard animation for different duration (for example, recharging different abilities).

Playing Animation for a Specific Duration
local function playAnimationForDuration(animationTrack, duration)

	local speed = animationTrack.Length / duration

	animationTrack:Play()

	animationTrack:AdjustSpeed(speed)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765000"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")



local animationTrack = animator:LoadAnimation(animation)



playAnimationForDuration(animationTrack, 3)

The following code sample includes two functions that demonstrate how AdjustSpeed and TimePosition can be used to freeze an animation at a particular point.

The first function freezes an animation at a particular point in time (defined in seconds). The second freezes at it at a percentage (between 0 or 100) by multiplying the percentage by the track length.

As TimePosition can not be used when an AnimationTrack is not playing, the functions check to make sure the animation is playing before proceeding.

Freeze Animation at Position
function freezeAnimationAtTime(animationTrack, timePosition)

	if not animationTrack.IsPlaying then

		-- Play the animation if it is not playing

		animationTrack:Play()

	end

	-- Set the speed to 0 to freeze the animation

	animationTrack:AdjustSpeed(0)

	-- Jump to the desired TimePosition

	animationTrack.TimePosition = timePosition

end



function freezeAnimationAtPercent(animationTrack, percentagePosition)

	if not animationTrack.IsPlaying then

		-- Play the animation if it is not playing

		animationTrack:Play()

	end

	-- Set the speed to 0 to freeze the animation

	animationTrack:AdjustSpeed(0)

	-- Jump to the desired TimePosition

	animationTrack.TimePosition = (percentagePosition / 100) * animationTrack.Length

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



freezeAnimationAtTime(animationTrack, 0.5)

freezeAnimationAtPercent(animationTrack, 50)

SetTargetInstance

()

參數

name: string
預設值：""
target: Instance
預設值：""

返回

()

Stop

()

停止 AnimationTrack 。一旦呼叫，動畫的重量將在指定的時間長度內移向零，由可選擇的 fadeTime 參數決定。例如，如果 Stop() 被稱為 fadeTime 的 2 ，則需要兩秒鐘才能將軌道的重量達到零並完全結束其效果。請注意，無論動畫的初始重量如何，這都會是如此。

不建議在嘗試覆蓋此效果並立即終止動畫時使用 的 ，因為這會導致關節在原空間凍結。如果必須立即結束，請確保你的裝備中的 Motor.MaxVelocity 的 Motor6Ds 足夠高，以便它們能夠正確地捕捉。

參數

fadeTime: number

動畫重量將在何時、以秒為單位，消失掉的時間。

預設值：0.100000001

返回

()

範例程式碼

This code sample includes a function that stops an AnimationTrack with a specific fadeTime, and yields until the fade is completed and the weight of the AnimationTrack is equal to zero.

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

AnimationTrack Stop
local function fadeOut(animationTrack, fadeTime)

	animationTrack:Stop(fadeTime)

	local startTime = tick()

	while animationTrack.WeightCurrent > 0 do

		task.wait()

	end

	local timeTaken = tick() - startTime

	print("Time taken for weight to reset: " .. tostring(timeTaken))

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



animationTrack:Play()



fadeOut(animationTrack, 1)
檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目

活動

DidLoop

此事件會在下次更新時發生，當循環 AnimationTrack 完成一個循環時發生。

目前它也可能在非循環動畫軌道的正確結束發射，但這種行為不應該被依賴。


範例程式碼

The function in this code sample will play an AnimationTrack on a loop, for a specific number of loops, before stopping the animation.

In some cases the developer may want to stop a looped animation after a certain number of loops have completed, rather than after a certain amount of time. This is where the DidLoop event can be used.

Play AnimationTrack for a Number of Loops
local function playForNumberLoops(animationTrack, number)

	animationTrack.Looped = true

	animationTrack:Play()

	local numberOfLoops = 0

	local connection = nil

	connection = animationTrack.DidLoop:Connect(function()

		numberOfLoops = numberOfLoops + 1

		print("loop: ", numberOfLoops)

		if numberOfLoops >= number then

			animationTrack:Stop()

			connection:Disconnect() -- it's important to disconnect connections when they are no longer needed

		end

	end)

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



playForNumberLoops(animationTrack, 5)

Ended

當 AnimationTrack 完全移動世界上的任何東西時，發生火災。動畫已停止播放，「淡出」已完成，主題處於中立姿勢。

您可以使用此來在動畫軌道的主題回到中立姿勢時執行行動，或清理 AnimationTrack 或 AnimationTrack 。或任何相關連線。


範例程式碼

The function in this code sample plays an animationTrack and yields until it has stopped and ended, printing at each step along the way.

AnimationTrack Ended
local InsertService = game:GetService("InsertService")

local Players = game:GetService("Players")



-- Create an NPC model to animate.

local npcModel = Players:CreateHumanoidModelFromUserId(129687796)

npcModel.Name = "JoeNPC"

npcModel.Parent = workspace

npcModel:MoveTo(Vector3.new(0, 15, 4))

local humanoid = npcModel:WaitForChild("Humanoid")



-- Load an animation.

local animationModel = InsertService:LoadAsset(2510238627)

local animation = animationModel:FindFirstChildWhichIsA("Animation", true)

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



-- Connect to Stopped event. This fires when animation stops of

-- it's own accord, or we explicitly call Stop.

animationTrack.Stopped:Connect(function()

	print("Animation stopped")

end)



-- Connect to Ended event. This fires when when animation is completely

-- finished affecting the world. In this case it will fire 3 seconds

-- after we call animationTrack:Stop because we pass in a 3

-- second fadeOut.

animationTrack.Ended:Connect(function()

	print("Animation ended")

	animationTrack:Destroy()

end)



-- Run, give it a bit to play, then stop.

print("Calling Play")

animationTrack:Play()

task.wait(10)

print("Calling Stop")

animationTrack:Stop(3)

KeyframeReached

每次播放的 AnimationTrack 達到一個沒有預設名稱 - "Keyframe"的 Keyframe 時，都會發生火災。

這個事件允許開發人員在動畫中的預定點執行代碼(由 Keyframe 名稱設置)。這樣可以通過在動畫中添加 Sounds 或 ParticleEffects 來擴展 Roblox 動畫的預設功能。

Keyframe 名稱不需要獨一無二。例如，如果動畫有三個名為「粒子」的關鍵幀，達到關鍵幀事件將在這些關鍵幀之一被達到時發射。

Keyframe 名稱可以在 Roblox 動畫編輯器中設置，當創建或編輯動畫時。然而，它們無法在播放之前在現有動畫上設置 Script 。

參數

keyframeName: string

已達到 Keyframe 的名稱。


Stopped

在 AnimationTrack 結束播放時發射。

此事件有多種用途。它可以用來等到 AnimationTrack 停止，然後再繼續 (例如，如果連環播放一系列動畫後停止)。它也可以用來清理任何在動畫播放期間創建的 Instances 。


範例程式碼

The function in this code sample will play an animationTrack and yield until it has stopped, before printing.

AnimationTrack Stopped
local function yieldPlayAnimation(animationTrack, fadeTime, weight, speed)

	animationTrack:Play(fadeTime, weight, speed)

	animationTrack.Stopped:Wait()

	print("Animation has stopped")

end



local animation = Instance.new("Animation")

animation.AnimationId = "rbxassetid://507765644"



local humanoid = script.Parent:WaitForChild("Humanoid")

local animator = humanoid:WaitForChild("Animator")

local animationTrack = animator:LoadAnimation(animation)



yieldPlayAnimation(animationTrack, 1, 0.6, 1)
檢視繼承自Instance的所有項目
檢視繼承自Object的所有項目