# AnimationTrack

AnimationTrack : `Instance`

## Overview

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

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

## Properties

### Animation

`Animation`

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

#### Code Samples

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

### BlendByInertialization

`boolean`

관성 기반 블렌딩(Inertialization) 사용 여부를 설정하는 속성입니다. true로 설정하면 애니메이션 전환 시 관성을 이용해 더 자연스러운 전환 효과를 제공합니다.

#### Code Samples

### IsPlaying

`boolean`

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

#### Code Samples

```lua
AnimationTrack:Play()

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

### Length

`number`

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

#### Code Samples

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

### Looped

`boolean`

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

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

#### 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)
```

### TimePosition

`number`

AnimationTrack이 원본 애니메이션의 어느 시점까지 재생되었는지를 초 단위로 나타내는 속성입니다.

이 값을 설정하면 애니메이션의 특정 시점으로 이동할 수 있습니다. 단, TimePosition을 설정하려면 AnimationTrack이 재생 중이어야 합니다. AdjustSpeed()를 사용해 재생 속도를 0으로 설정한 뒤 TimePosition을 조정하면 원하는 지점에서 애니메이션을 정지시킬 수 있습니다.

#### Code Samples

```lua
AnimationTrack:Play()
AnimationTrack:AdjustSpeed(0)
AnimationTrack.TimePosition = 1.5
```

### UpperBodyAnimation

`boolean`

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

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

#### Code Samples

## Methods

### AdjustSpeed

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

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

#### Parameters

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

#### Return

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

#### Code Samples

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

### AdjustWeight

애니메이션의 가중치를 변경합니다.

가중치는 즉시 변경되지 않고, fadeTime에 지정한 시간 동안 현재 가중치에서 목표 가중치로 서서히 변경됩니다. 같은 우선순위의 여러 애니메이션이 동시에 재생될 때 각 AnimationTrack의 가중치에 따라 포즈가 혼합됩니다.

#### Parameters

| `number` InWeight   | 변경할 애니메이션 가중치입니다. (기본값은 1입니다.)                   |
| ------------------- | ------------------------------------------------ |
| `number` InFadeTime | 기존 가중치에서 새 가중치로 전환되는 데 걸리는 시간입니다. (기본값은 0.1입니다.) |

#### Return

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

#### Code Samples

```lua
AnimationTrack:Play()
AnimationTrack:AdjustWeight(0.5, 0.2)
```

### 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   | 애니메이션이 재생될 가중치입니다. (기본값은 1입니다.)              |
| `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

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

호출되면 애니메이션의 가중치가 지정된 시간 동안 0으로 감소하며, 페이드아웃이 끝나면 애니메이션의 영향이 완전히 사라집니다.

#### Parameters

| `number` InFadeTime | 애니메이션의 가중치가 0으로 감소하는 데 걸리는 시간입니다. (기본값은 0.1입니다.) |
| ------------------- | ------------------------------------------------ |

#### 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

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

애니메이션 재생이 끝나고 페이드아웃까지 완료되어 대상이 중립 포즈로 돌아온 시점에 호출됩니다. 애니메이션이 완전히 정리된 뒤 후속 처리를 하거나 AnimationTrack을 정리할 때 사용할 수 있습니다.

#### 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

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

이 이벤트가 발생한 뒤에도 페이드아웃이 진행되는 동안에는 애니메이션이 대상에 계속 영향을 줄 수 있습니다. 애니메이션의 영향이 완전히 사라진 시점을 확인하려면 Ended 이벤트를 사용합니다.

#### Parameters

#### Code Samples

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

## See also

{% content-ref url="/pages/GWE1QQYA5ZKybkJcVPtz" %}
[캐릭터 애니메이션](/korean/manual/studio-manual/character/character-animation.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/korean/development/api-reference/classes/animationtrack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.