액션시퀀스 실행
개요
제작한 액션시퀀스를 런타임에서 실행하고 제어하는 방법을 설명합니다.
또한 Collision, Event, Trigger 트랙에 스크립트를 연결하여 액션시퀀스 재생 중 발생하는 다양한 상황을 처리할 수 있으며, ActionRunner를 통해 실행 상태를 관리할 수 있습니다.
액션시퀀스 실행 제어
실행
local ActionRunner = Humanoid:GetActionRunner()
local ActionSequenceKey = "AttackAction"
ActionRunner:Play(ActionSequenceKey)Play 메서드는 캐릭터가 사망하지 않은 상태에서만 호출할 수 있으며, 전달하는 Key 값은 액션시퀀스 인스턴스의 이름과 동일해야 합니다.
동작 원리
Play 메서드를 호출하면, 원본 액션시퀀스 인스턴스는 Humanoid.ActionRunner 하위로 복제되며, 이후 복제된 인스턴스를 기반으로 액션이 실행됩니다. 액션시퀀스의 동작 원리를 이해하면 스크립트를 통해 다양한 연출과 제어가 가능하며, 자세한 내용은 아래 동작 원리를 참고하세요.
동작 원리트랜지션 재생
액션시퀀스는 Play 메서드에 전달되는 TransitionTime 값이 0보다 크면, 기존 액션에서 새로운 액션으로 자연스럽게 전환(블렌딩)되며 재생됩니다. (반대로 TransitionTime이 0이거나 생략된 경우, 트랜지션 없이 기존 액션 A는 즉시 종료되고 B가 바로 재생됩니다.)
트랜지션 재생이 발생할 때, 이미 액션 A가 재생 중인 상태에서 액션 B를 실행하면 두 액션은 일정 시간 동안 함께 재생되며 점진적으로 전환됩니다. 이때 TransitionTime 동안 A에서 B로 블렌딩이 이루어지고, 이후 A는 종료되며 B만 유지됩니다.
또한 TransitionTime은 트랜지션이 발생할 수 있는 최대 시간이며, 실제 블렌딩 시간은 트랜지션 시작 시점에서 A의 남은 재생 시간과 B의 전체 재생 길이에 따라 달라질 수 있습니다. 이때 트랜지션 시간은 두 액션의 남은 구간 중 더 짧은 시간 기준으로 제한(Clamp)됩니다.
이 방식은 액션 간 급격한 전환을 방지하고, 보다 자연스러운 연출을 구현할 때 사용됩니다.
트랙별 트랜지션 처리 방식
TransitionTime이 0보다 큰 경우, 트랙 종류에 따라 서로 다른 방식으로 트랜지션이 처리됩니다.
Animation Track
TransitionTime 기준으로 A → B 간 블렌드가 수행됩니다. 동일 시점에 여러 애니메이션이 존재할 경우, 재생 시점과 트리 구조 기준으로 마지막 애니메이션이 우선 적용됩니다.
Sound Track
TransitionTime 기준으로 기존 사운드(A)는 Fade Out됩니다.
CameraShake Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Camera FOV Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Camera Zoom Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Control Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Collision Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Event Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다.
Trigger Track
기존 트랙(A)은 즉시 종료되고, 새로운 트랙(B)이 재생됩니다. 단, 이미 진입한 상태에서 이탈하지 않은 트리거는 종료 이벤트가 즉시 호출됩니다.
주의 사항
동시에 재생 가능한 액션시퀀스는 최대 2개입니다.
이미 2개의 액션시퀀스가 재생 중인 상태에서 새로운 액션을 실행하면, 현재 재생 중인 액션 중 가장 오래된 액션이 종료됩니다.
재생 중인 액션시퀀스 반환
ActionRunner에 설정된 현재 재생 중인 액션시퀀스를 가져옵니다.
트랜지션 상황에 따라 두 개 이상의 액션 시퀀스가 동시에 존재할 수 있으므로, 배열 형태로 반환됩니다.
반환된 배열은 이전에 재생된 액션시퀀스부터 다음에 재생될 액션시퀀스 순으로 정렬되며, 재생이 완료된 항목은 자동으로 제거됩니다.
GetActionSequences 메서드는 서버에서만 호출할 수 있습니다.
정지
특정 액션시퀀스를 지정하여 정지하거나, 모든 액션시퀀스를 한 번에 정지할 수 있습니다.
트랜지션 중에는 이전 액션(A)과 다음 액션(B)이 동시에 존재할 수 있습니다. 이 상태에서 B를 Stop할 경우, 트랜지션의 대상이 사라지게 되므로 A 또한 함께 Stop 처리될 수 있습니다.
또한 동일한 이름의 액션시퀀스 간 트랜지션(A → A)이 발생하는 경우, Stop은 StopAll과 동일하게 동작합니다.
트리거 트랙의 경우, 섹션에 진입한 후 아직 이탈하지 않은 상태에서 액션 시퀀서가 정지되면 종료 이벤트가 즉시 호출됩니다.
액션러너 이벤트
액션시퀀스의 실행 상태는 ActionRunner가 제공하는 이벤트를 통해 확인할 수 있습니다.
Ended 이벤트 : 액션시퀀스가 정상적으로 끝까지 재생된 경우 호출됩니다.
Stopped 이벤트: 액션시퀀스가 중간에 중단된 경우 호출됩니다. Stop 또는 StopAll 메서드로 종료된 경우에도 호출되며, 트랜지션 사용 여부와 관계없이 새로운 액션이 재생되면 기존 액션에 대해 즉시 호출됩니다.
액션시퀀스 이벤트 연결
충돌 이벤트, 이벤트 트랙, 트리거 트랙에 스크립트를 연결하여 액션 재생 중 필요한 로직을 실행할 수 있습니다.
이벤트 연결 스크립트는 반드시 액션시퀀스 인스턴스의 자식이어야 하며, script.Parent와 같은 상대 참조를 통해 연결해야 합니다. 액션시퀀스는 실행 시 복제되어 동작하므로, 상대 참조가 아닌 방식으로 연결할 경우 실제 실행 인스턴스(복제본)에는 적용되지 않습니다.
이벤트는 서버와 클라이언트 환경 모두에서 연결할 수 있습니다. 다만 서버측 Script는 액션시퀀스 바로 하위에 배치하는 것을 권장하며, 더 깊은 자손 위치에서는 정상적으로 동작하지 않을 수 있습니다.
액션시퀀스 하위의 LocalScript에서 이벤트를 연결한 경우, 해당 로직은 모든 클라이언트에서 호출되므로, 필요에 따라 액션시퀀스를 실행한 주체(self)를 기준으로 필터링해야 합니다.
충돌체 트랙 연동
충돌 이벤트에서 전달되는 대상 객체(other)에는 액션시퀀스를 실행한 주체(self)가 포함될 수 있습니다. 따라서 필요에 따라 실행자를 제외하는 필터링 처리를 수행해야 합니다.
충돌체에 닿은 대상에 대해 데미지 적용, 회복 처리 등 대상 기반 상호작용 로직을 처리할 때 사용됩니다.
이벤트 트랙 연동
액션 재생 중 특정 시점에 맞춰 스크립트를 실행할 때 사용됩니다.
예를 들어 점프 시작/착지 시점 처리, 스킬 준비/시전과 같은 타이밍 기반 로직 제어에 활용됩니다.
트리거 트랙 연동
특정 구간 동안 상태를 활성화하거나 비활성화하는 로직을 처리할 때 사용됩니다.
예를 들어 패링, 무적, 피격 판정 등 구간 기반 상태 제어에 활용됩니다.
Last updated