Was macht UE Animationssystem?
Du bist ein Experte für Unreal Engines Animationssystem.
Kontextprüfung
Lies zuerst .agents/ue-project-context.md. Notiere, welche Plugins aktiviert sind (Control Rig, Motion Matching, Full Body IK), ob GAS verwendet wird und die Skeleton-/Charakterhierarchie.
Informationen sammeln
- Welcher Animationsbedarf? (Locomotion, Ability, Cinematic, IK, procedural)
- Nur C++, nur Blueprint oder gemischt?
- Verwendet der Charakter
ACharactermit einer bestehendenUSkeletalMeshComponent? - Ist GAS aktiv? (beeinflusst Montage-Replikation)
- Multiplayer? (bestimmt Replikationsstrategie)
- Verwendet das Projekt modulare Linked Anim Layers?
Architektur
ACharacter / AActor
└── USkeletalMeshComponent
└── UAnimInstance subclass
├── NativeInitializeAnimation() [Setup, Game Thread]
├── NativeUpdateAnimation(float dt) [Game Thread]
├── NativeThreadSafeUpdateAnimation(dt) [Worker Thread]
├── FAnimInstanceProxy [Worker Thread Auswertung]
└── Montage API / Linked Layers
Animationsupdates laufen in zwei Phasen. Game Thread: NativeUpdateAnimation – sicher zum Lesen des Gameplay-Zustands. Worker Thread: Blend Tree Auswertung. Schreibe alle gemeinsam genutzten Zustände als UPROPERTY() Transient-Member in NativeUpdateAnimation; lese diese zwischengespeicherten Werte in NativeThreadSafeUpdateAnimation.
AnimInstance
Subclass Pattern
// 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(); // IMMER super aufrufen
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);
// Nur UPROPERTY-Member lesen, die oben in NativeUpdateAnimation geschrieben wurden.
// Keine UObject-Funktionen aufrufen, die nicht als BlueprintThreadSafe markiert sind.
}
FAnimInstanceProxy – Thread-Sicherer Zugriff
Schwere Animationslogik kann auf Worker-Threads über NativeThreadSafeUpdateAnimation laufen. Zugriff auf gemeinsame Daten über den Proxy:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// FMyAnimInstanceProxy Deklaration – Worker-Thread Datencontainer
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;
};
// In UMyAnimInstance: CreateAnimInstanceProxy überschreiben, um deinen Proxy zurückzugeben
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
Die Engine kopiert Daten zwischen Game Thread und Worker Thread an sicheren Synchronisationspunkten.
Montagen
Quelle: AnimMontage.h, AnimInstance.h
Wichtige 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;
Spielen + Delegate Pattern
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// Zuerst spielen – Montage_SetEndDelegate ruft GetActiveInstanceForMontage()
// intern auf, was nullptr zurückgibt, bis Montage_Play die Instanz erstellt.
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) { }
Dynamic Slot Montage
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
Multiplayer-Replikation
- Mit GAS:
UAbilitySystemComponent::PlayMontage()verwenden – GAS übernimmt die Replikation überFGameplayAbilityRepAnimMontage. - Ohne GAS: Einen Montage-Pointer oder eine benutzerdefinierte Rep-Struct replizieren; der Server ruft
Montage_Playauf, Clients spielen beiOnRep_. - Rufe
Montage_Playniemals unabhängig auf allen Netzrollen ohne Synchronisation auf.
GAS-Integration – PlayMontageAndWait
// GAS-Ability-Task – PlayMontageAndWait (erfordert GameplayAbilities-Modul)
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(); // muss aufgerufen werden, um den Task zu starten
Blend Spaces
Blend Spaces sind Daten-Assets, die im AnimGraph abgetastet werden. Steuere sie, indem du UPROPERTY-Member auf der AnimInstance setzt, die der AnimGraph liest.
- 1D (
UBlendSpace1D): einzelne Achse, typischerweise Geschwindigkeit (0–600). VerwendeFInterpolationParametermitInterpolationType=SpringDamper,InterpolationTime=0.15,DampingRatio=1.0. - 2D (
UBlendSpace): zwei Achsen – Richtung (-180 bis 180) und Geschwindigkeit (0–600). Kardinalrichtungs-Samples auf jeder Geschwindigkeitsstufe. - Aim Offset (
UAimOffsetBlendSpace): additiver Blend Space für Yaw/Pitch-Zielen, platziert nach der Basis-Locomotion-Pose im AnimGraph.
Siehe references/locomotion-setup.md für die vollständige Achsenkonfiguration und Beispielplatzierung.
State Machines
State Machines leben im AnimGraph. Binde native C++-Logik an Übergangsregeln und Zustandseintritt/-austritt ohne Blueprint:
// In 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));
Frage den Zustandsautomaten zur Laufzeit ab:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
Conduit-Knoten
Conduits werten eine einzelne Boolean-Regel aus und verzweigen zu mehreren Zielzuständen – sie ersetzen duplizierte Übergangslogik. Füge einen Conduit im AnimGraph-Editor hinzu; sein CanEnterTransition wird einmal ausgeführt und alle ausgehenden Übergänge teilen sich das Ergebnis. Verwende Conduits, wenn drei oder mehr Zustände dieselbe Eintrittsbedingung benötigen (z. B. „ist am Boden?