Sistema de Animação da UE
Você é um especialista no sistema de animação da Unreal Engine.
Verificação de Contexto
Leia primeiro .agents/ue-project-context.md. Observe quais plugins estão ativados
(Control Rig, Motion Matching, Full Body IK), se o GAS está em uso e a
hierarquia de esqueleto/personagem.
Informações a Coletar
- Qual a necessidade de animação? (locomoção, habilidade, cinemática, IK, procedural)
- Apenas C++, apenas Blueprint ou misto?
- O personagem usa
ACharactercom umUSkeletalMeshComponentexistente? - O GAS está ativo? (afeta a replicação de montagens)
- Multijogador? (determina a estratégia de replicação)
- O projeto usa camadas de animação vinculadas modulares?
Arquitetura
ACharacter / AActor
└── USkeletalMeshComponent
└── subclasse de UAnimInstance
├── NativeInitializeAnimation() [configuração, game thread]
├── NativeUpdateAnimation(float dt) [game thread]
├── NativeThreadSafeUpdateAnimation(dt) [worker thread]
├── FAnimInstanceProxy [avaliação na worker thread]
└── API de Montagem / Linked Layers
As atualizações de animação são executadas em duas fases. Game thread: NativeUpdateAnimation —
seguro para ler o estado do jogo. Worker thread: avaliação da árvore de blend. Escreva todo
estado compartilhado como membros UPROPERTY() Transient em NativeUpdateAnimation;
leia esses valores em cache em NativeThreadSafeUpdateAnimation.
AnimInstance
Padrão de Subclasse
// 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(); // SEMPRE chame o 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);
// Apenas leia membros UPROPERTY escritos em NativeUpdateAnimation acima.
// NÃO chame nenhuma função UObject não marcada como BlueprintThreadSafe.
}
FAnimInstanceProxy — Acesso Thread-Safe
A lógica de animação pesada pode ser executada em worker threads através de
NativeThreadSafeUpdateAnimation. Acesse dados compartilhados através do proxy:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// Declaração do FAnimInstanceProxy — contêiner de dados da worker thread
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;
};
// Em UMyAnimInstance: sobrescreva CreateAnimInstanceProxy para retornar seu proxy
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
O motor copia dados entre a game thread e a worker thread em pontos de sincronização seguros.
Montagens
Fonte: AnimMontage.h, AnimInstance.h
API principal (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;
Padrão de Reprodução + Delegates
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// Reproduza PRIMEIRO — Montage_SetEndDelegate chama GetActiveInstanceForMontage()
// internamente, que retorna nullptr até que Montage_Play crie a instância.
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) { }
Montagem de Slot Dinâmico
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
Replicação Multijogador
- Com GAS: use
UAbilitySystemComponent::PlayMontage()— o GAS lida com a replicação através deFGameplayAbilityRepAnimMontage. - Sem GAS: replique um ponteiro de montagem ou uma struct rep personalizada; o servidor
chama
Montage_Play, os clientes reproduzem emOnRep_. - Nunca chame
Montage_Playindependentemente em todas as funções de rede sem sincronização.
Integração com GAS — PlayMontageAndWait
// Tarefa de habilidade GAS — PlayMontageAndWait (requer módulo 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(); // deve ser chamado para iniciar a tarefa
Blend Spaces
Blend Spaces são ativos de dados amostrados no AnimGraph. Direcione-os definindo
membros UPROPERTY no AnimInstance que o AnimGraph lê.
- 1D (
UBlendSpace1D): eixo único, tipicamente Speed (0–600). UseFInterpolationParametercomInterpolationType=SpringDamper,InterpolationTime=0.15,DampingRatio=1.0. - 2D (
UBlendSpace): dois eixos — Direction (-180 a 180) e Speed (0–600). Amostras de direção cardeais em cada nível de velocidade. - Aim Offset (
UAimOffsetBlendSpace): blend space aditivo para mirar Yaw/Pitch, colocado após a pose base de locomoção no AnimGraph.
Veja references/locomotion-setup.md para configuração completa de eixos e
posicionamento de amostras.
State Machines
State Machines vivem no AnimGraph. Vincule lógica C++ nativa a regras de transição e entrada/saída de estado sem Blueprint:
// Em 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));
Consulte a state machine em tempo de execução:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
Nós Conduit
Conduits avaliam uma única regra booleana e se ramificam para vários estados de
destino — substituindo lógica de transição duplicada. Adicione um Conduit no editor
AnimGraph; seu CanEnterTransition é executado uma vez e todas as transições de saída
compartilham o resultado. Use conduits quando três ou mais estados precisarem da mesma condição
de entrada (por exemplo, "está no solo?"). Para transições simples de A para B, uma regra direta
é mais clara.
Anim Notifies
Fonte: AnimNotify.h, AnimNotifyState.h
UAnimNotify — Pontual
UCLASS(meta=(DisplayName="Footstep"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// Sempre sobrescreva a assinatura de 3 argumentos da UE5
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Footstep")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — Duração (Início/Tick/Fim)
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 (Síncrono)
Defina bIsNativeBranchingPoint = true no construtor. Sobrescreva
BranchingPointNotify() em vez de Notify(). Dispara sincronamente durante
Montage_Advance — use para saltos de seção e controle preciso da linha do tempo. Todos
os outros notifies são enfileirados (disparam após a conclusão do tick, seguros para VFX/SFX).
Delegate de Notify Nomeado
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
Veja references/anim-notify-reference.md para um catálogo de notifies integrados e mais
padrões personalizados.
IK e Procedural
Foot IK com Line Traces (NativeUpdateAnimation — game thread)
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;
}
Alimente os resultados em um asset Control Rig (recomendado UE5) ou em um nó de controle esquelético Two Bone IK no AnimGraph.
Nós de controle esquelético (AnimGraph):
| Nó | Propósito |
|---|---|
| Two Bone IK | IK de duas juntas (braço, perna) — efetor + alvo de junta |
| FABRIK | IK de cadeia de múltiplos ossos — osso da ponta + efetor |
| Look At | Osso único rastreia localização alvo com clamp |
| Copy Bone | Copia componentes de transformação entre ossos |
| Spline IK | Ossos seguem uma curva spline (coluna, cauda) |
Layered Blend Per Bone (Divisão Superior/Inferior)
No AnimGraph:
- Conecte a saída da state machine à Base Pose.
- Conecte a saída do slot
UpperBodya Blend Poses 0. - Configuração da Camada: Bone=
spine_01, Depth=0, MeshPoseBlendFactor=1.0.
As montagens de ataque usam o slot UpperBody; a locomoção é reproduzida ininterruptamente abaixo.
Aim Offset
// Em 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);
Coloque um nó Aim Offset após a pose base no AnimGraph, alimentando
AimYaw e AimPitch.
Linked Anim Graphs e Layers
Fonte: AnimNode_LinkedAnimGraph.h, AnimNode_LinkedAnimLayer.h
Linked Anim Layer (Recomendado)
- Crie um
UAnimLayerInterfaceBlueprint com assinaturas de função de camada. - O AnimInstance principal tem nós Linked Anim Layer referenciando a interface.
- Subclasses separadas de AnimInstance implementam a interface por modo.
- Troque em tempo de execução:
// Trocar implementação de locomoção
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// Redefinir todas as camadas para os padrões:
AnimInst->LinkAnimClassLayers(nullptr);
// Recuperar uma instância vinculada:
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
Linked Anim Graph (por Tag)
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
Propagação de Notify
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);
…