# ActionRunner

ActionRunner : `Instance`

## Overview

ActionSequence의 실행과 정지를 제어하는 컨트롤러 객체입니다.

`Humanoid:GetActionRunner()`를 호출하여 획득할 수 있으며, 현재 실행 중인 ActionSequence 목록을 조회하거나 이벤트를 통해 상태를 확인할 수 있습니다.

액션 실행 요청이 발생하면, 호출 위치(Client 또는 Server)에 관계없이 **서버에서 시퀀스 실행이 시작**됩니다. 이후 액션시퀀스 하위에 있는 **스크립트 이벤트가 연결**되고, 시퀀스와 자식 객체가 **모든 클라이언트로 복제**됩니다.

복제가 완료되면 **각 클라이언트에서 타임라인이 재생**되며, 애니메이션, 이펙트, 사운드 등의 연출이 실행됩니다.

즉, 액션시퀀스는 런타임에서 스크립트로 동적으로 생성하거나 직접 복제하는 구조가 아니라, **사전에 정의된 데이터를 기반으로 실행 시 복제**되어 연출을 수행하는 방식으로 동작합니다.

서버는 시퀀스 실행 시점을 기준으로 전체 진행 상태를 동기화하며, 클라이언트 간 발생할 수 있는 **시간 차이는 자동으로 보정**됩니다. 또한 게임 플레이의 일관성을 유지하기 위해 공격 **충돌 판정과 같은 핵심 로직은 서버에서 처리**됩니다.

액션시퀀스는 정의된 재생 구간 길이까지 타임라인이 재생되며 연출이 진행됩니다. **연출이 종료되면** 실행을 위해 **복제된 액션시퀀스 객체는 자동으로 제거**되며, 액션시퀀스에 연결된 이벤트 또한 함께 정리됩니다.

## Properties

## Methods

### GetActionSequences

ActionRunner에 설정된 현재 재생 중인 액션시퀀스를 가져옵니다.

트랜지션 상황에 따라 두 개 이상의 액션 시퀀스가 동시에 존재할 수 있으므로, 배열 형태로 반환됩니다.

반환된 배열은 이전에 재생된 액션시퀀스부터 다음에 재생될 액션시퀀스 순으로 정렬되며, 재생이 완료된 항목은 자동으로 제거됩니다.

GetActionSequences 메서드는 서버에서만 호출할 수 있습니다.

#### Parameters

#### Return

| `Value` | ActionSequence 목록입니다. |
| ------- | --------------------- |

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

local Actions = ActionRunner:GetActionSequences()
```

### Play

지정한 ID의 ActionSequence를 재생합니다.

Play 메서드는 캐릭터가 사망하지 않은 상태에서만 호출할 수 있으며, 전달하는 값은 액션시퀀스 인스턴스의 이름과 동일해야 합니다.

Play 메서드를 호출하면, 원본 액션시퀀스 인스턴스는 **Humanoid.ActionRunner 하위로 복제**되며, 이후 복제된 인스턴스를 기반으로 액션이 실행됩니다.

**연출이 종료되면** 실행을 위해 **복제된 액션시퀀스 객체는 자동으로 제거**되며, 액션시퀀스에 연결된 이벤트 또한 함께 정리됩니다.

**트랜지션 재생**

액션시퀀스는 Play 메서드에 전달되는 **TransitionTime 값이 0보다 크면**, 기존 액션에서 새로운 액션으로 자연스럽게 전환(블렌딩)되며 재생됩니다.\
(반대로 TransitionTime이 0이거나 생략된 경우, 트랜지션 없이 기존 액션 A는 즉시 종료되고 B가 바로 재생됩니다.)

트랜지션 재생이 발생할 때, 이미 액션 A가 재생 중인 상태에서 액션 B를 실행하면 두 액션은 **일정 시간 동안 함께 재생되며 점진적으로 전환**됩니다. 이때 TransitionTime 동안 A에서 B로 블렌딩이 이루어지고, 이후 A는 종료되며 B만 유지됩니다.

<figure><img src="/files/i2kXh9hPfrBNkj7RXCEx" alt=""><figcaption></figcaption></figure>

또한 TransitionTime은 트랜지션이 발생할 수 있는 **최대 시간**이며, 실제 블렌딩 시간은 트랜지션 시작 시점에서 A의 남은 재생 시간과 B의 전체 재생 길이에 따라 달라질 수 있습니다. 이때 트랜지션 시간은 두 액션의 남은 구간 중 더 짧은 시간 기준으로 제한(Clamp)됩니다.

이 방식은 액션 간 급격한 전환을 방지하고, 보다 자연스러운 연출을 구현할 때 사용됩니다.

**트랙별 트랜지션 처리 방식**

TransitionTime이 0보다 큰 경우, 트랙 종류에 따라 서로 다른 방식으로 트랜지션이 처리됩니다.

<table><thead><tr><th width="207.3333740234375">트랙</th><th>처리 방식</th></tr></thead><tbody><tr><td>Animation Track</td><td>TransitionTime 기준으로 A → B 간 블렌드가 수행됩니다.<br>동일 시점에 여러 애니메이션이 존재할 경우, 재생 시점과 트리 구조 기준으로 마지막 애니메이션이 우선 적용됩니다.</td></tr><tr><td>Sound Track</td><td>TransitionTime 기준으로 기존 사운드(A)는 Fade Out됩니다.</td></tr><tr><td>CameraShake Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Camera FOV Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Camera Zoom Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Control Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Collision Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Event Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.</td></tr><tr><td>Trigger Track</td><td>기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.<br>단, 이미 진입한 상태에서 이탈하지 않은 트리거는 종료 이벤트가 즉시 호출됩니다.</td></tr></tbody></table>

**주의 사항**

* 동시에 재생 가능한 액션시퀀스는 **최대 2개**입니다.
* 이미 2개의 액션시퀀스가 재생 중인 상태에서 새로운 액션을 실행하면, 현재 재생 중인 액션 중 가장 오래된 액션이 종료됩니다.

#### Parameters

| `string` InActionSequenceID | 재생할 ActionSequence 이름 입니다.                                                                                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` TransitionTime     | <p>액션시퀀스는 Play 메서드에 전달되는 <strong>TransitionTime 값이 0보다 크면</strong>, 기존 액션에서 새로운 액션으로 자연스럽게 전환(블렌딩)되며 재생됩니다.<br>(반대로 TransitionTime이 0이거나 생략된 경우, 트랜지션 없이 기존 액션 A는 즉시 종료되고 B가 바로 재생됩니다.)</p> |

#### Return

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

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

local ActionSequenceKey = "AttackAction"
local TransitionTime = 0.5 -- If greater than 0, it is processed as transition playback.

ActionRunner:Play(ActionSequenceKey, TransitionTime)
```

### Stop

지정한 ID의 ActionSequence를 정지합니다.

전달하는 값은 액션시퀀스 인스턴스의 이름과 동일해야 합니다.

#### Parameters

| `string` InActionSequenceID | 정지할 ActionSequence의 ID입니다. |
| --------------------------- | -------------------------- |

#### Return

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

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:Stop("SomeActionName")
```

### StopAll

현재 실행 중인 모든 ActionSequence를 정지합니다.

#### Parameters

#### Return

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

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:StopAll()
```

## Events

### Ended

실행 중이던 ActionSequence가 정상적으로 완료되면 발생하는 이벤트입니다.

#### Parameters

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

-- self : 액션시퀀스를 실행한 캐릭터 모델이 전달됩니다.
-- key : 종료된 액션시퀀스의 Key(이름)가 전달됩니다.
local function OnEnded(self, key)
    -- ...
end
ActionRunner.Ended:Connect(OnEnded)
```

### Stopped

`Stop()` 또는 `StopAll()` 메서드에 의해 ActionSequence가 중단되면 발생하는 이벤트입니다.

또한 트랜지션 사용 여부와 관계없이 새로운 액션이 재생되면 기존 액션에 대해 즉시 호출됩니다.

#### Parameters

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

-- self : 액션시퀀스를 실행한 캐릭터 모델이 전달됩니다.
-- key : 종료된 액션시퀀스의 Key(이름)가 전달됩니다.
local function OnStopped(self, key)
    -- ...
end
ActionRunner.Stopped:Connect(OnStopped)
```

## See also

{% content-ref url="/pages/4wFvTPpaFUW97x39URDq" %}
[액션시퀀스](/korean/manual/studio-manual/game-development/actionsequence.md)
{% endcontent-ref %}

{% content-ref url="/pages/PwkcSAovkak53rGWaRWG" %}
[액션시퀀스 실행](/korean/manual/studio-manual/game-development/actionsequence/running-actionsequences.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/actionrunner.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.