UE 애니메이션 시스템
당신은 언리얼 엔진의 애니메이션 시스템 전문가입니다.
컨텍스트 확인
먼저 .agents/ue-project-context.md를 읽으세요. 어떤 플러그인이 활성화되어 있는지(Control Rig, Motion Matching, Full Body IK), GAS가 사용되는지, 그리고 스켈레톤/캐릭터 계층 구조를 확인하세요.
수집할 정보
- 어떤 애니메이션이 필요한가? (로코모션, 어빌리티, 시네마틱, IK, 절차적)
- C++ 전용, 블루프린트 전용, 혼합?
- 캐릭터가 기존
USkeletalMeshComponent와 함께ACharacter를 사용하는가? - GAS가 활성화되어 있는가? (몽타주 복제에 영향)
- 멀티플레이어인가? (복제 전략 결정)
- 프로젝트가 모듈식 링크드 애님 레이어를 사용하는가?
아키텍처
ACharacter / AActor
└── USkeletalMeshComponent
└── UAnimInstance 서브클래스
├── NativeInitializeAnimation() [설정, 게임 스레드]
├── NativeUpdateAnimation(float dt) [게임 스레드]
├── NativeThreadSafeUpdateAnimation(dt) [워커 스레드]
├── FAnimInstanceProxy [워커 스레드 평가]
└── 몽타주 API / 링크드 레이어
애니메이션 업데이트는 두 단계로 실행됩니다. 게임 스레드: NativeUpdateAnimation — 게임플레이 상태를 읽기에 안전합니다. 워커 스레드: 블렌드 트리 평가. 모든 공유 상태는 NativeUpdateAnimation에서 UPROPERTY() Transient 멤버로 작성하고, NativeThreadSafeUpdateAnimation에서 캐시된 값을 읽습니다.
AnimInstance
서브클래스 패턴
// MyAnimInstance.h
UCLASS()
class MYGAME_API UMyAnimInstance : public UAnimInstance
{
GENERATED_BODY()
virtual void NativeInitializeAnimation() override;
virtual void NativeUpdateAnimation(float DeltaSeconds) override;
virtual void NativeThreadSafeUpdateAnimation(float DeltaSeconds) override;
protected:
UPROPERTY(Transient) TObjectPtr<ACharacter> OwningCharacter;
UPROPERTY(Transient) TObjectPtr<UCharacterMovementComponent> MovementComp;
UPROPERTY(Transient, BlueprintReadOnly, Category="Locomotion")
float Speed = 0.f;
UPROPERTY(Transient, BlueprintReadOnly, Category="Locomotion")
float Direction = 0.f;
UPROPERTY(Transient, BlueprintReadOnly, Category="Locomotion")
bool bIsInAir = false;
};
// MyAnimInstance.cpp
void UMyAnimInstance::NativeInitializeAnimation()
{
Super::NativeInitializeAnimation(); // 항상 부모 호출
OwningCharacter = Cast<ACharacter>(TryGetPawnOwner());
if (OwningCharacter)
MovementComp = OwningCharacter->GetCharacterMovement();
}
void UMyAnimInstance::NativeUpdateAnimation(float DeltaSeconds)
{
Super::NativeUpdateAnimation(DeltaSeconds);
if (!OwningCharacter || !MovementComp) return;
const FVector Velocity = MovementComp->Velocity;
Speed = Velocity.Size2D();
bIsInAir = MovementComp->IsFalling();
if (Speed > 3.f)
{
const FRotator ActorRot = OwningCharacter->GetActorRotation();
const FRotator VelocityRot = Velocity.ToOrientationRotator();
Direction = UKismetMathLibrary::NormalizedDeltaRotator(
VelocityRot, ActorRot).Yaw;
}
}
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
Super::NativeThreadSafeUpdateAnimation(DeltaSeconds);
// 위 NativeUpdateAnimation에서 작성된 UPROPERTY 멤버만 읽습니다.
// BlueprintThreadSafe로 표시되지 않은 UObject 함수는 호출하지 마세요.
}
FAnimInstanceProxy — 스레드 안전 접근
무거운 애니메이션 로직은 NativeThreadSafeUpdateAnimation을 통해 워커 스레드에서 실행할 수 있습니다. 프록시를 통해 공유 데이터에 접근하세요:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// FAnimInstanceProxy 선언 — 워커 스레드 데이터 컨테이너
USTRUCT()
struct FMyAnimInstanceProxy : public FAnimInstanceProxy
{
GENERATED_BODY()
FMyAnimInstanceProxy() = default;
explicit FMyAnimInstanceProxy(UAnimInstance* Instance) : FAnimInstanceProxy(Instance) {}
float Speed = 0.f;
FVector Velocity = FVector::ZeroVector;
TEnumAsByte<EMovementMode> MovementMode = MOVE_None;
virtual void PreUpdate(UAnimInstance* AnimInstance, float DeltaSeconds) override;
virtual void Update(float DeltaSeconds) override;
};
// UMyAnimInstance에서: CreateAnimInstanceProxy를 재정의하여 프록시 반환
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
엔진은 안전한 동기화 지점에서 게임 스레드와 워커 스레드 간에 데이터를 복사합니다.
몽타주
출처: AnimMontage.h, AnimInstance.h
주요 API (UAnimInstance):
float Montage_Play(UAnimMontage*, float PlayRate=1.f,
EMontagePlayReturnType=MontageLength, float StartAt=0.f, bool bStopAll=true);
void Montage_Stop(float BlendOut, const UAnimMontage* Montage=nullptr);
void Montage_Pause(const UAnimMontage* Montage=nullptr);
void Montage_Resume(const UAnimMontage* Montage);
void Montage_JumpToSection(FName Section, const UAnimMontage* Montage=nullptr);
void Montage_SetNextSection(FName From, FName To, const UAnimMontage* Montage=nullptr);
bool Montage_IsActive(const UAnimMontage*) const;
bool Montage_IsPlaying(const UAnimMontage*) const;
FName Montage_GetCurrentSection(const UAnimMontage* Montage=nullptr) const;
float Montage_GetPosition(const UAnimMontage*) const;
재생 + 델리게이트 패턴
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// 먼저 재생 — Montage_SetEndDelegate는 내부적으로 GetActiveInstanceForMontage()를
// 호출하는데, Montage_Play가 인스턴스를 생성하기 전까지 nullptr을 반환합니다.
if (AnimInst->Montage_Play(Montage) <= 0.f) return;
FOnMontageEnded EndDelegate;
EndDelegate.BindUObject(this, &UMyComponent::OnAttackEnded);
AnimInst->Montage_SetEndDelegate(EndDelegate, Montage);
FOnMontageBlendingOutStarted BlendOutDelegate;
BlendOutDelegate.BindUObject(this, &UMyComponent::OnAttackBlendingOut);
AnimInst->Montage_SetBlendingOutDelegate(BlendOutDelegate, Montage);
}
void UMyComponent::OnAttackEnded(UAnimMontage* Montage, bool bInterrupted) { }
void UMyComponent::OnAttackBlendingOut(UAnimMontage* Montage, bool bInterrupted) { }
동적 슬롯 몽타주
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
멀티플레이어 복제
- GAS 있음:
UAbilitySystemComponent::PlayMontage()사용 — GAS가FGameplayAbilityRepAnimMontage를 통해 복제를 처리합니다. - GAS 없음: 몽타주 포인터 또는 사용자 정의 rep 구조체 복제; 서버가
Montage_Play를 호출하고 클라이언트는OnRep_에서 재생합니다. - 동기화 없이 모든 네트워크 역할에서 독립적으로
Montage_Play를 호출하지 마세요.
GAS 통합 — PlayMontageAndWait
// GAS 어빌리티 태스크 — PlayMontageAndWait (GameplayAbilities 모듈 필요)
UAbilityTask_PlayMontageAndWait* Task =
UAbilityTask_PlayMontageAndWait::CreatePlayMontageAndWaitProxy(
this, NAME_None, AttackMontage, 1.f);
Task->OnCompleted.AddDynamic(this, &UMyAbility::OnMontageCompleted);
Task->OnInterrupted.AddDynamic(this, &UMyAbility::OnMontageInterrupted);
Task->ReadyForActivation(); // 태스크를 시작하려면 반드시 호출
블렌드 스페이스
블렌드 스페이스는 AnimGraph에서 샘플링되는 데이터 에셋입니다. AnimInstance에서 AnimGraph가 읽는 UPROPERTY 멤버를 설정하여 구동합니다.
- 1D (
UBlendSpace1D): 단일 축, 일반적으로 Speed (0–600).InterpolationType=SpringDamper,InterpolationTime=0.15,DampingRatio=1.0으로FInterpolationParameter를 사용하세요. - 2D (
UBlendSpace): 두 축 — Direction (-180 ~ 180) 및 Speed (0–600). 각 속도 계층에서 기본 방향 샘플. - Aim Offset (
UAimOffsetBlendSpace): Yaw/Pitch 조준을 위한 가산 블렌드 스페이스, AnimGraph에서 기본 로코모션 포즈 뒤에 배치.
전체 축 구성 및 샘플 배치는 references/locomotion-setup.md를 참조하세요.
스테이트 머신
스테이트 머신은 AnimGraph에 있습니다. 블루프린트 없이 기본 C++ 로직을 전환 규칙 및 상태 진입/종료에 바인딩합니다:
// NativeInitializeAnimation()에서
AddNativeTransitionBinding(
FName("LocomotionSM"), FName("Idle"), FName("Walk/Run"),
FCanTakeTransition::CreateUObject(this, &UMyAnimInstance::CanStartMoving),
FName("IdleToMoving"));
AddNativeStateEntryBinding(
FName("LocomotionSM"), FName("Land"),
FOnGraphStateChanged::CreateUObject(this, &UMyAnimInstance::OnLandEntered));
런타임에 스테이트 머신 쿼리:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
컨듀잇 노드
컨듀잇은 단일 부울 규칙을 평가하고 여러 대상 상태로 분기하여 중복된 전환 로직을 대체합니다. AnimGraph 편집기에서 컨듀잇을 추가하고, CanEnterTransition이 한 번 실행되며 모든 나가는 전환은 결과를 공유합니다. 세 개 이상의 상태가 동일한 진입 조건(예: "지상에 있는가?")이 필요한 경우 컨듀잇을 사용하세요. 단순한 A-to-B 전환의 경우 직접 규칙이 더 명확합니다.
애님 노티파이
출처: AnimNotify.h, AnimNotifyState.h
UAnimNotify — 시점 기반
UCLASS(meta=(DisplayName="Footstep"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// 항상 UE5의 3-인자 시그니처를 재정의
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Footstep")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — 지속 시간 (Begin/Tick/End)
UCLASS(meta=(DisplayName="Weapon Collision Window"))
class MYGAME_API UWeaponCollisionState : public UAnimNotifyState
{
GENERATED_BODY()
public:
virtual void NotifyBegin(USkeletalMeshComponent*, UAnimSequenceBase*,
float TotalDuration, const FAnimNotifyEventReference&) override;
virtual void NotifyEnd(USkeletalMeshComponent*, UAnimSequenceBase*,
const FAnimNotifyEventReference&) override;
};
브랜칭 포인트 (동기식)
생성자에서 bIsNativeBranchingPoint = true로 설정합니다. Notify() 대신 BranchingPointNotify()를 재정의합니다. Montage_Advance 중에 동기식으로 실행됩니다.—섹션 점프 및 정밀한 타임라인 제어에 사용합니다. 다른 모든 노티파이는 대기열에 추가됩니다(틱 완료 후 실행, VFX/SFX에 안전).
명명된 노티파이 델리게이트
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
내장 노티파이 카탈로그 및 더 많은 사용자 정의 패턴은 references/anim-notify-reference.md를 참조하세요.
IK 및 절차적 애니메이션
라인 트레이스를 사용한 Foot IK (NativeUpdateAnimation — 게임 스레드)
FVector UMyAnimInstance::GetFootTarget(FName SocketName) const
{
const FVector Foot = GetOwningComponent()->GetSocketLocation(SocketName);
FHitResult Hit;
FCollisionQueryParams P(SCENE_QUERY_STAT(FootIK), true);
P.AddIgnoredActor(OwningCharacter);
if (GetWorld()->LineTraceSingleByChannel(
Hit, Foot + FVector(0,0,50), Foot - FVector(0,0,75),
ECC_Visibility, P))
return Hit.ImpactPoint;
return Foot;
}
결과를 Control Rig 에셋(UE5 권장) 또는 AnimGraph의 Two Bone IK 스켈레탈 컨트롤 노드에 공급합니다.
스켈레탈 컨트롤 노드 (AnimGraph):
| 노드 | 목적 |
|---|---|
| Two Bone IK | 두 관절 IK (팔, 다리) — 이펙터 + 조인트 타겟 |
| FABRIK | 멀티 본 체인 IK — 팁 본 + 이펙터 |
| Look At | 단일 본이 클램프로 타겟 위치 추적 |
| Copy Bone | 본 간 변환 구성 요소 복사 |
| Spline IK | 본이 스플라인 곡선(척추, 꼬리)을 따름 |
레이어드 블렌드 퍼 본 (상체/하체 분할)
AnimGraph에서:
- 스테이트 머신 출력을 Base Pose에 연결합니다.
UpperBody슬롯 출력을 Blend Poses 0에 연결합니다.- 레이어 설정: Bone=
spine_01, Depth=0, MeshPoseBlendFactor=1.0.
공격 몽타주는 UpperBody 슬롯을 사용합니다. 로코모션은 아래에서 방해받지 않고 재생됩니다.
Aim Offset
// NativeUpdateAnimation에서:
const FRotator Delta = UKismetMathLibrary::NormalizedDeltaRotator(
OwningCharacter->GetBaseAimRotation(),
OwningCharacter->GetActorRotation());
AimYaw = FMath::Clamp(Delta.Yaw, -90.f, 90.f);
AimPitch = FMath::Clamp(Delta.Pitch, -90.f, 90.f);
AnimGraph의 기본 포즈 뒤에 Aim Offset 노드를 배치하고, AimYaw 및 AimPitch를 공급합니다.
링크드 애님 그래프 및 레이어
출처: AnimNode_LinkedAnimGraph.h, AnimNode_LinkedAnimLayer.h
링크드 애님 레이어 (권장)
- 레이어 함수 시그니처가 있는
UAnimLayerInterface블루프린트를 생성합니다. - 메인 AnimInstance가 인터페이스를 참조하는 Linked Anim Layer 노드를 가집니다.
- 분리된 AnimInstance 서브클래스가 모드별로 인터페이스를 구현합니다.
- 런타임에 전환:
// 로코모션 구현 전환
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// 모든 레이어를 기본값으로 재설정:
AnimInst->LinkAnimClassLayers(nullptr);
// 링크된 인스턴스 검색:
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
링크드 애님 그래프 (태그별)
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
노티파이 전파
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);
이 문서는 언리얼 엔진 5에 최적화되었습니다. 엔진 버전별 차이는 공식 문서를 참조하세요.