# AnimationTrack

AnimationTrack : `Instance`

## Overview

애니메이터에 적용된 애니메이션의 실행을 관리하는 객체입니다.

이 객체는 Animator의 LoadAnimation() 메서드를 호출해야만 얻을 수 있습니다.

## Properties

### Animation

`Animation`

AnimationTrack에 설정된 Animation 객체를 반환하는 속성입니다. (읽기 전용)

#### Code Samples

```lua
print(AnimationTrack.Animation)
```

### IsPlaying

`bool`

애니메이션 트랙의 실행 여부를 반환하는 속성입니다. (읽기 전용)

#### Code Samples

```lua
AnimationTrack:Play()

if AnimationTrack.IsPlaying then
    print("DoSomething")
end
```

### Length

`number`

애니메이션 트랙의 전체 재생 시간을 초 단위로 반환하는 속성입니다. (읽기 전용)

#### Code Samples

```lua
print(AnimationTrack.Length)
```

### Looped

`bool`

애니메이션 완료 후 자동으로 다시 반복 실행할지를 지정하는 속성입니다.

이 속성은 애니메이션을 실행하기 전에 미리 지정해야 정상적으로 반영됩니다. 실행 중에 값을 변경할 경우, 해당 애니메이션이 종료된 뒤 기본 애니메이션으로 돌아가지 않고 그대로 멈출 수 있으므로 주의가 필요합니다.

#### Code Samples

```lua
AnimationTrack.Looped = true
```

### Priority

`Enum.AnimationPriority`

여러 애니메이션이 동시에 실행될 때 어떤 동작이 우위를 차지할지 지정하는 속성입니다.

Enum.AnimationPriority는 총 7단계로 구분되며, 가장 높은 Action4부터 가장 낮은 Core까지 세분화되어 있습니다. 애니메이션의 우선순위를 적절히 설정하면, 서로 다른 애니메이션이 한 번에 실행되더라도 부드럽게 조화됩니다.

예를 들어 AnimationTrack의 Priority를 Movement로 지정하면 이동 동작이 발생할 경우 애니메이션이 즉시 중단됩니다. 반면 Priority를 Action으로 설정하면 이동 중에도 애니메이션이 계속 재생됩니다.

기본값은 Action입니다.

#### Code Samples

```lua
AnimationTrack.Priority = Enum.AnimationPriority.Movement

AnimationTrack:Play()
```

### Speed

`number`

AnimationTrack의 현재 재생 속도를 나타내는 읽기 전용 속성입니다. AdjustSpeed() 메서드를 사용하여 재생 속도를 변경한 경우, 이 속성을 통해 변경된 속도 값을 확인할 수 있습니다.

#### Code Samples

```lua
print(AnimationTrack.Speed)
```

### UpperBodyAnimation

`bool`

애니메이션을 재생할 때 상체(Upper Body)에만 애니메이션이 적용되도록 설정하는 변수입니다.

이 값을 true로 설정하면 애니메이션이 캐릭터의 상체에만 적용되어, 하체 동작(예: 걷기, 달리기 등)은 유지되면서 상체 동작만 변경됩니다.

#### Code Samples

## Methods

### AdjustSpeed

애니메이션의 재생 속도를 제어합니다.

애니메이션의 기본 속도는 AnimationTrack:Play() 실행 시 지정되지만, 재생 도중에도 별도로 수정이 가능합니다.

#### Parameters

| `number` InSpeed | 재생 속도입니다. |
| ---------------- | --------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
AnimationTrack:AdjustSpeed(3)
```

### GetMarkerReachedSignal

애니메이션 재생 중 특정 키프레임에 지정된 마커에 도달하면 실행되는 이벤트를 반환합니다.

#### Parameters

| `string` InName | 마커의 이름입니다. |
| --------------- | ---------- |

#### Return

| `ScriptSignal` | 반환된 이벤트입니다. |
| -------------- | ----------- |

#### Code Samples

```lua
local function OnAnimationEvent()
    print("OnAnimationEvent")
end
AnimationTrack:GetMarkerReachedSignal("SomeKeyName"):connect(OnAnimationEvent)
```

### Play

애니메이션 트랙을 실행합니다.

InFadeTime은 애니메이션이 재생될 때 가중치가 서서히 증가하는 데 걸리는 시간을 조절하여 점진적인 전환 효과를 제공합니다.

InSpeed는 애니메이션의 재생 속도를 배율로 조정하여 기본 속도보다 빠르거나 느리게 실행되도록 설정할 수 있습니다.

#### Parameters

| `number` InFadeTime | 애니메이션의 가중치가 증가하는 데 걸리는 시간입니다. (기본값은 0.1입니다.) |
| ------------------- | -------------------------------------------- |
| `number` InWeight   | 현재 지원되지 않습니다.                                |
| `number` InSpeed    | 재생 속도입니다. (기본값은 1입니다.)                       |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local Players = game:GetService("Players")

local Character = Players.LocalPlayer.Character
local Humanoid = Character:WaitForChild("Humanoid")

local Animation = Instance.new("Animation")
Animation.AnimationId = "ovdrassetid://18850100" -- WinAnimation01

local Animator = Humanoid:FindFirstChild("Animator")
local AnimationTrack = Animator:LoadAnimation(Animation)

AnimationTrack:Play()
```

### Stop

실행중인 애니메이션 트랙을 정지합니다.

#### Parameters

| `number` InFadeTime | 현재 지원되지 않습니다. |
| ------------------- | ------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
AnimationTrack:Stop()
```

## Events

### DidLoop

루프 기능이 활성화된 애니메이션 트랙이 루프를 마칠 때마다 실행되는 이벤트입니다.

루프가 끝난 직후 다음 업데이트에서 발생하며, 루프가 없는 애니메이션에는 호출되지 않습니다.

#### Parameters

#### Code Samples

```lua
AnimationTrack.Looped = true

local function OnLoopAnimation()
    print("The animation looped!")
end
AnimationTrack.DidLoop:Connect(OnLoopAnimation)

AnimationTrack:Play()
```

### Ended

애니메이션 트랙의 재생이 완료되면 실행되는 이벤트입니다.

루프 기능이 활성화되어 있으면 호출되지 않으며, Stop() 메서드에 의해 종료될 때도 호출됩니다.

#### Parameters

#### Code Samples

```lua
local function OnEnded()
    print("The animation has ended!")
end
AnimationTrack.Ended:Connect(OnEnded)
```

### KeyframeReached

(Deprecated) 애니메이션이 진행되면서 지정된 이름을 가진 키프레임에 도달할 때마다 실행되는 이벤트입니다.

GetMarkerReachedSignal 사용을 권장합니다.

#### Parameters

| `string` KeyframeName | 키프레임 이름입니다. |
| --------------------- | ----------- |

#### Code Samples

```lua
local function OnKeyframeReached(keyframeName)
    print(keyframeName)
end
AnimationTrack.KeyframeReached:Connect(OnKeyframeReached)
```

### Stopped

Stop() 메서드에 의해 종료될 때 애니메이션 트랙의 재생이 정지되면 실행되는 이벤트입니다.

#### Parameters

#### Code Samples

```lua
local function OnStopped()
    print("The animation has been stopped!")
end
AnimationTrack.Stopped:Connect(OnStopped)
```

## See also

{% content-ref url="../../../manual/studio-manual/character/character-animation" %}
[character-animation](https://docs.overdare.com/korean/manual/studio-manual/character/character-animation)
{% endcontent-ref %}