UE 动画系统
您是虚幻引擎动画系统的专家。
上下文检查
首先阅读 .agents/ue-project-context.md。注意已启用的插件(Control Rig、Motion Matching、Full Body IK),是否使用了 GAS,以及骨骼/角色层级。
待收集信息
- 需要什么动画?(移动、技能、过场、IK、程序化)
- 仅 C++、仅蓝图,还是混合?
- 角色是否使用带有现有
USkeletalMeshComponent的ACharacter? - 是否启用了 GAS?(影响蒙太奇复制)
- 是否为多人游戏?(决定复制策略)
- 项目是否使用模块化的链接动画层?
架构
ACharacter / AActor
└── USkeletalMeshComponent
└── UAnimInstance 子类
├── NativeInitializeAnimation() [初始化,游戏线程]
├── NativeUpdateAnimation(float dt) [游戏线程]
├── NativeThreadSafeUpdateAnimation(dt) [工作线程]
├── FAnimInstanceProxy [工作线程评估]
└── 蒙太奇 API / 链接层
动画更新分两个阶段运行。游戏线程:NativeUpdateAnimation — 安全读取游戏状态。工作线程:混合树评估。将所有共享状态作为 UPROPERTY() Transient 成员在 NativeUpdateAnimation 中写入;然后在 NativeThreadSafeUpdateAnimation 中读取这些缓存值。
AnimInstance
子类模式
// 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(); // 始终调用父类
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);
// 仅读取上面 NativeUpdateAnimation 中写入的 UPROPERTY 成员。
// 不要调用任何未标记为 BlueprintThreadSafe 的 UObject 函数。
}
FAnimInstanceProxy — 线程安全访问
繁重的动画逻辑可以通过 NativeThreadSafeUpdateAnimation 在工作线程上运行。通过代理访问共享数据:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// FAnimInstanceProxy 声明 — 工作线程数据容器
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;
};
// 在 UMyAnimInstance 中:重写 CreateAnimInstanceProxy 以返回你的代理
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
引擎在安全的同步点之间复制游戏线程和工作线程的数据。
蒙太奇
来源:AnimMontage.h、AnimInstance.h
关键 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;
播放 + 委托模式
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// 先播放 — Montage_SetEndDelegate 内部会调用 GetActiveInstanceForMontage()
// 在 Montage_Play 创建实例之前,它会返回 nullptr。
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) { }
动态插槽蒙太奇
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
多人游戏复制
- 使用 GAS:使用
UAbilitySystemComponent::PlayMontage()— GAS 通过FGameplayAbilityRepAnimMontage处理复制。 - 不使用 GAS:复制一个蒙太奇指针或自定义的 rep 结构;服务端调用
Montage_Play,客户端在OnRep_上播放。 - 切勿在没有同步的情况下,在所有网络角色上独立调用
Montage_Play。
GAS 集成 — PlayMontageAndWait
// GAS 能力任务 — PlayMontageAndWait(需要 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(); // 必须调用以启动任务
混合空间
混合空间是在 AnimGraph 中采样的数据资源。通过设置 AnimInstance 上 AnimGraph 读取的 UPROPERTY 成员来驱动它们。
- 1D (
UBlendSpace1D):单轴,通常为速度(0–600)。 使用FInterpolationParameter,其中InterpolationType=SpringDamper、InterpolationTime=0.15、DampingRatio=1.0。 - 2D (
UBlendSpace):双轴 — 方向(-180 到 180)和速度(0–600)。 每个速度层级有基本方向采样。 - 瞄准偏移 (
UAimOffsetBlendSpace):用于偏航/俯仰瞄准的附加混合空间,放置在 AnimGraph 中基础移动姿态之后。
参见 references/locomotion-setup.md 以了解完整的轴配置和采样放置。
状态机
状态机位于 AnimGraph 中。将原生 C++ 逻辑绑定到转换规则以及状态的进入/退出,无需蓝图:
// 在 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));
运行时查询状态机:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
导管节点
导管评估单个布尔规则并分派到多个目标状态——替换重复的转换逻辑。在 AnimGraph 编辑器中添加一个导管;它的 CanEnterTransition 运行一次,所有传出转换共享结果。当三个或更多状态需要相同的进入条件时(例如,“是否着地?”),使用导管。对于简单的 A 到 B 转换,直接规则更清晰。
动画通知
来源:AnimNotify.h、AnimNotifyState.h
UAnimNotify — 时间点
UCLASS(meta=(DisplayName="Footstep"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// 始终重写 UE5 的 3 参数签名
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Footstep")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — 持续时间(开始/持续/结束)
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;
};
分支点(同步)
在构造函数中设置 bIsNativeBranchingPoint = true。重写 BranchingPointNotify() 而不是 Notify()。在 Montage_Advance 期间同步触发——用于片段跳转和精确的时间轴控制。所有其他通知都已排队(在 tick 完成后触发,对 VFX/SFX 安全)。
命名通知委托
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
参见 references/anim-notify-reference.md 以了解内置通知目录和更多自定义模式。
IK 和程序化动画
使用线条追踪的足部 IK(NativeUpdateAnimation — 游戏线程)
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;
}
将结果输入到 Control Rig 资源(推荐 UE5)或 AnimGraph 中的 Two Bone IK 骨架控制节点。
骨架控制节点(AnimGraph):
| 节点 | 用途 |
|---|---|
| Two Bone IK | 双关节 IK(手臂、腿部)— 效应器 + 关节目标 |
| FABRIK | 多骨骼链 IK — 尖端骨骼 + 效应器 |
| Look At | 单骨骼追踪目标位置并带有钳制 |
| Copy Bone | 在骨骼之间复制变换组件 |
| Spline IK | 骨骼跟随样条曲线(脊柱、尾巴) |
按骨骼分层混合(上半身/下半身分离)
在 AnimGraph 中:
- 将状态机输出连接到 Base Pose。
- 将
UpperBody插槽输出连接到 Blend Poses 0。 - 层设置:Bone=
spine_01,Depth=0,MeshPoseBlendFactor=1.0。
攻击蒙太奇使用 UpperBody 插槽;移动动画在下方不受中断地播放。
瞄准偏移
// 在 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);
在 AnimGraph 中基础姿态之后放置一个 Aim Offset 节点,并输入 AimYaw 和 AimPitch。
链接动画图和层
来源:AnimNode_LinkedAnimGraph.h、AnimNode_LinkedAnimLayer.h
链接动画层(推荐)
- 创建一个带有层函数签名的
UAnimLayerInterface蓝图。 - 主 AnimInstance 拥有引用该接口的 Linked Anim Layer 节点。
- 单独的 AnimInstance 子类实现每个模式的接口。
- 运行时切换:
// 切换移动实现
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// 将所有层重置为默认值:
AnimInst->LinkAnimClassLayers(nullptr);
// 检索链接实例:
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
按标签链接动画图
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
通知传播
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);
…
[为翻译而截断]