UOverAnimMeshDeformer

기준: OverAnim 0.1.0 Beta · Unreal Engine 5.8
헤더: OverAnimation/Asset/OverAnimMeshDeformer.h

UOverAnimMeshDeformer는 Skeleton별 OverAnim 저작 에셋입니다. Region, Module Stack, Response Rule, 모션·시뮬레이션·프로토콜 설정을 보관하며 UOverAnimComponent가 런타임에 설치합니다.

Properties

Details UI 이름	C++ 속성명	기본값 · 범위	영향 · 관계
`Target Skeleton`	`TargetSkeleton`	`None`	대상 Skeletal Mesh의 Skeleton과 같아야 합니다. 불일치하면 계약 검증과 설치가 실패합니다.
`Applied Animations`	`AppliedAnimations`	빈 배열	비어 있으면 모든 Animation이 허용됩니다. 항목이 있으면 지정 Animation에만 전체 길이 Activation Window가 주입됩니다.
`Scope Activation Channel`	`ScopeActivationChannel`	`None`	`AppliedAnimations`가 만든 Window가 전달하는 선택적 채널입니다. Rule의 `Notify Activation Channel` 필터와만 연결됩니다.
`Master Effect Intensity`	`MasterEffectIntensity`	`1.0`, `0+` · UI 최대 `3`	에셋의 모든 Module authored strength에 곱해집니다. 모듈의 개별 safety limit은 유지됩니다.
C++ legacy tuning source	`TuningSource`	`Detailed`	기존 asset 호환을 위해 남아 있는 직렬화 필드입니다. 현재 built-in module runtime은 이 값을 읽지 않으며, `Simple / Details` 레이아웃과 Simple knob 적용 여부를 제어하지 않습니다. Details/Blueprint에는 직접 노출되지 않습니다.
`Simulation Settings`	`SimulationSettings`	구조체 기본값	Fixed update, substep, discontinuity/history reset을 제어합니다. Motion · Simulation을 참조합니다.
`Motion Signal Settings`	`MotionSignalSettings`	구조체 기본값	Automatic Six-Stage Motion의 분석·신호 설정입니다. Motion · Simulation을 참조합니다.
`Proportion Calibration`	`ProportionCalibration`	자동 보정 켜짐	캐릭터/Region 크기에 따라 선형 거리·속도·가속도 기준을 보정합니다. Region · Calibration을 참조합니다.
`Signal Protocol Settings`	`SignalProtocolSettings`	구조체 기본값	Protocol Channel을 실제 `FName` Signal로 변환합니다. Signal · Impact Types을 참조합니다.
`Impact Signal Settings`	`ImpactSignalSettings`	구조체 기본값	Hit, Collision, Damage 요청의 magnitude, deduplication, contact 처리 규칙입니다.
`Overlapping Region Policy`	`RegionCompositionPolicy`	`AdditiveClamped`	vertex mask가 겹친 Region의 변형을 `Additive Delta` 또는 `Strongest Delta`로 합성합니다.
`Request Budget`	`RequestBudget`	`256 / 64 / 32 / 1/60 s / 2 s`	프레임당 Signal/Request와 active response slot의 상한입니다. 초과 요청은 처리되지 않을 수 있습니다.
`Bone Group Descs`	`BoneGroupDescs`	빈 배열	Bone Group · Region의 저작 데이터입니다.
`Response Sets`	`ResponseSets`	빈 배열	Rule이 선택하는 named set입니다. Response Types를 참조합니다.
`Response Rules`	`ResponseRules`	빈 배열	Signal을 특정 Region/Module Response로 라우팅합니다.

Blueprint / Call In Editor authoring

Blueprint 표시명	C++ 선언	입력 · 반환	전제조건 · 실패/상태 변화
Add or Update Automatic Six-Stage Response	`int32 AddOrUpdateAutomaticMotionPhaseRule(FName BoneGroupName, FName ModuleName)`	Region 이름과 Module 이름을 받고 Rule index를 반환합니다.	Group, Module, Region Motion Phase Signal 이름이 유효하고 Module이 automatic response를 지원해야 합니다. 실패하면 `INDEX_NONE`입니다. 성공하면 motion/Region/phase signal을 켜고 activation scope를 `AuthoredActionWindow`로 설정합니다. 기존 Rule은 authored stage 설정을 보존하고, 새 Rule은 module 기본 response parameter와 automatic Response Set을 만듭니다.

C++ public functions

이 함수들은 Blueprint 노드가 아닙니다. 에셋 저작 도구 또는 C++ 통합의 지원 경계입니다.

Validation · Animation Scope · Skeleton

C++ 선언	반환 · 상태 변화	전제조건 · 거부 조건
`bool HasAppliedAnimations() const`	`AppliedAnimations` 배열에 하나 이상 항목이 있으면 `true`, 비어 있으면 `false`입니다. 에셋이 Animation Scope를 명시했는지를 질의합니다.	배열 내용의 로드 가능 여부나 대상 Animation의 Skeleton 일치 여부는 검사하지 않습니다. scope notify injection은 각 항목을 개별적으로 동기 로드하며, 로드하지 못한 항목은 건너뜁니다.
`bool SetTargetSkeleton(USkeleton* InTargetSkeleton)`	Skeleton을 설정하고 변경 delegate를 알립니다.	`InTargetSkeleton`이 유효해야 합니다. 유효하지 않으면 `false`입니다.
`bool ValidateContract(const USkeletalMesh* SkeletalMesh, TArray<FText>& OutErrors, TArray<FText>& OutWarnings) const`	`OutErrors`, `OutWarnings`를 채우고 오류가 없을 때 `true`입니다.	Mesh/Skeleton, 고유 ID·이름, mask 범위, Rule route, module 지원 범위, budget을 대조합니다. 반환 `false`이면 설치 가능한 계약이 아닙니다.
`FOverAnimAssetChanged& GetAssetChangedDelegate()`	에셋 변경 multicast delegate를 반환합니다.	아래 `FOverAnimAssetChanged`의 세 인자를 받는 native C++ delegate입니다. Blueprint Event가 아닙니다.
`void NotifyAssetChanged(EOverAnimAssetChangeType ChangeType, UObject* ChangedObject)`	`AssetChangedDelegate`를 `(this, ChangeType, ChangedObject)`로 broadcast합니다.	저작 변경 분류를 알리는 API이며, 렌더링·instance lifecycle 제어 API는 아닙니다.

Asset change delegate

FOverAnimAssetChanged는 UOverAnimMeshDeformer*, EOverAnimAssetChangeType, UObject*의 세 인자를 갖는 native multicast delegate입니다. 반환값은 없고 Blueprint에 노출되지 않습니다. 구독 C++ 코드는 자신이 보관한 delegate handle을 자신의 수명 종료 전에 제거해야 합니다.

Broadcast 인자	타입	계약
`Asset`	`UOverAnimMeshDeformer*`	변경을 알린 에셋입니다. `GetAssetChangedDelegate()`를 반환한 에셋과 같습니다.
`ChangeType`	`EOverAnimAssetChangeType`	아래 표의 변경 범주입니다. 구독자는 범주에 따라 캐시·표시 갱신 범위를 구분할 수 있습니다.
`ChangedObject`	`UObject*`	변경의 직접 대상입니다. 에셋 자체 또는 해당 Module이 전달될 수 있으며, 이 delegate는 소유권을 이전하지 않습니다.

`EOverAnimAssetChangeType` 값	의미	현재 내장 저작 경로
`Parameters`	구성원은 유지한 채 이름, mask 정책, LOD 정책, view stylization, module 파라미터처럼 값만 달라졌음을 나타냅니다.	파라미터 설정자와 일반 module Details 변경이 이 범주를 보냅니다.
`Structure`	Target Skeleton, Bone Group/Module의 추가·삭제·순서·활성화처럼 설치 또는 조합 구조가 달라졌음을 나타냅니다.	Skeleton 설정, Group/Module 구조 편집, Undo 및 structural module property 변경이 이 범주를 보냅니다.
`PreviewOnly`	미리보기 전용 변경을 구분하기 위한 public enum 값입니다.	OverAnim `0.1.0 Beta`의 내장 저작 경로는 이 값으로 `NotifyAssetChanged()`를 호출하지 않습니다. 외부 통합이 전달할 수 있는 분류값입니다.

Bone Group authoring

C++ 선언	반환 · 상태 변화	전제조건 · 거부 조건
`FGuid AddBoneGroup()`	새 Group의 ID를 반환합니다.	성공한 ID는 `BoneGroupDescs`에 추가됩니다.
`bool RemoveBoneGroup(FGuid GroupId)`	해당 Group을 제거합니다.	일치 ID가 없으면 `false`입니다. 그 Group을 가리키는 Rule은 별도로 유효성 검사를 통과해야 합니다.
`FGuid DuplicateBoneGroup(FGuid GroupId)`	복제 Group ID를 반환합니다.	원본 ID가 없으면 invalid GUID입니다. Module/Region 데이터가 복제됩니다.
`bool MoveBoneGroup(FGuid GroupId, int32 TargetIndex)`	배열 순서를 변경합니다.	ID 또는 target index가 유효하지 않으면 `false`입니다.
`bool SetBoneGroupName(FGuid GroupId, FName NewName)`	`GroupName`을 변경합니다.	빈 이름 또는 다른 Group과 중복이면 `false`입니다. Rule의 `BoneGroupName`은 자동으로 대체되지 않습니다.
`bool SetBoneGroupAlwaysEnabled(FGuid GroupId, bool bIsAlwaysEnable)`	`Always Active`를 변경합니다.	대상 ID가 없으면 `false`입니다.
`bool SetBoneGroupAffectedBone(FGuid GroupId, FName BoneName, bool bAffected)`	한 bone을 mask에 추가/제거합니다.	Group과 bone이 유효해야 합니다.
`bool SetBoneGroupAffectedBones(FGuid GroupId, TConstArrayView<FName> BoneNames, bool bAffected)`	여러 bone의 mask 상태를 바꿉니다.	Group ID와 각 bone 이름이 유효해야 합니다.
`bool SetBoneGroupHierarchyExpansion(FGuid GroupId, int32 ExpandTowardsRoot, int32 ExpandTowardsLeaf)`	root/leaf expansion을 변경합니다.	root는 `0+`, leaf는 `-1` 또는 `0+`여야 합니다.
`bool SetBoneGroupMotionSampleBone(FGuid GroupId, FName MotionSampleBone)`	`Fixed Analysis Bone`을 변경합니다.	Group ID가 없으면 `false`입니다. `None`은 `Analysis Method`를 사용하는 자동 해석입니다.
`bool SetBoneGroupAutomaticActionGroup(FGuid GroupId, FName AutomaticActionGroup)`	`Action Group`을 변경합니다.	Group ID가 없거나 현재 값과 같으면 `false`입니다. `None`은 독립 Region입니다.
`bool SetBoneGroupAutomaticActionMotionAnalysis(FGuid GroupId, OverAnimMotionPhase::EMotionAnalysis MotionAnalysis)`	`Analysis Method`를 변경합니다.	Group ID가 없거나 현재 값과 같으면 `false`입니다. 함수 자체는 전달된 enum 값을 별도로 sanitize하지 않습니다.
`bool SetBoneGroupAutomaticPhaseAnimationRouting(FGuid GroupId, OverAnimMotionPhase::EAnimationRouting AnimationRouting)`	`Analyze Animations` route를 변경합니다.	Group ID가 없거나 현재 값과 같으면 `false`입니다. Saved Allowed Animations는 지우지 않으며 다른 route에서는 validation warning과 함께 무시될 수 있습니다.
`bool SetBoneGroupAutomaticPhaseAnimations(FGuid GroupId, TConstArrayView<TSoftObjectPtr<UAnimSequenceBase>> Animations)`	`Allowed Animations`를 교체합니다.	Group ID가 없으면 `false`입니다. null, `AppliedAnimations`에 없는 항목과 중복 경로를 제거한 배열을 저장하며, 정리된 결과가 현재 값과 같아도 `false`입니다.
`bool SetBoneGroupAuthoredMotionPhaseCurves(FGuid GroupId, FName CurveName, FName CurveWeightName)`	Stage Curve와 companion weight curve를 함께 설정합니다.	Group ID가 없거나 두 값이 모두 현재 값과 같으면 `false`입니다. 함수는 weight-only 조합도 저장하므로 호출 후 validation을 수행해야 합니다. Weight curve만 있으면 계약 오류입니다.
`bool SetBoneGroupMaskPolicy(FGuid GroupId, const FOverAnimRegionMaskPolicy& MaskPolicy)`	mask falloff를 변경합니다.	`ZeroWeight < FullWeight`여야 합니다.
`bool SetBoneGroupLodPolicy(FGuid GroupId, EOverAnimRegionLodPolicy LodPolicy)`	LOD 계약을 변경합니다.	Group ID가 없으면 `false`입니다.
`bool SetBoneGroupViewStylization(FGuid GroupId, const FOverAnimRegionViewStylizationSettings& ViewStylization)`	Region Camera Readability 권한/강도를 변경합니다.	Component의 Camera Readability master switch가 별도로 켜져야 실제 correction이 적용됩니다.

Module Stack authoring

C++ 선언	반환 · 상태 변화	전제조건 · 거부 조건
`FGuid AddModule(FGuid GroupId, TSubclassOf<UOverAnimDeformerModule> ModuleClass)`	생성 Module ID를 반환합니다.	Group과 `ModuleClass`가 유효해야 합니다. 실패하면 invalid GUID입니다.
`bool RemoveModule(FGuid GroupId, FGuid ModuleId)`	Module을 제거합니다.	Group/Module ID가 없으면 `false`입니다. 해당 Module을 가리키는 Rule은 별도 수정이 필요합니다.
`int32 RemoveMissingModuleEntries(FGuid GroupId)`	제거한 missing class 항목 수를 반환합니다.	Group ID가 없으면 `0`입니다.
`FGuid DuplicateModule(FGuid GroupId, FGuid ModuleId)`	복제 Module ID를 반환합니다.	대상 ID가 없으면 invalid GUID입니다.
`bool MoveModule(FGuid GroupId, FGuid ModuleId, int32 TargetIndex)`	Module Stack 순서를 변경합니다.	대상 ID/index가 유효하지 않으면 `false`입니다. 같은 Phase 안에서는 순서가 합성 결과에 영향을 줍니다.
`bool SetModuleEnabled(FGuid GroupId, FGuid ModuleId, bool bEnabled)`	Module의 enabled 상태를 변경합니다.	대상 ID가 없으면 `false`입니다.
`bool RenameModule(FGuid GroupId, FGuid ModuleId, FName NewName)`	`Module Name`을 변경합니다.	유효한 대상과 고유한 이름이 필요합니다. Rule의 `ModuleName` route와 일치해야 합니다.
`bool ResetModuleParameters(FGuid GroupId, FGuid ModuleId)`	class default의 노출 파라미터로 되돌립니다.	대상 ID가 없으면 `false`입니다. `Module Id`는 식별자로 유지됩니다.

Lookup queries

C++ 선언	반환 · 상태 변화	전제조건 · 거부 조건
`int32 FindBoneGroupIndex(FGuid GroupId) const`	`BoneGroupDescs`에서 `GroupId`가 일치하는 첫 항목의 배열 index를 반환합니다. 에셋을 변경하지 않습니다.	일치하는 ID가 없으면 `INDEX_NONE`입니다. invalid GUID도 일치 항목이 없으면 같은 값을 반환합니다.
`int32 FindModuleIndex(const FOverAnimBoneGroupDesc& BoneGroupDesc, FGuid ModuleId) const`	전달된 `BoneGroupDesc.Modules`에서 null이 아니고 `ModuleId`가 일치하는 첫 Module의 배열 index를 반환합니다. 에셋을 변경하지 않습니다.	`BoneGroupDesc`는 호출자가 이미 확보한 값이며, 함수는 Group ID를 다시 찾지 않습니다. 일치 Module이 없거나 null 항목뿐이면 `INDEX_NONE`입니다.
`int32 FindAutomaticMotionPhaseRuleIndex(FName BoneGroupName, FName ModuleName) const`	Region Motion Phase Signal, source/target Region, Module, `AutomaticMotionPhase` timing이 모두 일치하는 첫 Rule index를 반환합니다.	일치 Rule이 없으면 `INDEX_NONE`이며 에셋을 변경하지 않습니다.
`static FName MakeAutomaticMotionPhaseResponseSetName(FName BoneGroupName)`	`Motion.ActionPhrase.<sanitized group>` 형식의 automatic Response Set 이름을 반환합니다.	이름을 생성할 뿐 Response Set을 추가하지 않습니다.

Static resolution helpers

C++ 선언	반환 · 출력	전제조건
`static bool BuildExplicitBoneChain(const USkeleton* Skeleton, FName StartBoneName, FName EndBoneName, TArray<FName>& OutBoneChain)`	부모-자식으로 연결된 chain을 `OutBoneChain`에 기록합니다.	Skeleton과 두 bone이 유효하고 Start가 End의 조상 경로에 있어야 `true`입니다.
`static void BuildResolvedAffectedBones(const FReferenceSkeleton& RefSkeleton, const FOverAnimBoneGroupDesc& BoneGroupDesc, TArray<FName>& OutBoneNames)`	명시 mask와 hierarchy expansion을 적용한 bone 목록을 출력합니다.	반환 목록은 입력 skeleton에 존재하는 bone만 의미가 있습니다.
`static OverAnimMotionPhase::FActionChain ResolveAutomaticActionMotionChain(const FReferenceSkeleton& RefSkeleton, const FOverAnimBoneGroupDesc& BoneGroupDesc)`	`PrimaryGuideChain`용 bone 이름, 유효·무시된 명시적 bone 수를 반환합니다.	연결된 명시적 Affected Bone이 최소 2개일 때 `IsUsable()`이 true입니다. helper branch와 연결되지 않은 명시 bone은 분석 chain에서 제외될 수 있습니다.
`static FName ResolveMotionSampleBone(const FReferenceSkeleton& RefSkeleton, const FOverAnimBoneGroupDesc& BoneGroupDesc)`	`Fixed Analysis Bone` 또는 legacy fallback으로 가장 깊은 resolved Region bone을 반환합니다.	Automatic Action 분석 전체가 이 bone 하나만 사용한다는 의미는 아닙니다. Fixed bone이 비어 있으면 `Analysis Method`와 `ResolveAutomaticActionMotionChain()` 결과가 우선될 수 있습니다. 해석할 bone이 없으면 `None`입니다.

FOverAnimAutomaticActionMotionChain은 BoneNames, ValidExplicitBoneCount, IgnoredExplicitBoneCount를 공개합니다. IsUsable()은 BoneNames.Num() >= 2일 때 true입니다.

UOverAnimDeformerInstanceSettings

UOverAnimDeformerInstanceSettings는 UMeshDeformerInstanceSettings를 상속하는 UCLASS(Transient) C++ runtime context입니다. UOverAnimDeformerModule::CreateInstance()를 override한 외부 module class는 이 포인터를 받아 측정 결과를 읽을 수 있습니다. 이 클래스는 BlueprintType이 아니며 Details/asset에 저장되는 사용자 저작 설정은 아닙니다.

C++ 필드	생성 시 값	수명·노출 계약
`FOverAnimResolvedCharacterProportions CharacterProportions`	`CreateSettingsInstance(UMeshComponent*)`가 Target Mesh와 에셋 `ProportionCalibration`으로 해석한 캐릭터 비율입니다.	설치별 transient snapshot입니다. Blueprint/Details에 노출되지 않고 asset에 저장되지 않습니다.
`FOverAnimProportionCalibrationSettings ProportionCalibration`	에셋의 `ProportionCalibration`을 복사한 값입니다.	위 snapshot을 만든 보정 규칙입니다. 사용자 저작은 `Proportion Calibration`에서 하며, 이 runtime context는 설정 저장 위치가 아닙니다.

UOverAnimMeshDeformer::CreateSettingsInstance()가 이 객체를 생성하고 Mesh Deformer 수명주기에서 보관합니다. public 필드는 custom module extension의 읽기 컨텍스트이지만, 직접 생성·직접 변경의 지속성 또는 재설치 동작은 public API로 보장되지 않습니다.

설치 전 계약

UOverAnimComponent::ApplyOverAnim()은 Target Mesh, TargetSkeleton, Region, Rule, Module의 계약이 맞을 때만 준비 상태가 됩니다. 모든 Rule이 Signal 이름, Bone Group 이름, Module 이름, 활성화 조건, Module 지원 범위를 동시에 만족해야 합니다.