Unreal Engine 애니메이션 메타데이터: UAnimMetaData와 Metadata Curve

UAnimMetaData는 Animation Asset에 저장되는 UObject다#

UAnimationAsset은 UAnimMetaData instance 배열을 보관한다. metadata object는 animation asset의 subobject로 저장되므로 class property를 사용해 구조화된 data를 만들 수 있다.

주로 아래 용도로 쓴다.

• locomotion clip의 gameplay category와 권장 play rate
• 특정 animation을 처리하는 custom pipeline option
• export/import source 정보와 project-specific validation flag
• animation selection system이 asset load 뒤 읽을 작은 configuration

Asset metadata를 매 frame 찾기보다 animation을 선택하거나 state를 초기화하는 시점에 읽고, 자주 쓰는 primitive 값을 consumer에 cache하는 편이 명확하다.

Project 전용 metadata class 만들기#

1
#pragma once
2

3
#include "Animation/AnimMetaData.h"
4
#include "GameplayTagContainer.h"
5
#include "TraversalAnimMetaData.generated.h"
6

7
UCLASS(BlueprintType, Blueprintable, EditInlineNew)
8
class MYGAME_API UTraversalAnimMetaData final : public UAnimMetaData
9
{
10
    GENERATED_BODY()
11

12
public:
13
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Traversal")
14
    bool bSupportsRootMotion = false;
15

16
    UPROPERTY(
17
        EditAnywhere,
18
        BlueprintReadOnly,
19
        Category = "Traversal",
20
        meta = (ClampMin = "0.0"))
21
    float RecommendedPlayRate = 1.0f;
22

23
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Traversal")
24
    FGameplayTag TraversalType;
25
};

FGameplayTag를 사용하므로 이 예제 module은 GameplayTags dependency도 선언한다. Public header에 type이 value로 노출되므로 Public dependency다.

1
PublicDependencyModuleNames.AddRange(
2
    new[]
3
    {
4
        "Core",
5
        "CoreUObject",
6
        "Engine",
7
        "GameplayTags",
8
    }
9
);

단순 bool과 float만 필요하면 GameplayTags 부분은 제거할 수 있다.

Runtime에서 null-safe하게 조회하기#

1
#include "TraversalAnimMetaData.h"
2

3
#include "Animation/AnimationAsset.h"
4

5
const UTraversalAnimMetaData* FindTraversalMetaData(
6
    const UAnimationAsset* AnimationAsset)
7
{
8
    return AnimationAsset
9
        ? AnimationAsset->FindMetaDataByClass<UTraversalAnimMetaData>()
10
        : nullptr;
11
}

사용자는 metadata가 없는 Asset을 정상 입력으로 처리해야 한다.

1
float GetRecommendedPlayRate(const UAnimationAsset* AnimationAsset)
2
{
3
    const UTraversalAnimMetaData* MetaData =
4
        FindTraversalMetaData(AnimationAsset);
5

6
    return MetaData
7
        ? FMath::Max(0.0f, MetaData->RecommendedPlayRate)
8
        : 1.0f;
9
}

UAnimMetaData와 UAnimationAsset은 runtime Engine module API다. 그러나 object 접근이 가능하다고 모든 thread에서 안전한 것은 아니다.

같은 class의 metadata는 여러 개일 수 있다#

Blueprint의 FindMetaDataByClass가 단일 object를 반환하더라도 저장 구조와 editor API가 class별 singleton을 보장하는 것은 아니다.

• UAnimationAsset::MetaData는 array다.
• FindMetaDataByClass는 일치하는 첫 instance를 반환한다.
• editor의 GetMetaDataOfClass는 일치하는 instance array를 반환한다.

duplicate도 표현할 수 있다. 첫 항목만 쓰는 gameplay code가 duplicate 입력을 받으면 어떤 object가 선택되는지 content ordering에 의존한다.

Project가 class별 singleton을 원한다면 명시적으로 정책을 만든다.

• Editor add tool에서 기존 instance를 먼저 검색해 추가를 거부한다.
• Data Validation에서 같은 class count가 1을 넘으면 error로 보고한다.
• duplicate를 모두 허용한다면 first-match API 대신 array를 순회하고 ordering/merge rule을 정의한다.

“API 이름이 단수라서 하나일 것”이라는 추론을 serialization invariant로 사용하지 않는다.

Editor에서 추가·삭제·검증하기#

UAnimationBlueprintLibrary는 editor automation API다. Editor Utility Widget, Animation Modifier, commandlet/editor module에서 metadata를 일괄 추가·삭제·검사할 수 있다.

runtime module이 아니라 별도 Editor module에 dependency를 둔다.

1
PrivateDependencyModuleNames.AddRange(
2
    new[]
3
    {
4
        "Core",
5
        "CoreUObject",
6
        "Engine",
7
        "AnimationBlueprintLibrary",
8
        "MyGame", // metadata class를 선언한 runtime module 이름으로 교체
9
    }
10
);

주로 아래 operation을 쓴다.

직접 작성한 C++ editor tool의 기본 흐름은 이렇다.

1
// Editor module only
2
#include "AnimationBlueprintLibrary.h"
3
#include "Animation/AnimationAsset.h"
4
#include "TraversalAnimMetaData.h"
5

6
UAnimMetaData* AddTraversalMetaDataIfMissing(
7
    UAnimationAsset* AnimationAsset)
8
{
9
    if (!AnimationAsset)
10
    {
11
        return nullptr;
12
    }
13

14
    if (UTraversalAnimMetaData* Existing =
15
            AnimationAsset
16
                ->FindMetaDataByClass<UTraversalAnimMetaData>())
17
    {
18
        return Existing;
19
    }
20

21
    AnimationAsset->Modify();
22

23
    UAnimMetaData* Added = nullptr;
24
    UAnimationBlueprintLibrary::AddMetaData(
25
        AnimationAsset,
26
        UTraversalAnimMetaData::StaticClass(),
27
        Added);
28

29
    if (Added)
30
    {
31
        AnimationAsset->MarkPackageDirty();
32
    }
33

34
    return Added;
35
}

실제 batch tool에서는 다음도 처리한다.

• FScopedTransaction과 undo/redo
• duplicate class 정책
• read-only/source-control checkout
• dirty package 목록과 명시적인 save
• 실패 log와 idempotent 재실행
• Animation Modifier를 반복 적용할 때 versioning과 reapply 정책

MarkPackageDirty는 file save가 아니다. Editor Utility나 commandlet이 변경을 디스크에 기록할지 별도로 결정해야 한다.

Metadata Curve는 constant source curve다#

Animation Curves 문서의 Metadata Curve는 source animation에서 모든 key가 1.0인 read-only curve type이다. curve가 없으면 해당 source에는 flag가 없고, 있으면 source clip은 1.0을 제공한다.

Metadata Curve의 constant track 예시다. UI 배치는 engine version에 따라 달라질 수 있다.

하지만 최종 AnimGraph 값이 항상 정확히 0 또는 1이라고 가정하면 안 된다. animation pose와 curve가 blend되면 weight와 curve blend option에 따라 중간값이나 override 결과가 나올 수 있다.

1
const float TraversalWeight =
2
    AnimInstance->GetCurveValue(TEXT("Traversal"));
3

4
const bool bTraversalActive = TraversalWeight >= 0.5f;

0.5f는 engine의 보편 규칙이 아니라 이 gameplay system이 정한 threshold다. 연속 weight가 유용하면 bool로 바꾸지 않고 그대로 사용한다. curve가 없을 때의 fallback도 gameplay code에서 명시한다.

아래 상황에는 Metadata Curve가 잘 맞는다.

• state machine transition이나 AnimGraph branch가 현재 pose mix의 성격을 읽음
• animation layer가 특정 curve flag를 downstream graph로 전달함
• event 시점이 아니라 clip 전체에 걸친 tag-like float가 필요함

반대로 gameplay에서 구조화된 여러 field를 읽거나 Asset을 평가하지 않은 상태에서도 설정이 필요하면 UAnimMetaData가 낫다.

Notify, Attribute, Asset Metadata와 구분하기#

Montage section metadata#

Animation Asset 전체가 아니라 Montage section별로 다른 설정이 필요할 수도 있다. FCompositeSection은 section metadata 배열을 가질 수 있다.

예를 들어 한 Montage 안의 Windup, Attack, Recover section에 서로 다른 traversal/interrupt rule을 붙일 수 있다. 이 경우도 같은 class duplicate와 first-match policy를 section 단위로 정의해야 한다. Section index/name이 유효한지 확인하고, Montage가 수정될 때 metadata mapping validation을 수행한다.

Section metadata와 Anim Notify State도 구분한다.

• Section 전체의 구조화된 설정: section UAnimMetaData
• timeline 안 정확한 활성 구간과 event: Notify State

Runtime과 Editor 경계 요약#

Editor API header를 runtime module의 Public header에 include하거나 Shipping dependency에 넣지 않는다. Runtime에서 필요한 data와 editor authoring tool을 module로 분리한다.

검증 체크리스트#

• metadata가 Asset 전체인지 Montage section 단위인지 결정했는가?
• 같은 metadata class를 여러 개 허용할지 정책을 정했는가?
• first-match API에 duplicate ordering을 맡기지 않았는가?
• runtime lookup에서 null과 invalid field range를 처리했는가?
• worker-thread AnimGraph에서 UObject metadata를 직접 조회하지 않는가?
• Editor automation을 Editor module에 격리했는가?
• transaction, source-control, dirty package, save를 처리했는가?
• Metadata Curve의 final 값이 blend될 수 있음을 고려했는가?
• bool threshold 또는 continuous weight policy를 명시했는가?
• time event라면 Notify, keyed typed data라면 Attribute를 검토했는가?
• 일반 Asset Metadata를 runtime gameplay data로 사용하지 않았는가?
• cook과 packaged build에서 필요한 metadata class/module이 포함되는가?

참고 자료#

• Epic Games: UAnimMetaData
• Epic Games: UAnimationAsset
• Epic Games: Find Meta Data by Class
• Epic Games: UAnimationBlueprintLibrary
• Epic Games: Add Meta Data
• Epic Games: Get Meta Data Of Class
• Epic Games: Animation Modifiers
• Epic Games: Animation Curves and Metadata Curves
• Epic Games: UAnimInstance::GetCurveValue
• Epic Games: Animation Blend Nodes
• Epic Games: UAnimMontage
• Epic Games: FCompositeSection
• Epic Games: Animation Attributes
• Epic Games: Animation Notifies
• Epic Games: Asset Metadata
• UE5 How to hold data in Animation Assets (Anim Meta Data)