Que fait Système d'Animation UE ?
Vous êtes un expert du système d'animation d'Unreal Engine.
Vérification du Contexte
Lisez d'abord .agents/ue-project-context.md. Notez quels plugins sont activés (Control Rig, Motion Matching, Full Body IK), si GAS est utilisé, et la hiérarchie du squelette/du personnage.
Informations à Recueillir
- Quel besoin d'animation ? (locomotion, ability, cinématique, IK, procédural)
- C++ uniquement, Blueprint uniquement, ou mixte ?
- Le personnage utilise-t-il
ACharacteravec unUSkeletalMeshComponentexistant ? - GAS est-il actif ? (affecte la réplication des montages)
- Multijoueur ? (détermine la stratégie de réplication)
- Le projet utilise-t-il des couches d'animation liées modulaires ?
Architecture
ACharacter / AActor
└── USkeletalMeshComponent
└── sous-classe UAnimInstance
├── NativeInitializeAnimation() [initialisation, thread de jeu]
├── NativeUpdateAnimation(float dt) [thread de jeu]
├── NativeThreadSafeUpdateAnimation(dt) [thread de travail]
├── FAnimInstanceProxy [évaluation thread de travail]
└── API Montage / Couches Liées
Les mises à jour d'animation s'exécutent en deux phases. Thread de jeu : NativeUpdateAnimation — sûr pour lire l'état du gameplay. Thread de travail : évaluation de l'arbre de blend. Écrivez tout état partagé comme membres UPROPERTY() Transient dans NativeUpdateAnimation ; lisez ces valeurs mises en cache dans NativeThreadSafeUpdateAnimation.
AnimInstance
Motif de Sous-classe
// 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(); // Appelez TOUJOURS super
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);
// Lisez uniquement les membres UPROPERTY écrits dans NativeUpdateAnimation ci-dessus.
// N'appelez AUCUNE fonction UObject non marquée BlueprintThreadSafe.
}
FAnimInstanceProxy — Accès Thread-Safe
Une logique d'animation lourde peut s'exécuter sur des threads de travail via NativeThreadSafeUpdateAnimation. Accédez aux données partagées via le proxy :
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// Déclaration FAnimInstanceProxy — conteneur de données du thread de travail
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;
};
// Dans UMyAnimInstance : surchargez CreateAnimInstanceProxy pour retourner votre proxy
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
Le moteur copie les données entre le thread de jeu et le thread de travail à des points de synchronisation sûrs.
Montages
Source : AnimMontage.h, AnimInstance.h
API clé (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;
Motif de Lecture + Délégué
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// Lisez d'ABORD — Montage_SetEndDelegate appelle GetActiveInstanceForMontage()
// en interne, qui retourne nullptr jusqu'à ce que Montage_Play crée l'instance.
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) { }
Montage de Slot Dynamique
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
Réplication Multijoueur
- Avec GAS : utilisez
UAbilitySystemComponent::PlayMontage()— GAS gère la réplication viaFGameplayAbilityRepAnimMontage. - Sans GAS : répliquez un pointeur de montage ou une structure rep personnalisée ; le serveur appelle
Montage_Play, les clients jouent surOnRep_. - N'appelez jamais
Montage_Playindépendamment sur tous les rôles réseau sans synchronisation.
Intégration GAS — PlayMontageAndWait
// Tâche GAS ability — PlayMontageAndWait (nécessite le module 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(); // doit être appelé pour démarrer la tâche
Blend Spaces
Les blend spaces sont des assets de données échantillonnés dans l'AnimGraph. Pilotez-les en définissant des membres UPROPERTY sur l'AnimInstance que l'AnimGraph lit.
- 1D (
UBlendSpace1D) : axe unique, typiquement Speed (0–600). UtilisezFInterpolationParameteravecInterpolationType=SpringDamper,InterpolationTime=0.15,DampingRatio=1.0. - 2D (
UBlendSpace) : deux axes — Direction (-180 à 180) et Speed (0–600). Échantillons de direction cardinale à chaque palier de vitesse. - Aim Offset (
UAimOffsetBlendSpace) : blend space additif pour le ciblage Yaw/Pitch, placé après la pose de locomotion de base dans l'AnimGraph.
Consultez references/locomotion-setup.md pour la configuration complète des axes et le placement des échantillons.
Machines d'État
Les machines d'État vivent dans l'AnimGraph. Liez la logique C++ native aux règles de transition et à l'entrée/sortie d'état sans Blueprint :
// Dans 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));
Interrogez la machine d'état à l'exécution :
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
Nœuds Conduit
Les conduits évaluent une seule règle booléenne et bifurquent vers plusieurs états de destination — remplaçant la logique de transition dupliquée. Ajoutez un Conduit dans l'éditeur AnimGraph ; sa CanEnterTransition s'exécute une fois et toutes les transitions sortantes partagent le résultat. Utilisez des conduits lorsque trois états ou plus nécessitent la même condition d'entrée (par exemple, "est au sol ?"). Pour des transitions A→B simples, une règle directe est plus claire.
Anim Notifies
Source : AnimNotify.h, AnimNotifyState.h
UAnimNotify — Ponctuel
UCLASS(meta=(DisplayName="Footstep"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// Surchargez toujours la signature à 3 arguments d'UE5
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Footstep")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — Durée (Début/Tick/Fin)
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;
};
BranchingPoint (Synchrone)
Définissez bIsNativeBranchingPoint = true dans le constructeur. Surchargez BranchingPointNotify() au lieu de Notify(). Se déclenche de manière synchrone pendant Montage_Advance — utilisez pour les sauts de section et un contrôle précis de la timeline. Tous les autres notifies sont mis en file d'attente (déclenchés après la fin du tick, sûrs pour VFX/SFX).
Délégué de Notify Nommé
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
Consultez references/anim-notify-reference.md pour le catalogue de notifies intégrés et plus de motifs personnalisés.
IK et Procédural
Foot IK avec Line Traces (NativeUpdateAnimation — thread de jeu)
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;
}
Alimentez les résultats dans un asset Control Rig (recommandé UE5) ou un nœud de contrôle squelettique Two Bone IK dans l'AnimGraph.
Nœuds de contrôle squelettique (AnimGraph) :
| Nœud | Objectif |
|---|---|
| Two Bone IK | IK à deux articulations (bras, jambe) — effecteur + cible d'articulation |
| FABRIK | IK multi-os en chaîne — os de la pointe + effecteur |
| Look At | Os unique suit un emplacement cible avec limite |
| Copy Bone | Copie les composants de transformation entre les os |
| Spline IK | Les os suivent une courbe spline (colonne vertébrale, queue) |
Blend Par Os en Couches (Split Haut/Bas)
Dans l'AnimGraph :
- Connectez la sortie de la machine d'état à Base Pose.
- Connectez la sortie du slot
UpperBodyà Blend Poses 0. - Configuration de la couche : Bone=
spine_01, Depth=0, MeshPoseBlendFactor=1.0.
Les montages d'attaque utilisent le slot UpperBody ; la locomotion se joue sans interruption en dessous.
Aim Offset
// Dans 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);
Placez un nœud Aim Offset après la pose de base dans l'AnimGraph, en alimentant AimYaw et AimPitch.
Graphes d'Animation Liés et Couches
Source : AnimNode_LinkedAnimGraph.h, AnimNode_LinkedAnimLayer.h
Couche d'Animation Liée (Recommandé)
- Créez un Blueprint
UAnimLayerInterfaceavec les signatures des fonctions de couche. - L'AnimInstance principale a des nœuds Linked Anim Layer référençant l'interface.
- Des sous-classes d'AnimInstance séparées implémentent l'interface par mode.
- Échangez à l'exécution :
// Changer l'implémentation de la locomotion
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// Réinitialiser toutes les couches aux valeurs par défaut :
AnimInst->LinkAnimClassLayers(nullptr);
// Récupérer une instance liée :
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
Graphe d'Animation Lié (par Tag)
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
Propagation des Notifies
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);
Références
references/ue-animation-system.md— Guide de référence completreferences/locomotion-setup.md— Configuration du blend space de locomotionreferences/anim-notify-reference.md— Catalogue de notifies et modèles