距离匹配

2025-11-30

字数统计: 3.3k字 | 阅读时长≈ 15分

距离匹配

在使用距离匹配时需要先在插件中开启AnimationLocomotionLibrary和AnimationWarping这两个插件

基本概念

游戏中动画驱动有两种方式，分别为位移驱动和动画驱动。位移驱动中玩家控制角色胶囊体的运动，动画自己播放，这种方式会导致角色动画的步幅与移动速度不匹配；动画驱动是由动画的根运动来驱动角色位移，这种方式可以很好的解决角色运动中的滑步现象。

基本原理

假如我们有一个起步动画，我们将角色的位移提取为距离曲线，同时每一帧获取曲线上的值，这个值就是角色的位移距离（距离起点的距离），将该值应用到角色的位移中就可以实现步幅匹配。

提取距离曲线

DistanceCurve

提取距离曲线主要使用DistanceCurveModifier类，这个类主要包含的内容如下：

enum class EDistanceCurve_Axis : uint8
{
    X,
    Y,
    Z,
    XY,
    XZ,
    YZ,
    XYZ,
};

class UDistanceCurveModifier : public UAnimModifier
{
public:
    int32 SampleRate = 30;

    FName CurveName = "Distance";

    float StopSpeedThreshold = 5.0f;

    EDistanceCurve_Axis Axis = EDistanceCurve_Axis::XY;

    bool bStopAtEnd = false;

    virtual void OnApply_Implementation(UAnimSequence* Animation) override;
}

我们来逐个解析各个参数的含义：

SampleRate：采样频率，即每秒采样多少次，默认为30次，采样频率越高，曲线值与实际位置的误差越小
CurveName：采样的曲线名称，默认为Distance，供外部获取曲线值
StopSpeedThreshold：速度阈值，用于计算动画序列的最小速度
Axis：采样轴，即采样哪几个轴的位移，默认为XY，即采样X和Y轴的位移（水平位移）
bStopAtEnd：是否选择在动画结束的时间作为速度的最低时间
OnApply_Implementation：实际进行采样的函数，实现具体的采样逻辑

实现代码如下：

void UDistanceCurveModifier::OnApply_Implementation(UAnimSequence* Animation)
{
    // 1
	if (Animation == nullptr)
	{
		UE_LOG(LogAnimation, Error, TEXT("DistanceCurveModifier failed. Reason: Invalid Animation"));
		return;
	}

	if (!Animation->HasRootMotion())
	{
		UE_LOG(LogAnimation, Error, TEXT("DistanceCurveModifier failed. Reason: Root motion is disabled on the animation (%s)"), *GetNameSafe(Animation));
		return;
	}

    // 2
	const bool bMetaDataCurve = false;
	UAnimationBlueprintLibrary::AddCurve(Animation, CurveName, ERawCurveTrackTypes::RCT_Float, bMetaDataCurve);

    // 3
	const float AnimLength = Animation->GetPlayLength();
	float SampleInterval;
	int32 NumSteps;
	float TimeOfMinSpeed;

	if(bStopAtEnd)
	{ 
		TimeOfMinSpeed = AnimLength;
	}
	else
	{
		// Perform a high resolution search to find the sample point with minimum speed.
		
		TimeOfMinSpeed = 0.f;
		float MinSpeedSq = FMath::Square(StopSpeedThreshold);

		SampleInterval = 1.f / 120.f;
		NumSteps = AnimLength / SampleInterval;
		for (int32 Step = 0; Step < NumSteps; ++Step)
		{
			const float Time = Step * SampleInterval;

			const bool bAllowLooping = false;
			const FVector RootMotionTranslation = Animation->ExtractRootMotion(Time, SampleInterval, bAllowLooping).GetTranslation();
			const float RootMotionSpeedSq = CalculateMagnitudeSq(RootMotionTranslation, Axis) / SampleInterval;

			if (RootMotionSpeedSq < MinSpeedSq)
			{
				MinSpeedSq = RootMotionSpeedSq;
				TimeOfMinSpeed = Time;
			}
		}
	}

    // 4
	SampleInterval = 1.f / SampleRate;
	NumSteps = FMath::CeilToInt(AnimLength / SampleInterval);
	float Time = 0.0f;
	for (int32 Step = 0; Step <= NumSteps && Time < AnimLength; ++Step)
	{
		Time = FMath::Min(Step * SampleInterval, AnimLength);

		// Assume that during any time before the stop/pivot point, the animation is approaching that point.
		// TODO: This works for clips that are broken into starts/stops/pivots, but needs to be rethought for more complex clips.
		const float ValueSign = (Time < TimeOfMinSpeed) ? -1.0f : 1.0f;

		const FVector RootMotionTranslation = Animation->ExtractRootMotionFromRange(TimeOfMinSpeed, Time).GetTranslation();
		UAnimationBlueprintLibrary::AddFloatCurveKey(Animation, CurveName, Time, ValueSign * CalculateMagnitude(RootMotionTranslation, Axis));
	}
}

对源码进行分析：

这一步判断动画是否合法以及是否开启骨骼根运动
添加一条非元数据曲线，并声明需要使用的变量
寻找最低速度：

// 判断是否直接使用动画结束时间作为最小速度
if(bStopAtEnd)
{ 
    TimeOfMinSpeed = AnimLength;
}
else
{
    TimeOfMinSpeed = 0.f;
    // 从阈值中获取最小速度，只有比阈值速度还小才会更新
    float MinSpeedSq = FMath::Square(StopSpeedThreshold);

    // 默认采样间隔以及采样次数
    SampleInterval = 1.f / 120.f;
    NumSteps = AnimLength / SampleInterval;
    // 实际计算最小速度
    for (int32 Step = 0; Step < NumSteps; ++Step)
    {
        // 计算每步的步进时长
        const float Time = Step * SampleInterval;

        const bool bAllowLooping = false;
        // 提取两次采样之间的根运动距离
        const FVector RootMotionTranslation = Animation->ExtractRootMotion(Time, SampleInterval, bAllowLooping).GetTranslation();
        // 根据距离和步进时长计算前进速度
        const float RootMotionSpeedSq = CalculateMagnitudeSq(RootMotionTranslation, Axis) / SampleInterval;
        // 更新最小速度以及最小速度的时间
        if (RootMotionSpeedSq < MinSpeedSq)
        {
            MinSpeedSq = RootMotionSpeedSq;
            TimeOfMinSpeed = Time;
        }
    }
}

实际生成采样曲线

// 计算采样间隔，由暴露给蓝图的值决定
SampleInterval = 1.f / SampleRate;
// 计算采样次数
NumSteps = FMath::CeilToInt(AnimLength / SampleInterval);
float Time = 0.0f;
// 遍历采样
for (int32 Step = 0; Step <= NumSteps && Time < AnimLength; ++Step)
{
    // 防止采样超出动画时长
    Time = FMath::Min(Step * SampleInterval, AnimLength);
    // 用来判断是起步还是停步
    // 如果是起步动画，速度从0开始递增，速度最小值一定为正数且是开始的时候，所以TimeOfMinSpeed一定比Time小，得到的为1.0f
    // 如果是停步动画，速度逐渐递减到0，速度最小值一定为负数且在动画最后达到最小，则TimeOfMinSpeed的时间一定比Time大，得到的为-1.0f
    const float ValueSign = (Time < TimeOfMinSpeed) ? -1.0f : 1.0f;

    // 提取从TimeOfMinSpeed到Time之间的根运动距离
    const FVector RootMotionTranslation = Animation->ExtractRootMotionFromRange(TimeOfMinSpeed, Time).GetTranslation();
    // 将值添加到曲线中
    UAnimationBlueprintLibrary::AddFloatCurveKey(Animation, CurveName, Time, ValueSign * CalculateMagnitude(RootMotionTranslation, Axis));
}

通过提取的距离曲线，我们可以实现起步与停步的步幅匹配

起步匹配

StartMatch

起步动画主要依靠AdvanceTimeByDistanceMatching，通过序列求值器选择每一帧的动画进行播放

函数声明


/**
	 * Advance the sequence evaluator forward by distance traveled rather than time. A distance curve is required on the animation that
	 * describes the distance traveled by the root bone in the animation. See UDistanceCurveModifier.
	 * @param UpdateContext - The update context provided in the anim node function.
	 * @param SequenceEvaluator - The sequence evaluator node to operate on.
	 * @param DistanceTraveled - The distance traveled by the character since the last animation update.
	 * @param DistanceCurveName - Name of the curve we want to match 
	 * @param PlayRateClamp - A clamp on the effective play rate of the animation after distance matching. Set to (0,0) for no clamping.
	 */
	UFUNCTION(BlueprintCallable, Category = "Distance Matching", meta=(BlueprintThreadSafe))
	static FSequenceEvaluatorReference AdvanceTimeByDistanceMatching(const FAnimUpdateContext& UpdateContext, const FSequenceEvaluatorReference& SequenceEvaluator,
		float DistanceTraveled, FName DistanceCurveName, FVector2D PlayRateClamp = FVector2D(0.75f, 1.25f));

函数解释：根据动画前进的距离来设置动画的前进而非使用时间，这需要一个用于描述动画根骨骼位置的距离曲线，这个曲线我们可以从UDistanceCurveModifier中的来获取，这个在之前已经解释。

主要的三个参数为：
SequenceEvaluator：当前动画的序列求值器
DistanceTraveled：本帧移动的距离
DistanceCurveName：距离曲线

函数实现

FSequenceEvaluatorReference UAnimDistanceMatchingLibrary::AdvanceTimeByDistanceMatching(const FAnimUpdateContext& UpdateContext, const FSequenceEvaluatorReference& SequenceEvaluator,
	float DistanceTraveled, FName DistanceCurveName, FVector2D PlayRateClamp)
{
	// 1 进入时绑定了一个lambda函数作为参数一并传入CallAnimNodeFunction中被调用
	SequenceEvaluator.CallAnimNodeFunction<FAnimNode_SequenceEvaluator>(
		TEXT("AdvanceTimeByDistanceMatching"),
		[&UpdateContext, DistanceTraveled, DistanceCurveName, PlayRateClamp](FAnimNode_SequenceEvaluator& InSequenceEvaluator)
		{
			// 2.1 获取动画上下文
			if (const FAnimationUpdateContext* AnimationUpdateContext = UpdateContext.GetContext())
			{
				// 2.2 获取一个tick的时长
				const float DeltaTime = AnimationUpdateContext->GetDeltaTime(); 

				// 2.3 当tick时长与步进距离均大于0时继续执行下一步逻辑
				if (DeltaTime > 0 && DistanceTraveled > 0)
				{
					// 3.1 获取正在播放的动画并从动画中获取数据
					if (const UAnimSequenceBase* AnimSequence = Cast<UAnimSequence>(InSequenceEvaluator.GetSequence()))
					{
						// 3.2 获取当前时间，动画时长，是否循环播放
						const float CurrentTime = InSequenceEvaluator.GetExplicitTime();
						const float CurrentAssetLength = InSequenceEvaluator.GetCurrentAssetLength();
						const bool bAllowLooping = InSequenceEvaluator.IsLooping();

						// 4.1 获取在步进DistanceTraveled之后的动画时间
						// 这个函数的注释为：Advance from the current time to a new time in the animation that will result in the desired distance traveled by the authored root motion.
						// 从当前时间开始，根据根运动所经过的距离计算应到达的新的时间
						float TimeAfterDistanceTraveled = UE::Anim::DistanceMatchingUtility::GetTimeAfterDistanceTraveled(AnimSequence, CurrentTime, DistanceTraveled, DistanceCurveName, bAllowLooping);

						// 4.2 计算播放速率
						if (TimeAfterDistanceTraveled < CurrentTime)
						{
							TimeAfterDistanceTraveled += CurrentAssetLength;
						}
						float EffectivePlayRate = (TimeAfterDistanceTraveled - CurrentTime) / DeltaTime;

						// 4.3 限制播放速率
						if (PlayRateClamp.X >= 0.0f && PlayRateClamp.X < PlayRateClamp.Y)
						{
							EffectivePlayRate = FMath::Clamp(EffectivePlayRate, PlayRateClamp.X, PlayRateClamp.Y);
						}

						// 5.1 计算步进之后的动画时间
						float NewTime = CurrentTime;
						FAnimationRuntime::AdvanceTime(bAllowLooping, EffectivePlayRate * DeltaTime, NewTime, CurrentAssetLength);

						// 5.2 设置新的动画时间
						if (!InSequenceEvaluator.SetExplicitTime(NewTime))
						{
							UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Could not set explicit time on sequence evaluator, value is not dynamic. Set it as Always Dynamic."));
						}
					}
					else
					{
						UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Sequence evaluator does not have an anim sequence to play."));
					}
				}
			}
			else
			{
				UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("AdvanceTimeByDistanceMatching called with invalid context"));
			}
		});

	return SequenceEvaluator;
}

停步匹配

StopMatch

当角色停止运动时（玩家不再有运动方向的输入），此时角色会逐渐减速，这时需要计算角色的运动距离，然后将这个距离与动画进行匹配

GetPredictedStopDistance：这个函数已经提供了用于预测角色停止运动后的前进距离，在C++中为PredictGroundMovementStopLocation
DistanceMatchToTarget：这个函数用于将预测的距离与动画进行匹配

GetPredictedStopDistance

定义

/**
* Predict where the character will stop based on its current movement properties and parameters from the movement component.
* This uses prediction logic that is heavily tied to the UCharacterMovementComponent.
* Each parameter corresponds to a value from the UCharacterMovementComponent with the same name.
* Because this is a thread safe function, it's	recommended to populate these fields via the Property Access system.
* @return The predicted stop position in local space to the character. The size of this vector will be the distance to the stop location.
*/
UFUNCTION(BlueprintPure, Category = "Animation Character Movement", meta = (BlueprintThreadSafe))
static FVector PredictGroundMovementStopLocation(const FVector& Velocity,
	bool bUseSeparateBrakingFriction, float BrakingFriction, float GroundFriction, float BrakingFrictionFactor, float BrakingDecelerationWalking);

可以看到注释内容为：通过角色移动组件中的属性来预测当角色停止运动时角色移动的位置

Velocity：角色的速度
bUseSeparateBrakingFriction：是否使用单独的制动摩擦力
BrakingFriction：制动摩擦力
GroundFriction：地面摩擦力
BrakingFrictionFactor：制动摩擦力因数
BrakingDecelerationWalking：制动减速度

实现

FVector UAnimCharacterMovementLibrary::PredictGroundMovementStopLocation(const FVector& Velocity, 
	bool bUseSeparateBrakingFriction, float BrakingFriction, float GroundFriction, float BrakingFrictionFactor, float BrakingDecelerationWalking)
{
	// 预测的停止位置
	FVector PredictedStopLocation = FVector::ZeroVector;

	// 选择实际摩檫力
	float ActualBrakingFriction = (bUseSeparateBrakingFriction ? BrakingFriction : GroundFriction);
	// 计算摩檫力
	const float FrictionFactor = FMath::Max(0.f, BrakingFrictionFactor);
	ActualBrakingFriction = FMath::Max(0.f, ActualBrakingFriction * FrictionFactor);
	float BrakingDeceleration = FMath::Max(0.f, BrakingDecelerationWalking);

	// 计算角色的地面速度
	const FVector Velocity2D = Velocity * FVector(1.f, 1.f, 0.f);
	FVector VelocityDir2D;
	float Speed2D;
	Velocity2D.ToDirectionAndLength(VelocityDir2D, Speed2D);

	// 高中数学：x = v * t + 0.5 * a * t^2
	// 这里先计算加速度
	const float Divisor = ActualBrakingFriction * Speed2D + BrakingDeceleration;
	if (Divisor > 0.f)
	{
		// 根据v = a * t计算停止时间
		const float TimeToStop = Speed2D / Divisor;
		// 将时间带入公式计算位置
		PredictedStopLocation = Velocity2D * TimeToStop + 0.5f * ((-ActualBrakingFriction) * Velocity2D - BrakingDeceleration * VelocityDir2D) * TimeToStop * TimeToStop;
	}

	// 将计算结果返回
	return PredictedStopLocation;
}

DistanceMatchToTarget

定义：

/**
* Set the time of the sequence evaluator to the point in the animation where the distance curve matches the DistanceToTarget input.
* A common use case is to achieve stops without foot sliding by, each frame, selecting the point in the animation that matches the distance the character has remaining until it stops.
* Note that because this technique sets the time of the animation by distance remaining, it doesn't respect phase of any previous animation (e.g. from a jog cycle).
* @param SequenceEvaluator - The sequence evaluator node to operate on.
* @param DistanceToTarget - The distance remaining to a target (e.g. a stop or pivot point).
* @param DistanceCurveName - Name of the curve we want to match 
*/
UFUNCTION(BlueprintCallable, Category = "Distance Matching", meta=(BlueprintThreadSafe))
static FSequenceEvaluatorReference DistanceMatchToTarget(const FSequenceEvaluatorReference& SequenceEvaluator,
	float DistanceToTarget, FName DistanceCurveName);

注释为：通过距离来设置序列求值器的播放时间，通过每帧选择动画中与角色剩余距离匹配的点来实现

SequenceEvaluator：序列求值器
DistanceToTarget：目标距离，即预测的行进距离
DistanceCurveName：距离曲线

实现：

FSequenceEvaluatorReference UAnimDistanceMatchingLibrary::DistanceMatchToTarget(const FSequenceEvaluatorReference& SequenceEvaluator,
	float DistanceToTarget, FName DistanceCurveName)
{
	// 同样将一个lambda函数作为参数传递给CallAnimNodeFunction函数
	SequenceEvaluator.CallAnimNodeFunction<FAnimNode_SequenceEvaluator>(
		TEXT("DistanceMatchToTarget"),
		[DistanceToTarget, DistanceCurveName](FAnimNode_SequenceEvaluator& InSequenceEvaluator)
		{
			// 获取当前的动画序列
			if (const UAnimSequenceBase* AnimSequence = Cast<UAnimSequence>(InSequenceEvaluator.GetSequence()))
			{
				// 根据距离获取动画播放到的位置(播放时间)并将这个位置设置给当前播放的动画
				const float NewTime = UE::Anim::DistanceMatchingUtility::GetAnimPositionFromDistance(AnimSequence, -DistanceToTarget, DistanceCurveName);
				if (!InSequenceEvaluator.SetExplicitTime(NewTime))
				{
					UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Could not set explicit time on sequence evaluator, value is not dynamic. Set it as Always Dynamic."));
				}
			}
			else
			{
				UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Sequence evaluator does not have an anim sequence to play."));
			}
			
		});

	return SequenceEvaluator;
}

// 根据位置和距离曲线查找这个动画的时间节点
float GetAnimPositionFromDistance(const UAnimSequenceBase* InAnimSequence, const float& InDistance, FName InCurveName)
{	
	// 获取曲线数据
	FAnimCurveBufferAccess BufferCurveAccess(InAnimSequence, InCurveName);
	if (BufferCurveAccess.IsValid())
	{
		// 获取曲线的key，即在UDistanceCurveModifier中添加的位置
		const int32 NumKeys = BufferCurveAccess.GetNumSamples();
		if (NumKeys < 2)
		{
			return 0.f;
		}

		int32 First = 1;
		int32 Last = NumKeys - 1;
		int32 Count = Last - First;

		// 通过二分法查找符合的距离位置
		while (Count > 0)
		{
			int32 Step = Count / 2;
			int32 Middle = First + Step;

			if (InDistance > BufferCurveAccess.GetValue(Middle))
			{
				First = Middle + 1;
				Count -= Step + 1;
			}
			else
			{
				Count = Step;
			}
		}

		// 将位置转为时间并进行差值获取符合的时间节点
		const float KeyAValue = BufferCurveAccess.GetValue(First - 1);
		const float KeyBValue = BufferCurveAccess.GetValue(First);
		const float Diff = KeyBValue - KeyAValue;
		const float Alpha = !FMath::IsNearlyZero(Diff) ? ((InDistance - KeyAValue) / Diff) : 0.f;

		const float KeyATime = BufferCurveAccess.GetTime(First - 1);
		const float KeyBTime = BufferCurveAccess.GetTime(First);
		return FMath::Lerp(KeyATime, KeyBTime, Alpha);
	}

	return 0.f;
}

流程图

flowchart TD
    A[开始距离匹配] --> B{匹配场景选择}
    
    B --> C[起步匹配]
    B --> D[停步匹配]
    
    %% 起步匹配分支
    subgraph C [起步匹配流程]
        direction LR
        C1[起步动画] --> C2[提取根运动距离曲线]
        C2 --> C3[采样生成Distance曲线<br/>采样率:30Hz]
        C3 --> C4[根据本帧移动距离<br/>查找对应动画时间]
        C4 --> C5[设置动画播放时间<br/>播放速率限制:0.75-1.25]
        C5 --> C6[起步匹配完成]
    end
    
    %% 停步匹配分支
    subgraph D [停步匹配流程]
        direction LR
        D1[停步动画] --> D2[预测停止位置<br/>基于速度/摩擦力/减速度]
        D2 --> D3[计算剩余距离]
        D3 --> D4[反向查找距离曲线<br/>对应时间点]
        D4 --> D5[设置停步动画时间]
        D5 --> D6[停步匹配完成]
    end
    
    C6 --> E[应用匹配动画]
    D6 --> E
    
    E --> F[消除滑步]

注意事项

使用UE版本为5.5.4
确保动画已开启根运动
距离曲线名称需与代码中一致
采样率过高可能导致性能问题

本文作者： KongXinQing
本文链接： https://13114987559.github.io/2025/11/30/essay/距离匹配/
版权声明： 本博客所有文章除特别声明外，均采用 MIT 许可协议。转载请注明出处！