Sistema de Animación de UE
Eres un experto en el sistema de animación de Unreal Engine.
Verificación de Contexto
Lee primero .agents/ue-project-context.md. Nota qué plugins están habilitados
(Control Rig, Motion Matching, Full Body IK), si GAS está en uso, y la
jerarquía de esqueleto/personaje.
Información a Recopilar
- ¿Qué necesidad de animación? (locomoción, habilidad, cinemática, IK, procedural)
- ¿Solo C++, solo Blueprint o mixto?
- ¿El personaje usa
ACharactercon unUSkeletalMeshComponentexistente? - ¿Está activo GAS? (afecta la replicación de montajes)
- ¿Multijugador? (determina la estrategia de replicación)
- ¿El proyecto usa capas de animación enlazadas modulares?
Arquitectura
ACharacter / AActor
└── USkeletalMeshComponent
└── subclase de UAnimInstance
├── NativeInitializeAnimation() [configuración, hilo de juego]
├── NativeUpdateAnimation(float dt) [hilo de juego]
├── NativeThreadSafeUpdateAnimation(dt) [hilo de trabajo]
├── FAnimInstanceProxy [evaluación en hilo de trabajo]
└── API de Montaje / Capas Enlazadas
Las actualizaciones de animación se ejecutan en dos fases. Hilo de juego: NativeUpdateAnimation —
es seguro leer el estado del juego. Hilo de trabajo: evaluación del árbol de mezcla. Escribe todo
el estado compartido como miembros UPROPERTY() Transient en NativeUpdateAnimation;
lee esos valores en caché en NativeThreadSafeUpdateAnimation.
AnimInstance
Patrón de Subclase
// 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(); // SIEMPRE llamar al 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);
// Solo leer miembros UPROPERTY escritos en NativeUpdateAnimation arriba.
// NO llamar a funciones UObject que no estén marcadas como BlueprintThreadSafe.
}
FAnimInstanceProxy — Acceso Seguro para Hilos
La lógica de animación pesada puede ejecutarse en hilos de trabajo a través de
NativeThreadSafeUpdateAnimation. Accede a los datos compartidos a través del proxy:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// Declaración de FMyAnimInstanceProxy — contenedor de datos del hilo de trabajo
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;
};
// En UMyAnimInstance: sobrescribir CreateAnimInstanceProxy para devolver tu proxy
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
El motor copia datos entre el hilo de juego y el hilo de trabajo en puntos de sincronización seguros.
Montajes
Fuente: AnimMontage.h, AnimInstance.h
API clave (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;
Patrón de Reproducción + Delegado
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// Reproducir PRIMERO — Montage_SetEndDelegate llama a GetActiveInstanceForMontage()
// internamente, que devuelve nullptr hasta que Montage_Play crea la instancia.
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) { }
Montaje de Ranura Dinámica
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
Replicación Multijugador
- Con GAS: usar
UAbilitySystemComponent::PlayMontage()— GAS maneja la replicación a través deFGameplayAbilityRepAnimMontage. - Sin GAS: replicar un puntero de montaje o una estructura de replicación personalizada; el servidor
llama a
Montage_Play, los clientes reproducen enOnRep_. - Nunca llamar a
Montage_Playde forma independiente en todos los roles de red sin sincronización.
Integración GAS — PlayMontageAndWait
// Tarea de habilidad GAS — PlayMontageAndWait (requiere el 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(); // debe llamarse para iniciar la tarea
Blend Spaces
Los Blend Spaces son activos de datos muestreados en el AnimGraph. Se controlan estableciendo
miembros UPROPERTY en el AnimInstance que el AnimGraph lee.
- 1D (
UBlendSpace1D): un solo eje, típicamente Speed (0–600). UsarFInterpolationParameterconInterpolationType=SpringDamper,InterpolationTime=0.15,DampingRatio=1.0. - 2D (
UBlendSpace): dos ejes — Direction (-180 a 180) y Speed (0–600). Muestras de dirección cardinal en cada nivel de velocidad. - Aim Offset (
UAimOffsetBlendSpace): blend space aditivo para apuntar Yaw/Pitch, colocado después de la pose base de locomoción en el AnimGraph.
Ver references/locomotion-setup.md para la configuración completa de ejes y
colocación de muestras.
Máquinas de Estados
Las máquinas de estados viven en el AnimGraph. Vincula la lógica C++ nativa a las reglas de transición y a la entrada/salida de estados sin Blueprint:
// En 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));
Consultar la máquina de estados en tiempo de ejecución:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
Nodos Conduit
Los Conduits evalúan una sola regla booleana y se ramifican a múltiples estados de destino
— reemplazando la lógica de transición duplicada. Agrega un Conduit en el editor de AnimGraph;
su CanEnterTransition se ejecuta una vez y todas las transiciones salientes comparten
el resultado. Usa conduits cuando tres o más estados necesiten la misma condición de entrada
(por ejemplo, "¿está en el suelo?"). Para transiciones simples de A a B, una regla directa es más clara.
Notificaciones de Animación
Fuente: AnimNotify.h, AnimNotifyState.h
UAnimNotify — Punto en el Tiempo
UCLASS(meta=(DisplayName="Footstep"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// Siempre sobrescribir la firma de 3 argumentos de UE5
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Footstep")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — Duración (Inicio/Actualización/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;
};
Punto de Ramificación (Síncrono)
Establece bIsNativeBranchingPoint = true en el constructor. Sobrescribe
BranchingPointNotify() en lugar de Notify(). Se dispara de forma síncrona durante
Montage_Advance — úsalo para saltos de sección y control preciso de la línea de tiempo. Todas las
demás notificaciones se ponen en cola (se disparan después de que el tick completa, seguro para VFX/SFX).
Delegado de Notificación Nombrada
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
Ver references/anim-notify-reference.md para un catálogo de notificaciones incorporadas y más
patrones personalizados.
IK y Procedural
IK de Pie con Trazados de Línea (NativeUpdateAnimation — hilo de juego)
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;
}
Alimenta los resultados en un activo de Control Rig (recomendado UE5) o en un nodo de control esquelético Two Bone IK en el AnimGraph.
Nodos de control esquelético (AnimGraph):
| Nodo | Propósito |
|---|---|
| Two Bone IK | IK de dos articulaciones (brazo, pierna) — efector + objetivo de articulación |
| FABRIK | IK de cadena multi-hueso — hueso punta + efector |
| Look At | Hueso único sigue la ubicación del objetivo con límite |
| Copy Bone | Copia componentes de transformación entre huesos |
| Spline IK | Los huesos siguen una curva spline (columna, cola) |
Mezcla por Hueso en Capas (División Superior/Inferior)
En el AnimGraph:
- Conecta la salida de la máquina de estados a Base Pose.
- Conecta la salida de la ranura
UpperBodya Blend Poses 0. - Configuración de capa: Bone=
spine_01, Depth=0, MeshPoseBlendFactor=1.0.
Los montajes de ataque usan la ranura UpperBody; la locomoción se reproduce sin interrupciones debajo.
Aim Offset
// En 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);
Coloca un nodo Aim Offset después de la pose base en el AnimGraph, alimentando
AimYaw y AimPitch.
Gráficos de Animación Enlazados y Capas
Fuente: AnimNode_LinkedAnimGraph.h, AnimNode_LinkedAnimLayer.h
Capa de Animación Enlazada (Recomendada)
- Crea un
UAnimLayerInterfaceBlueprint con firmas de funciones de capa. - El AnimInstance principal tiene nodos Linked Anim Layer que hacen referencia a la interfaz.
- Subclases de AnimInstance separadas implementan la interfaz por modo.
- Intercambia en tiempo de ejecución:
// Cambiar la implementación de locomoción
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// Restablecer todas las capas a los valores predeterminados:
AnimInst->LinkAnimClassLayers(nullptr);
// Recuperar una instancia enlazada:
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
Gráfico de Animación Enlazado (por Etiqueta)
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
Propagación de Notificaciones
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);