void FAnimNode_OrientationWarping::EvaluateSkeletalControl_AnyThread(FComponentSpacePoseContext& Output, TArray<FBoneTransform>& OutBoneTransforms)
{
	SCOPE_CYCLE_COUNTER(STAT_OrientationWarping_Eval);
	check(OutBoneTransforms.Num() == 0);


	// 需要朝向的角度
	float TargetOrientationAngleRad;

	const float DeltaSeconds = Output.AnimInstanceProxy->GetDeltaSeconds();
	// 最大校正角度,默认为180°
	const float MaxAngleCorrectionRad = FMath::DegreesToRadians(MaxCorrectionDegrees);
	// 围绕哪个角度进行旋转,默认为Yaw轴
	const FVector RotationAxisVector = UE::Anim::GetAxisVector(RotationAxis);
	// 前进方向
	FVector LocomotionForward = FVector::ZeroVector;

	bool bGraphDrivenWarping = false;
	// 提取根运动
	const UE::Anim::IAnimRootMotionProvider* RootMotionProvider = UE::Anim::IAnimRootMotionProvider::Get();

	// 判断是否为图表模式,在该模式下会使用根运动
	if (Mode == EWarpingEvaluationMode::Graph)
	{
		bGraphDrivenWarping = !!RootMotionProvider;
		ensureMsgf(bGraphDrivenWarping, TEXT("Graph driven Orientation Warping expected a valid root motion delta provider interface."));
	}

#if WITH_EDITORONLY_DATA
	bFoundRootMotionAttribute = false;
#endif

#if ENABLE_ANIM_DEBUG
	FTransform RootMotionTransformDelta = FTransform::Identity;
	float RootMotionDeltaAngleRad = 0.0;
	const float PreviousOrientationAngleRad = ActualOrientationAngleRad;
#endif

#if ENABLE_ANIM_DEBUG || ENABLE_VISUAL_LOG
	if (DeltaSeconds > 0)
	{
		bUsedFutureRootMotion = false;
	}
#endif

	// We will likely need to revisit LocomotionAngle participating as an input to orientation warping.
	// Without velocity information from the motion model (such as the capsule), LocomotionAngle isn't enough
	// information in isolation for all cases when deciding to warp.
	//
	// For example imagine that the motion model has stopped moving with zero velocity due to a
	// transition into a strafing stop. During that transition we may play an animation with non-zero 
	// velocity for an arbitrary number of frames. In this scenario the concept of direction is meaningless 
	// since we cannot orient the animation to match a zero velocity and consequently a zero direction, 
	// since that would break the pose. For those frames, we would incorrectly over-orient the strafe.
	//
	// The solution may be instead to pass velocity with the actor base rotation, allowing us to retain
	// speed information about the motion. It may also allow us to do more complex orienting behavior 
	// when multiple degrees of freedom can be considered.

	/**
	 * 尝试翻译:
	 * 我们可能需要重新评估将LocomotionAngle作为朝向角度,当运动的模型(例如角色的胶囊体)不再有速度信息时,
	 * 此时当决定进行扭曲时LocomotionAngle并不能提供足够的信息(大体意思可能为只依赖LocomotionAnlge并不能将扭曲的所有情况都考虑到)
	 *
	 * 考虑一种情况:由于进入停止运动的过渡状态,运动的模型此时的速度为0,在过渡期间我们可能会在任意帧播放一个速度非0的过渡动画,
	 * 在这种场景下朝向是个没有意义的概念，因为我们不能为了匹配一个为0的速度(因为它的方向为0)去旋转动画,此时我们应该停止动画,
	 * 在这些帧中会产生不正确的过渡旋转
	 *
	 * 解决方案为使用一个带有Actor旋转的速度值,这允许我们保留运动的速度信息,
	 * 当多个自由旋转的朝向被考虑时它也能允许我们使用复杂的朝向逻辑
	 */

	// 判断使用的旋转空间
	if (WarpingSpace == EOrientationWarpingSpace::ComponentTransform)
	{
		WarpingSpaceTransform = Output.AnimInstanceProxy->GetComponentTransform();
	}

	// 如果带有根运动则执行下述逻辑
	if (bGraphDrivenWarping)
	{
#if !ENABLE_ANIM_DEBUG
		FTransform RootMotionTransformDelta = FTransform::Identity;
#endif

		// 提取根运动
		bGraphDrivenWarping = RootMotionProvider->ExtractRootMotion(Output.CustomAttributes, RootMotionTransformDelta);

		// Graph driven orientation warping will modify the incoming root motion to orient towards the intended locomotion angle
		if (bGraphDrivenWarping)
		{
#if WITH_EDITORONLY_DATA
			// Graph driven Orientation Warping expects a root motion delta to be present in the attribute stream.
			bFoundRootMotionAttribute = true;
#endif

			// In UE, forward is defined as +x; consequently this is also true when sampling an actor's velocity. Historically the skeletal 
			// mesh component forward will not match the actor, requiring us to correct the rotation before sampling the LocomotionForward.
			// In order to make orientation warping 'pure' in the future we will need to provide more context about the intent of
			// the actor vs the intent of the animation in their respective spaces. Specifically, we will need some form the following information:
			//
			// 1. Actor Forward
			// 2. Actor Velocity
			// 3. Skeletal Mesh Relative Rotation

			/**
			 * 尝试翻译:
			 * 在UE中,+x的方向被定义为正方向;因此当对Actor的速度进行采样是也是如此(?_?)
			 * 骨骼的MeshComponent中的正方向与Actor的正方向并不匹配,这需要我们在对速度正方向进行采样时纠正旋转
			 * 为了让"朝向扭曲"在未来(后续使用)不受干扰我们需要提供更多关于Actor本身的意图和动画的意图作为上下文信息(?_?)
			 *
			 * Actor的正方向
			 * Actor的速度
			 * 对骨骼进行相对旋转
			 */

			// 根据输入朝向的大小判断是否停止,或者说是否有输入朝向
			// LocomotionDirection如果存在则优先使用
			if (LocomotionDirection.SquaredLength() > UE_SMALL_NUMBER)
			{
				// if we have a LocomotionDirection vector, transform into root bone local space
				// 如果有输入朝向则将这个朝向旋转到根运动的空间中
				LocomotionForward = WarpingSpaceTransform.InverseTransformVector(LocomotionDirection);
				LocomotionForward.Normalize();
			}
			else
			{
				// 没有朝向输入
				LocomotionAngle = FRotator::NormalizeAxis(LocomotionAngle);
				// UE-184297 Avoid storing LocomotionAngle in radians in case haven't updated the pinned input, to avoid a DegToRad(RadianValue)
				// 获取旋转角度
				const float LocomotionAngleRadians = FMath::DegreesToRadians(LocomotionAngle);
				// 根据旋转轴获取旋转值
				const FQuat LocomotionRotation = FQuat(RotationAxisVector, LocomotionAngleRadians);
				// 获取骨骼的相对旋转
				const FTransform SkeletalMeshRelativeTransform = Output.AnimInstanceProxy->GetComponentRelativeTransform();
            	const FQuat SkeletalMeshRelativeRotation = SkeletalMeshRelativeTransform.GetRotation();
				// 获取运动朝向
				LocomotionForward = SkeletalMeshRelativeRotation.UnrotateVector(LocomotionRotation.GetForwardVector()).GetSafeNormal();
			}

			// Flatten locomotion direction, along the rotation axis.
			/**
			 * 将运动方向沿着旋转轴的方向进行扁平化，即将运动方向投影到运动平面中使其与旋转轴锤子
			 * 1. 通过点积计算LocomotionForward在RotationAxisVector上的投影长度,并将长度乘以旋转轴得到旋转轴上的向量
			 * 2. 让LocomotionForward减去这个得到的向量,结果为垂直旋转轴的向量
			 * 3. 进行归一化得到运动方向
			 *
			 * 公式为:V_proj = V - (V·Axis)*Axis
			 * 目的是移除在旋转轴方向的分量，只在平面上计算方向
			 */
			LocomotionForward = (LocomotionForward - RotationAxisVector.Dot(LocomotionForward) * RotationAxisVector).GetSafeNormal();

			// @todo: Graph mode using a "manual value" makes no sense. Restructure logic to address this in the future.
			if (bUseManualRootMotionVelocity)
			{
				RootMotionTransformDelta.SetTranslation(ManualRootMotionVelocity * DeltaSeconds);
			}

			// 操作和上一步类似
			// 获取根运动增量
			FVector RootMotionDeltaTranslation = RootMotionTransformDelta.GetTranslation();
			// 保存上一帧的旋转
			const FQuat PreviousRootMotionDeltaRotation = RootMotionDeltaRotation;
			// 这一帧的旋转
			RootMotionDeltaRotation = RootMotionTransformDelta.GetRotation();
			
			// Flatten root motion translation, along the rotation axis.
			// 使用同样的投影操作
			RootMotionDeltaTranslation = RootMotionDeltaTranslation - RotationAxisVector.Dot(RootMotionDeltaTranslation) * RotationAxisVector;

			// Look forward in root motion to determine orientation warping angle if future time specified
			// 获取预测的根运动方向(根据变量注释这是一个实验性的功能,版本为5.5)
			FVector PredictedRootMotionDeltaTranslation = RootMotionDeltaTranslation;
			if (TargetTime > 0 && CurrentAnimAsset)
			{
				if (UAnimSequenceBase* AnimSequence = Cast<UAnimSequenceBase>(CurrentAnimAsset))
				{
					FTransform PredictedRootMotionTransform = AnimSequence->ExtractRootMotion(CurrentAnimAssetTime, TargetTime, false);
					PredictedRootMotionDeltaTranslation = PredictedRootMotionTransform.GetTranslation();
					PredictedRootMotionDeltaTranslation = PredictedRootMotionDeltaTranslation - RotationAxisVector.Dot(PredictedRootMotionDeltaTranslation) * RotationAxisVector;
				}
			}

			// 根据增量计算根运动的速度
			const float RootMotionDeltaSpeed = RootMotionDeltaTranslation.Size() / DeltaSeconds;
			// 如果运动的速度小于速度阈值,则认为朝向角度为0,即角色运动基本停止,此时不再应用朝向扭曲
			if (RootMotionDeltaSpeed < MinRootMotionSpeedThreshold)
			{
				// If we're under the threshold, snap orientation angle to 0, and let interpolation handle the delta
				TargetOrientationAngleRad = 0.0f;
			}
			else
			{
				// 获取根运动朝向
				const FVector PreviousRootMotionDeltaDirection = RootMotionDeltaDirection;
				// Hold previous direction if we can't calculate it from current move delta, because the root is no longer moving
				// 如果根运动已经停止则使用上一帧保存的朝向
				RootMotionDeltaDirection = RootMotionDeltaTranslation.GetSafeNormal(UE_SMALL_NUMBER, PreviousRootMotionDeltaDirection);
				TargetOrientationAngleRad = UE::Anim::SignedAngleRadBetweenNormals(RootMotionDeltaDirection, LocomotionForward, RotationAxisVector);

				// Motion Matching may return an animation that deviates a lot from the movement direction (e.g movement direction going bwd and motion matching could return the fwd animation for a few frames)
				// When that happens, since we use the delta between root motion and movement direction, we would be over-rotating the lower body and breaking the pose during those frames
				// So, when that happens we use the inverse of the root motion direction to calculate our target rotation. 
				// This feels a bit 'hacky' but its the only option I've found so far to mitigate the problem
				// 看翻译似乎是用来适配MotionMatching的
				if (LocomotionAngleDeltaThreshold > 0.f)
				{
					if (FMath::Abs(FMath::RadiansToDegrees(TargetOrientationAngleRad)) > LocomotionAngleDeltaThreshold)
					{
						TargetOrientationAngleRad = FMath::UnwindRadians(TargetOrientationAngleRad + FMath::DegreesToRadians(180.0f));
						RootMotionDeltaDirection = -RootMotionDeltaDirection;
					}
				}

				// If there is translation in predicted root motion, use it if the orientation error is less than current error
				// 判断是否需要使用预测角度
				if (TargetTime > 0 && CurrentAnimAsset && !PredictedRootMotionDeltaTranslation.IsNearlyZero(UE_SMALL_NUMBER))
				{
					PredictedRootMotionDeltaTranslation.Normalize();
					float PredictedOrientationErrorAngleRad = UE::Anim::SignedAngleRadBetweenNormals(PredictedRootMotionDeltaTranslation, LocomotionForward, RotationAxisVector);

					// The future orientation will often match the current, so add a small delta to avoid further testing for same values
					if (FMath::Abs(PredictedOrientationErrorAngleRad) + UE_KINDA_SMALL_NUMBER < FMath::Abs(TargetOrientationAngleRad))
					{
						// Note: Don't update root motion direction, as the root motion direction is what we are playing, 
						// not the future. Updating root motion direction will break counter compensate. 
						// Also, we rely on the built in interp for continuity / smoothness
#if ENABLE_ANIM_DEBUG || ENABLE_VISUAL_LOG
						FutureRootMotionDeltaDirection = PredictedRootMotionDeltaTranslation;
						bUsedFutureRootMotion = true;
#endif
						TargetOrientationAngleRad = PredictedOrientationErrorAngleRad;
					}
				}

				// Don't compensate interpolation by the root motion angle delta if the previous direction isn't valid.
				// 翻译:如果PreviousDirection是个无效值,则不对根运动的角度差值进行插值补偿
				// 如果PreviousDirection不为0并且使用插值补偿则进入下面的逻辑
				// 主要为补偿根运动自身的方向对插值的影响,例如动画本身就带有旋转的情况
				if (bCounterCompenstateInterpolationByRootMotion && !PreviousRootMotionDeltaDirection.IsNearlyZero(UE_SMALL_NUMBER))
				{
#if !ENABLE_ANIM_DEBUG
					float RootMotionDeltaAngleRad;
#endif
					// Counter the interpolated orientation angle by the root motion direction angle delta.
					// This prevents our interpolation from fighting the natural root motion that's flowing through the graph.
					// To correctly measure the amount to counter, we need to unrotate our previous delta direction by our previous rotation
					// As the previous direction delta is relative to the previous rotation delta
					// static float SignedAngleRadBetweenNormals(const FVector& From, const FVector& To, const FVector& Axis)
					// 获取AB两个方向在Axis轴上的角度差值
					RootMotionDeltaAngleRad = UE::Anim::SignedAngleRadBetweenNormals(RootMotionDeltaDirection, PreviousRootMotionDeltaRotation.UnrotateVector(PreviousRootMotionDeltaDirection), RotationAxisVector);
					
					// Root motion may have large deltas i.e. bad blends or sudden direction changes like pivots.
					// If there's an instantaneous pop in root motion direction, this is likely a pivot.
					// 进行夹值限制
					const float MaxRootMotionDeltaToCompensateRad = FMath::DegreesToRadians(MaxRootMotionDeltaToCompensateDegrees);
					if (FMath::Abs(RootMotionDeltaAngleRad) < MaxRootMotionDeltaToCompensateRad)
					{
						CounterCompensateTargetAngleRad += RootMotionDeltaAngleRad;
						float CounterCompensateAngle = FMath::FInterpTo(0, CounterCompensateTargetAngleRad, DeltaSeconds, CounterCompensateInterpSpeed);
						ActualOrientationAngleRad = FMath::UnwindRadians(ActualOrientationAngleRad + CounterCompensateAngle);
						CounterCompensateTargetAngleRad -= CounterCompensateAngle;
					}
				}

				// Rotate the root motion delta fully by the warped angle
				// 将根运动旋转到LocomotionForward的方向
				const FVector WarpedRootMotionTranslationDelta = FQuat(RotationAxisVector, TargetOrientationAngleRad).RotateVector(RootMotionDeltaTranslation);
				RootMotionTransformDelta.SetTranslation(WarpedRootMotionTranslationDelta);
			}

			// Forward the side effects of orientation warping on the root motion contribution for this sub-graph
			// 覆盖根运动
			const bool bRootMotionOverridden = RootMotionProvider->OverrideRootMotion(RootMotionTransformDelta, Output.CustomAttributes);
			ensureMsgf(bRootMotionOverridden, TEXT("Graph driven Orientation Warping expected a root motion delta to be present in the attribute stream prior to warping/overriding it."));
		}
		else
		{
			// Early exit on missing root motion delta attribute
			return;
		}
	} 
	else
	{
		// Manual orientation warping will take the angle directly
		TargetOrientationAngleRad = FRotator::NormalizeAxis(OrientationAngle);
		TargetOrientationAngleRad = FMath::DegreesToRadians(TargetOrientationAngleRad);
	}

	// Optionally interpolate the effective orientation towards the target orientation angle
	// When the orientation warping node becomes relevant, the input pose orientation may not be aligned with the desired orientation.
	// Instead of interpolating this difference, snap to the desired orientation if it's our first update to minimize corrections over-time.
	// 如果需要进行插值的话则进行插值
	if ((RotationInterpSpeed > 0.f) && !bIsFirstUpdate)
	{
		const float SmoothOrientationAngleRad = FMath::FInterpTo(ActualOrientationAngleRad, TargetOrientationAngleRad, DeltaSeconds, RotationInterpSpeed);
		// Limit our interpolation rate to prevent pops.
		// @TODO: Use better, more physically accurate interpolation here.
		ActualOrientationAngleRad = FMath::Clamp(SmoothOrientationAngleRad, ActualOrientationAngleRad - MaxAngleCorrectionRad, ActualOrientationAngleRad + MaxAngleCorrectionRad);
	}
	else
	{
		ActualOrientationAngleRad = TargetOrientationAngleRad;
	}

	// 对实际朝向进行夹值
	ActualOrientationAngleRad = FMath::Clamp(ActualOrientationAngleRad, -MaxAngleCorrectionRad, MaxAngleCorrectionRad);
	// Allow the alpha value of the node to affect the final rotation
	// 应用作用效果
	ActualOrientationAngleRad *= ActualAlpha;

	// 是否应用全局混合权重,默认为false
	if (bScaleByGlobalBlendWeight)
	{
		ActualOrientationAngleRad *= BlendWeight;
	}

#if ENABLE_ANIM_DEBUG
	bool bDebugging = false;
#if WITH_EDITORONLY_DATA
	bDebugging = bDebugging || bEnableDebugDraw;
#else
	constexpr float DebugDrawScale = 1.f;
#endif
	const int32 DebugIndex = CVarAnimNodeOrientationWarpingDebug.GetValueOnAnyThread();
	bDebugging = bDebugging || (DebugIndex > 0);

	if (bDebugging)
	{
		const FTransform ComponentTransform = Output.AnimInstanceProxy->GetComponentTransform();
		const FVector ActorForwardDirection = Output.AnimInstanceProxy->GetActorTransform().GetRotation().GetForwardVector();
		FVector DebugArrowOffset = FVector::ZAxisVector * DebugDrawScale;

		// Draw debug shapes
		{
			const FVector ForwardDirection = bGraphDrivenWarping
				? ComponentTransform.GetRotation().RotateVector(LocomotionForward)
				: ActorForwardDirection;

			Output.AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + ForwardDirection * 100.f * DebugDrawScale,
				40.f * DebugDrawScale, FColor::Red, false, 0.f, 2.f * DebugDrawScale);

			const FVector RotationDirection = bGraphDrivenWarping
				? ComponentTransform.GetRotation().RotateVector(RootMotionDeltaDirection)
				: ActorForwardDirection.RotateAngleAxis(OrientationAngle, RotationAxisVector);

			DebugArrowOffset += FVector::ZAxisVector * DebugDrawScale;
			Output.AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + RotationDirection * 100.f * DebugDrawScale,
				40.f * DebugDrawScale, FColor::Blue, false, 0.f, 2.f * DebugDrawScale);

			if (bUsedFutureRootMotion && bGraphDrivenWarping)
			{
				const FVector FutureRotationDirection = ComponentTransform.GetRotation().RotateVector(FutureRootMotionDeltaDirection);

				Output.AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
					ComponentTransform.GetLocation() + DebugArrowOffset,
					ComponentTransform.GetLocation() + DebugArrowOffset + FutureRotationDirection * 100.f * DebugDrawScale,
					40.f * DebugDrawScale, FColor::Yellow, false, 0.f, 2.f * DebugDrawScale);
			}

			const float ActualOrientationAngleDegrees = FMath::RadiansToDegrees(ActualOrientationAngleRad);
			const FVector WarpedRotationDirection = bGraphDrivenWarping
				? RotationDirection.RotateAngleAxis(ActualOrientationAngleDegrees, RotationAxisVector)
				: ActorForwardDirection.RotateAngleAxis(ActualOrientationAngleDegrees, RotationAxisVector);

			DebugArrowOffset += FVector::ZAxisVector * DebugDrawScale;
			Output.AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + WarpedRotationDirection * 100.f * DebugDrawScale,
				40.f * DebugDrawScale, FColor::Green, false, 0.f, 2.f * DebugDrawScale);
		}

		// Draw text on mesh in world space
		{
			TStringBuilder<1024> DebugLine;

			const float PreviousOrientationAngleDegrees = FMath::RadiansToDegrees(PreviousOrientationAngleRad);
			const float ActualOrientationAngleDegrees = FMath::RadiansToDegrees(ActualOrientationAngleRad);
			const float TargetOrientationAngleDegrees = FMath::RadiansToDegrees(TargetOrientationAngleRad);
			if (Mode == EWarpingEvaluationMode::Manual)
			{
				DebugLine.Appendf(TEXT("\n - Previous Orientation Angle: (%.3fd)"), PreviousOrientationAngleDegrees);
				DebugLine.Appendf(TEXT("\n - Orientation Angle: (%.3fd)"), ActualOrientationAngleDegrees);
				DebugLine.Appendf(TEXT("\n - Target Orientation Angle: (%.3fd)"), TargetOrientationAngleRad);
			}
			else
			{
				if (RotationInterpSpeed > 0.0f)
				{
					DebugLine.Appendf(TEXT("\n - Previous Orientation Angle: (%.3fd)"), FMath::RadiansToDegrees(PreviousOrientationAngleRad));
					DebugLine.Appendf(TEXT("\n - Root Motion Frame Delta Angle: (%.3fd)"), FMath::RadiansToDegrees(RootMotionDeltaAngleRad));
				}
				DebugLine.Appendf(TEXT("\n - Actual Orientation Angle: (%.3fd)"), FMath::RadiansToDegrees(ActualOrientationAngleRad));
				DebugLine.Appendf(TEXT("\n - Target Orientation Angle: (%.3fd)"), FMath::RadiansToDegrees(TargetOrientationAngleRad));
				// Locomotion angle is already in degrees.
				DebugLine.Appendf(TEXT("\n - Locomotion Angle: (%.3fd)"), LocomotionAngle);
				DebugLine.Appendf(TEXT("\n - Root Motion Delta: %s)"), *RootMotionTransformDelta.GetTranslation().ToString());
				DebugLine.Appendf(TEXT("\n - Root Motion Speed: %.3fd)"), RootMotionTransformDelta.GetTranslation().Size() / DeltaSeconds);
			}
			Output.AnimInstanceProxy->AnimDrawDebugInWorldMessage(DebugLine.ToString(), FVector::UpVector * 50.0f, FColor::Yellow, 1.f /*TextScale*/);
		}
	}
#endif

#if ANIM_TRACE_ENABLED
	{
		const float PreviousOrientationAngleDegrees = FMath::RadiansToDegrees(PreviousOrientationAngleRad);
		const float ActualOrientationAngleDegrees = FMath::RadiansToDegrees(ActualOrientationAngleRad);
		const float TargetOrientationAngleDegrees = FMath::RadiansToDegrees(TargetOrientationAngleRad);

		TRACE_ANIM_NODE_VALUE(Output, TEXT("Previous OrientationAngle Degrees"), PreviousOrientationAngleDegrees);
		TRACE_ANIM_NODE_VALUE(Output, TEXT("Actual Orientation Angle Degrees"), ActualOrientationAngleDegrees);
		TRACE_ANIM_NODE_VALUE(Output, TEXT("Target Orientation Angle Degrees"), TargetOrientationAngleDegrees);

		if (Mode == EWarpingEvaluationMode::Graph)
		{
			const float RootMotionDeltaAngleDegrees = FMath::RadiansToDegrees(RootMotionDeltaAngleRad);
			TRACE_ANIM_NODE_VALUE(Output, TEXT("Root Motion Delta Angle Degrees"), RootMotionDeltaAngleDegrees);
			TRACE_ANIM_NODE_VALUE(Output, TEXT("Locomotion Angle"), LocomotionAngle);
			TRACE_ANIM_NODE_VALUE(Output, TEXT("Root Motion Translation Delta"), RootMotionTransformDelta.GetTranslation());

			const float RootMotionSpeed = RootMotionTransformDelta.GetTranslation().Size() / DeltaSeconds;
			TRACE_ANIM_NODE_VALUE(Output, TEXT("Root Motion Speed"), RootMotionSpeed);
		}
	}
#endif
	

#if ENABLE_VISUAL_LOG
	if (FVisualLogger::IsRecording())
	{
		const FTransform ComponentTransform = Output.AnimInstanceProxy->GetComponentTransform();
		const FVector ActorForwardDirection = Output.AnimInstanceProxy->GetActorTransform().GetRotation().GetForwardVector();
		FVector DebugArrowOffset = FVector::ZAxisVector * DebugDrawScale;

		// Draw debug shapes
		{
			const FVector ForwardDirection = bGraphDrivenWarping
				? ComponentTransform.GetRotation().RotateVector(LocomotionForward)
				: ActorForwardDirection;

			UE_VLOG_ARROW(Output.AnimInstanceProxy->GetAnimInstanceObject(), "OrientationWarping", Display,
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + ForwardDirection * 100.f * DebugDrawScale,
				FColor::Red, TEXT(""));

			const FVector RotationDirection = bGraphDrivenWarping
				? ComponentTransform.GetRotation().RotateVector(RootMotionDeltaDirection)
				: ActorForwardDirection.RotateAngleAxis(OrientationAngle, RotationAxisVector);

			DebugArrowOffset += FVector::ZAxisVector * DebugDrawScale;
			UE_VLOG_ARROW(Output.AnimInstanceProxy->GetAnimInstanceObject(), "OrientationWarping", Display,
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + RotationDirection * 100.f * DebugDrawScale,
				FColor::Blue, TEXT(""));

			if (bUsedFutureRootMotion && bGraphDrivenWarping)
			{
				const FVector FutureRotationDirection = ComponentTransform.GetRotation().RotateVector(FutureRootMotionDeltaDirection);

				Output.AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
					ComponentTransform.GetLocation() + DebugArrowOffset,
					ComponentTransform.GetLocation() + DebugArrowOffset + FutureRotationDirection * 100.f * DebugDrawScale,
					40.f * DebugDrawScale, FColor::Yellow, false, 0.f, 2.f * DebugDrawScale);
			}

			const float ActualOrientationAngleDegrees = FMath::RadiansToDegrees(ActualOrientationAngleRad);
			const FVector WarpedRotationDirection = bGraphDrivenWarping
				? RotationDirection.RotateAngleAxis(ActualOrientationAngleDegrees, RotationAxisVector)
				: ActorForwardDirection.RotateAngleAxis(ActualOrientationAngleDegrees, RotationAxisVector);

			DebugArrowOffset += FVector::ZAxisVector * DebugDrawScale;

			UE_VLOG_ARROW(Output.AnimInstanceProxy->GetAnimInstanceObject(), "OrientationWarping", Display,
				ComponentTransform.GetLocation() + DebugArrowOffset,
				ComponentTransform.GetLocation() + DebugArrowOffset + WarpedRotationDirection * 100.f * DebugDrawScale,
				FColor::Green, TEXT(""));
		}
	}
#endif

	// 首先对根骨骼应用旋转
	// DistributedBoneOrientationAlpha(0-1)用于控制旋转骨骼的分配比例,剩余的部分(1-)会应用到脊椎和脚步
	const float RootOffset = FMath::UnwindRadians(ActualOrientationAngleRad * DistributedBoneOrientationAlpha);
	
	// Rotate Root Bone first, as that cheaply rotates the whole pose with one transformation.
	if (!FMath::IsNearlyZero(RootOffset, KINDA_SMALL_NUMBER))
	{
		const FQuat RootRotation = FQuat(RotationAxisVector, RootOffset);
		const FCompactPoseBoneIndex RootBoneIndex(0);
	
		FTransform RootBoneTransform(Output.Pose.GetComponentSpaceTransform(RootBoneIndex));
		RootBoneTransform.SetRotation(RootRotation * RootBoneTransform.GetRotation());
		RootBoneTransform.NormalizeRotation();
		Output.Pose.SetComponentSpaceTransform(RootBoneIndex, RootBoneTransform);
	}

	// 开始旋转脊椎骨
	const int32 NumSpineBones = SpineBoneDataArray.Num();
	const bool bSpineOrientationAlpha = !FMath::IsNearlyZero(DistributedBoneOrientationAlpha, KINDA_SMALL_NUMBER);
	const bool bUpdateSpineBones = (NumSpineBones > 0) && bSpineOrientationAlpha;

	// 对填入的脊椎骨应用反向旋转,抵消根骨骼的旋转,保持上半身相对稳定
	if (bUpdateSpineBones)
	{
		// Spine bones counter rotate body orientation evenly across all bones.
		for (int32 ArrayIndex = 0; ArrayIndex < NumSpineBones; ArrayIndex++)
		{
			const FOrientationWarpingSpineBoneData& BoneData = SpineBoneDataArray[ArrayIndex];
			const FQuat SpineBoneCounterRotation = FQuat(RotationAxisVector, -ActualOrientationAngleRad * DistributedBoneOrientationAlpha * BoneData.Weight);
			check(BoneData.Weight > 0.f);

			FTransform SpineBoneTransform(Output.Pose.GetComponentSpaceTransform(BoneData.BoneIndex));
			SpineBoneTransform.SetRotation((SpineBoneCounterRotation * SpineBoneTransform.GetRotation()));
			SpineBoneTransform.NormalizeRotation();
			Output.Pose.SetComponentSpaceTransform(BoneData.BoneIndex, SpineBoneTransform);
		}
	}
	
	const float IKFootRootOrientationAlpha = 1.f - DistributedBoneOrientationAlpha;
	const bool bUpdateIKFootRoot = (IKFootData.IKFootRootBoneIndex != FCompactPoseBoneIndex(INDEX_NONE)) && !FMath::IsNearlyZero(IKFootRootOrientationAlpha, KINDA_SMALL_NUMBER);

	// Rotate IK Foot Root
	if (bUpdateIKFootRoot)
	{
		// 根据填入的Alpha应用根脚步IK旋转
		const FQuat BoneRotation = FQuat(RotationAxisVector, ActualOrientationAngleRad * IKFootRootOrientationAlpha);

		FTransform IKFootRootTransform(Output.Pose.GetComponentSpaceTransform(IKFootData.IKFootRootBoneIndex));
		IKFootRootTransform.SetRotation(BoneRotation * IKFootRootTransform.GetRotation());
		IKFootRootTransform.NormalizeRotation();
		Output.Pose.SetComponentSpaceTransform(IKFootData.IKFootRootBoneIndex, IKFootRootTransform);

		// IK Feet 
		// These match the root orientation, so don't rotate them. Just preserve root rotation. 
		// We need to update their translation though, since we rotated their parent (the IK Foot Root bone).
		const int32 NumIKFootBones = IKFootData.IKFootBoneIndexArray.Num();
		const bool bUpdateIKFootBones = bUpdateIKFootRoot && (NumIKFootBones > 0);

		// 对脚步IK骨应用反向旋转,保证相对地面稳定
		if (bUpdateIKFootBones)
		{
			const FQuat IKFootRotation = FQuat(RotationAxisVector, -ActualOrientationAngleRad * IKFootRootOrientationAlpha);

			for (int32 ArrayIndex = 0; ArrayIndex < NumIKFootBones; ArrayIndex++)
			{
				const FCompactPoseBoneIndex& IKFootBoneIndex = IKFootData.IKFootBoneIndexArray[ArrayIndex];

				FTransform IKFootBoneTransform(Output.Pose.GetComponentSpaceTransform(IKFootBoneIndex));
				IKFootBoneTransform.SetRotation(IKFootRotation * IKFootBoneTransform.GetRotation());
				IKFootBoneTransform.NormalizeRotation();
				Output.Pose.SetComponentSpaceTransform(IKFootBoneIndex, IKFootBoneTransform);
			}
		}
	}

	// 按照骨骼树进行排序输出骨骼
	OutBoneTransforms.Sort(FCompareBoneTransformIndex());
	bIsFirstUpdate = false;
}

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;
}

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;
        }
    }
}

/**
	 * 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));

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;
}

/**
* 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);

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;
}

/**
* 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);

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;
}

/**
* Set the play rate of the sequence player so that the speed of the animation matches in-game movement speed.
* While distance matching is commonly used for transition animations, cycle animations (walk, jog, etc) typically just adjust their play rate to match
* the in-game movement speed.
* This function assumes that the animation has a constant speed.
* @param SequencePlayer - The sequence player node to operate on.
* @param SpeedToMatch - The in-game movement speed to match. This is usually the current speed of the movement component.
* @param PlayRateClamp - A clamp on how much the animation's play rate can change to match the in-game movement speed. Set to (0,0) for no clamping.
*/
UFUNCTION(BlueprintCallable, Category = "Distance Matching", meta=(BlueprintThreadSafe))
static FSequencePlayerReference SetPlayrateToMatchSpeed(const FSequencePlayerReference& SequencePlayer, 
    float SpeedToMatch, FVector2D PlayRateClamp = FVector2D(0.75f, 1.25f));

FSequencePlayerReference UAnimDistanceMatchingLibrary::SetPlayrateToMatchSpeed(const FSequencePlayerReference& SequencePlayer, float SpeedToMatch, FVector2D PlayRateClamp)
{
    // 绑定了一个lambda函数作为参数一并传入CallAnimNodeFunction中被调用
	SequencePlayer.CallAnimNodeFunction<FAnimNode_SequencePlayer>(
		TEXT("SetPlayrateToMatchSpeed"),
		[SpeedToMatch, PlayRateClamp](FAnimNode_SequencePlayer& InSequencePlayer)
		{
            // 获取当前播放的动画序列
			if (const UAnimSequence* AnimSequence = Cast<UAnimSequence>(InSequencePlayer.GetSequence()))
			{
                // 获取序列的长度，如果长度大于0则进行调整
				const float AnimLength = AnimSequence->GetPlayLength();
				if (!FMath::IsNearlyZero(AnimLength))
				{
					// Calculate the speed as: (distance traveled by the animation) / (length of the animation)
                    // 获取动画从开始到结束的根运动距离并计算平面的移动距离
					const FVector RootMotionTranslation = AnimSequence->ExtractRootMotionFromRange(0.0f, AnimLength).GetTranslation();
					const float RootMotionDistance = RootMotionTranslation.Size2D();
                    // 当角色的移动距离大于0时则进行调整
					if (!FMath::IsNearlyZero(RootMotionDistance))
					{
                        // 获取动画速度
						const float AnimationSpeed = RootMotionDistance / AnimLength;
                        // 获取速度当前的移动速度与动画的速度的比值
						float DesiredPlayRate = SpeedToMatch / AnimationSpeed;
						if (PlayRateClamp.X >= 0.0f && PlayRateClamp.X < PlayRateClamp.Y)
						{
							DesiredPlayRate = FMath::Clamp(DesiredPlayRate, PlayRateClamp.X, PlayRateClamp.Y);
						}

						// 根据比值来动态调整动画的播放速度
						if (!InSequencePlayer.SetPlayRate(DesiredPlayRate))
						{
							UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Could not set play rate on sequence player, value is not dynamic. Set it as Always Dynamic."));
						}
					}
					else
					{
						UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Unable to adjust playrate for animation with no root motion delta (%s)."), *GetNameSafe(AnimSequence));
					}
				}
				else
				{
					UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Unable to adjust playrate for zero length animation (%s)."), *GetNameSafe(AnimSequence));
				}
			}
			else
			{
				UE_LOG(LogAnimDistanceMatchingLibrary, Warning, TEXT("Sequence player does not have an anim sequence to play."));
			}
		});

	return SequencePlayer;
}

void FAnimNode_StrideWarping::Initialize_AnyThread(const FAnimationInitializeContext& Context)
{
	FAnimNode_SkeletalControlBase::Initialize_AnyThread(Context);
	
    // 初始化代理
	AnimInstanceProxy = Context.AnimInstanceProxy;
	// 用于夹值和插值
    StrideScaleModifierState.Reinitialize();
	// 初始化朝向
    ActualStrideDirection = FVector::ForwardVector;
	// 初始化步幅
    ActualStrideScale = 1.f;
#if WITH_EDITORONLY_DATA
    // 调试模式下使用，获取根骨骼的位移和速度
	CachedRootMotionDeltaTranslation = FVector::ZeroVector;
	CachedRootMotionDeltaSpeed = 0.f;
#endif
}

void FAnimNode_StrideWarping::EvaluateSkeletalControl_AnyThread(FComponentSpacePoseContext& Output, TArray<FBoneTransform>& OutBoneTransforms)
{
	SCOPE_CYCLE_COUNTER(STAT_StrideWarping_Eval);
	check(OutBoneTransforms.IsEmpty());

	// 获取当前帧的跨步朝向以及上一帧的朝向
	const FVector PreviousStrideDirection = ActualStrideDirection;
	ActualStrideDirection = StrideDirection;
	// 跨步缩放值->步幅的大小
	ActualStrideScale = StrideScale;

	// 是否使用图表模式
	bool bGraphDrivenWarping = false;
	// 获取根运动提取器,如果改提取器是有效的则使用图表模式
	const UE::Anim::IAnimRootMotionProvider* RootMotionProvider = UE::Anim::IAnimRootMotionProvider::Get();

	// 判断是否为图表模式,在节点的细节面板中可以选择
	if (Mode == EWarpingEvaluationMode::Graph)
	{
		bGraphDrivenWarping = !!RootMotionProvider;
		ensureMsgf(bGraphDrivenWarping, TEXT("Graph driven Stride Warping expected a valid root motion delta provider interface."));
	}

	// 初始化运动距离
	FTransform RootMotionTransformDelta = FTransform::Identity;
#if WITH_EDITORONLY_DATA
	// 编辑器下的调试设置
	bFoundRootMotionAttribute = false;
#else
	FVector CachedRootMotionDeltaTranslation = FVector::ZeroVector;
#endif
	if (bGraphDrivenWarping)
	{
		// 如果根运动是有效的话则提取根运动
		// Output的含义:在AnimInstance更新时会从Root开始递归更新骨骼的pose,这个output就是动画节点左边的连线所计算的pose
		// Graph driven stride warping will override the manual stride direction with the intent of the current animation sub-graph's accumulated root motion
		bGraphDrivenWarping = RootMotionProvider->ExtractRootMotion(Output.CustomAttributes, RootMotionTransformDelta);
		if (bGraphDrivenWarping)
		{
			// 缓存根运动的位移数据
			CachedRootMotionDeltaTranslation = RootMotionTransformDelta.GetTranslation();
			// If there's no root motion delta, keep the previous stride direction
			// 根据两帧之间的位移差值拿到运动的朝向
			ActualStrideDirection = CachedRootMotionDeltaTranslation.GetSafeNormal(UE_SMALL_NUMBER, PreviousStrideDirection);
#if WITH_EDITORONLY_DATA
			// Graph driven Stride Warping expects a root motion delta to be present in the attribute stream.
			// 编辑器下的调试设置
			bFoundRootMotionAttribute = true;
#endif
		}
		// Early exit on missing root motion delta attribute
		// 否则说明在图表模式下没有开启根运动,提前返回
		else if (bDisableIfMissingRootMotion)
		{
			return;
		}
	}

	// 拿到output中的骨骼数据
	const FBoneContainer& RequiredBones = Output.Pose.GetPose().GetBoneContainer();
	// 从output的骨骼数据中拿到脚步ik骨骼的空间网格体数据
	const FTransform IKFootRootTransform = Output.Pose.GetComponentSpaceTransform(IKFootRootBone.GetCompactPoseIndex(RequiredBones));
	// 获取地面的法线向量,一般为(0, 0, 1)
	const FVector ResolvedFloorNormal = FloorNormalDirection.AsComponentSpaceDirection(AnimInstanceProxy, IKFootRootTransform);
	// 获取重力方向,一般默认向下(0 ,0, -1)
	const FVector ResolvedGravityDirection = GravityDirection.AsComponentSpaceDirection(AnimInstanceProxy, IKFootRootTransform);

	// 是否使用地面方向来旋转跨步朝向
	// 根据下面的计算可以得到:
	// 首先将实际跨步方向和地面法线方向进行叉乘,可以得到横向的轴向向量
	// 再将轴向向量和地面法向向量进行叉乘得到实际方向
	// 主要用来处理一些上下坡等非水平面的运动方向
	if (bOrientStrideDirectionUsingFloorNormal)
	{
		const FVector StrideWarpingAxis = ResolvedFloorNormal ^ ActualStrideDirection;
		ActualStrideDirection = StrideWarpingAxis ^ ResolvedFloorNormal;
	}

#if ENABLE_ANIM_DEBUG
	bool bDebugging = false;
#if WITH_EDITORONLY_DATA
	bDebugging = bDebugging || bEnableDebugDraw;
#else
	constexpr float DebugDrawScale = 1.f;
#endif
	bDebugging = bDebugging || CVarAnimNodeStrideWarpingDebug.GetValueOnAnyThread() == 1;
	if (bDebugging)
	{
		// 绘制骨骼信息用于调试
		// Draw Floor Normal
		AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
			AnimInstanceProxy->GetComponentTransform().TransformPosition(IKFootRootTransform.GetLocation()),
			AnimInstanceProxy->GetComponentTransform().TransformPosition(IKFootRootTransform.GetLocation() + ResolvedFloorNormal * 25.f * DebugDrawScale),
			40.f * DebugDrawScale, FColor::Blue, false, 0.f, 2.f * DebugDrawScale);
	}
#endif

	// Get all foot IK Transforms
	// FootData在InitializeBoneReferences中初始化,数据来源与output一致,从节点左边输出的骨骼数据中获取
	for (auto& Foot : FootData)
	{
		Foot.IKFootBoneTransform = Output.Pose.GetComponentSpaceTransform(Foot.IKFootBoneIndex);
#if ENABLE_ANIM_DEBUG
		if (bDebugging
#if WITH_EDITORONLY_DATA
			&& bDebugDrawIKFootOrigin
#endif
		)
		{
			const FVector FootWorldLocation = AnimInstanceProxy->GetComponentTransform().TransformPosition(Foot.IKFootBoneTransform.GetLocation());
			AnimInstanceProxy->AnimDrawDebugSphere(FootWorldLocation, 8.f * DebugDrawScale, 16, FColor::Red);
		}
#endif
	}

	// 如果开启根运动则对实际步幅进行调整
	if (bGraphDrivenWarping)
	{
		// CachedRootMotionDeltaSpeed,存储根运动的速度
#if WITH_EDITORONLY_DATA
		CachedRootMotionDeltaSpeed = CachedRootMotionDeltaTranslation.Size() / CachedDeltaTime;
#else
		const float CachedRootMotionDeltaSpeed = CachedRootMotionDeltaTranslation.Size() / CachedDeltaTime;
#endif

		// 如果速度小于根运动的最小移动速度则不调整步幅
		// 否则根据实际速度对步幅进行等比缩放
		if (CachedRootMotionDeltaSpeed <= MinRootMotionSpeedThreshold)
		{
			// If root motion speed is under the threshold, snap back to no stride adjustment.
			// If interpolation is on, it will blend the result
			ActualStrideScale = 1.0f;
		}
		else
		{
			// Graph driven stride scale factor will be determined by the ratio of the
			// locomotion (capsule/physics) speed against the animation root motion speed
			ActualStrideScale = LocomotionSpeed / CachedRootMotionDeltaSpeed;
		}
	}

	// Allow the opportunity for stride scale clamping and interpolation regardless of evaluation mode
	// 翻译无论采用哪种模式(EWarpingEvaluationMode中的定义),都对步幅进行夹值和插值(可能是用于平滑过渡)
	ActualStrideScale = StrideScaleModifierState.ApplyTo(StrideScaleModifier, ActualStrideScale, CachedDeltaTime);

	// 如果开启了根运动则根据实际的步幅大小对运动位移进行缩放
	// 同时尝试对输入的骨骼数据使用缩放后的位移数据进行覆盖
	if (bGraphDrivenWarping)
	{
		// Forward the side effects of stride warping on the root motion contribution for this sub-graph
		RootMotionTransformDelta.ScaleTranslation(ActualStrideScale);
		const bool bRootMotionOverridden = RootMotionProvider->OverrideRootMotion(RootMotionTransformDelta, Output.CustomAttributes);
		ensureMsgf(bRootMotionOverridden, TEXT("Graph driven Stride Warping expected a root motion delta to be present in the attribute stream prior to warping/overriding it."));
	}

	// 处理脚步ik
	// Scale IK feet bones along Stride Warping Axis, from the Thigh bone location.
	// 翻译:从大腿骨开始沿着跨步扭曲的轴向对脚步ik数据进行缩放
	for (auto& Foot : FootData)
	{
		// Stride Warping along Stride Warping Axis
		// 获取脚步ik骨骼的位置以及大腿骨的位置
		const FVector IKFootLocation = Foot.IKFootBoneTransform.GetLocation();
		const FVector ThighBoneLocation = Output.Pose.GetComponentSpaceTransform(Foot.ThighBoneIndex).GetLocation();

		// Project Thigh Bone Location on plane made of FootIKLocation and FloorPlaneNormal, along Gravity Dir.
		// 翻译:沿着重力方向将大腿骨的位置投影在由脚步ik骨的位置和地面法线所组成的平面上
		// LinePlaneIntersection:线平面交点
		// This will be the StrideWarpingPlaneOrigin
		// 首先判断重力和地面法线是否平行,如果平行,则直接使用脚步ik骨骼的位置
		// 否则进行投影:以脚步ik骨的位置作为平面的原点,以地面的法线作为平面的法线得到一个片面,将大腿骨的位置沿着重力的方向投影在这个平面上
		// 实际得到的就是大腿骨在脚步ik骨位置的运动平面上的投影位置
		const FVector StrideWarpingPlaneOrigin = (FMath::Abs(ResolvedGravityDirection | ResolvedFloorNormal) > DELTA) ? FMath::LinePlaneIntersection(ThighBoneLocation, ThighBoneLocation + ResolvedGravityDirection, IKFootLocation, ResolvedFloorNormal) : IKFootLocation;

		// Project FK Foot along StrideWarping Plane, this will be our Scale Origin
		// 翻译:将脚步ik骨的位置投影在跨步平面上(运动平面)
		// 以上一步得到的投影位置作为平面的原点,实际的运动方向作为该平面的法线构造平面
		// 计算脚步ik骨在这个平面上的投影
		const FVector ScaleOrigin = FVector::PointPlaneProject(IKFootLocation, StrideWarpingPlaneOrigin, ActualStrideDirection);

		// 由IKFootLocation和ScaleOrigin可以计算出脚步ik骨的运动方向,再乘以实际的步幅加上投影位置就是新的脚步骨骼应该在的位置
		// Now the ScaleOrigin and IKFootLocation are forming a line parallel to the floor, and we can scale the IK foot.
		const FVector WarpedLocation = ScaleOrigin + (IKFootLocation - ScaleOrigin) * ActualStrideScale;
		Foot.IKFootBoneTransform.SetLocation(WarpedLocation);

#if ENABLE_ANIM_DEBUG
		if (bDebugging
#if WITH_EDITORONLY_DATA
			&& bDebugDrawIKFootAdjustment
#endif
		)
		{
			const FVector FootWorldLocation = AnimInstanceProxy->GetComponentTransform().TransformPosition(Foot.IKFootBoneTransform.GetLocation());
			AnimInstanceProxy->AnimDrawDebugSphere(FootWorldLocation, 8.f * DebugDrawScale, 16, FColor::Green);

			const FVector ScaleOriginWorldLoc = AnimInstanceProxy->GetComponentTransform().TransformPosition(ScaleOrigin);
			AnimInstanceProxy->AnimDrawDebugSphere(ScaleOriginWorldLoc, 8.f * DebugDrawScale, 16, FColor::Yellow);
		}
#endif
	}

	// 开始计算盆骨偏移,首先进行初始化
	FVector PelvisOffset = FVector::ZeroVector;
	const FCompactPoseBoneIndex PelvisBoneIndex = PelvisBone.GetCompactPoseIndex(RequiredBones);

	// 获取盆骨的位置信息并初始化盆骨的位置
	FTransform PelvisTransform = Output.Pose.GetComponentSpaceTransform(PelvisBoneIndex);
	const FVector InitialPelvisLocation = PelvisTransform.GetLocation();

	// 声明一个容器用于存储所有FK骨骼到盆骨的距离
	TArray<float, TInlineAllocator<10>> FKFootDistancesToPelvis;
	FKFootDistancesToPelvis.Reserve(FootData.Num());

	// 声明一个容器储存所有IK骨骼的位置
	TArray<FVector, TInlineAllocator<10>> IKFootLocations;
	IKFootLocations.Reserve(FootData.Num());

	// 遍历脚步ik骨骼的数据并获取距离和位置信息
	for (auto& Foot : FootData)
	{
		const FVector FKFootLocation = Output.Pose.GetComponentSpaceTransform(Foot.FKFootBoneIndex).GetLocation();
		FKFootDistancesToPelvis.Add(FVector::Dist(FKFootLocation, InitialPelvisLocation));

		const FVector IKFootLocation = Foot.IKFootBoneTransform.GetLocation();
		IKFootLocations.Add(IKFootLocation);
	}

	// Adjust Pelvis down if needed to keep foot contact with the ground and prevent over-extension
	// 翻译:将盆骨的位置向下进行调整以保证脚步解除地面同时防止过度拉伸
	PelvisTransform = PelvisIKFootSolver.Solve(PelvisTransform, FKFootDistancesToPelvis, IKFootLocations, CachedDeltaTime);

#if ENABLE_ANIM_DEBUG
	if (bDebugging
#if WITH_EDITORONLY_DATA
		&& bDebugDrawPelvisAdjustment
#endif
	)
	{
		// Draw Adjustments in Pelvis location
		AnimInstanceProxy->AnimDrawDebugSphere(AnimInstanceProxy->GetComponentTransform().TransformPosition(InitialPelvisLocation), 8.f * DebugDrawScale, 16, FColor::Red);
		AnimInstanceProxy->AnimDrawDebugSphere(AnimInstanceProxy->GetComponentTransform().TransformPosition(PelvisTransform.GetLocation()), 8.f * DebugDrawScale, 16, FColor::Blue);
	}

	if (bDebugging)
	{
		// Draw Stride Direction
		AnimInstanceProxy->AnimDrawDebugDirectionalArrow(
			AnimInstanceProxy->GetComponentTransform().TransformPosition(InitialPelvisLocation),
			AnimInstanceProxy->GetComponentTransform().TransformPosition(InitialPelvisLocation + ActualStrideDirection * ActualStrideScale * 100.f * DebugDrawScale),
			40.f * DebugDrawScale, FColor::Red, false, 0.f, 2.f * DebugDrawScale);

		// Draw text on mesh in world space
		{
			TStringBuilder<1024> DebugLine;

			DebugLine.Appendf(TEXT("\n - Stride Scale: (%.3fd)"), ActualStrideScale);
			DebugLine.Appendf(TEXT("\n - Stride Direction: (%s)"), *(ActualStrideDirection.ToCompactString()));
			
			if (Mode == EWarpingEvaluationMode::Graph)
			{
				DebugLine.Appendf(TEXT("\n - Locomotion Speed: (%.3fd)"), LocomotionSpeed);

#if WITH_EDITORONLY_DATA
				if (bFoundRootMotionAttribute)
				{
					DebugLine.Appendf(TEXT("\n - Root Motion: Direction(%s), Speed(%.3fd)"), *(CachedRootMotionDeltaTranslation.GetSafeNormal().ToCompactString()), CachedRootMotionDeltaSpeed);
				}
				else
				{
					DebugLine.Appendf(TEXT("\n - Root Motion: NO ATTRIBUTE FOUND"), *(ActualStrideDirection.ToCompactString()));
				}
#endif

				DebugLine.Appendf(TEXT("\n - Min Root Motion Speed Threshold: (%.3fd)"), MinRootMotionSpeedThreshold);
			}

			AnimInstanceProxy->AnimDrawDebugInWorldMessage(DebugLine.ToString(), FVector::UpVector * 50.0f, FColor::Yellow, 1.f /*TextScale*/);
		}
	}
#endif
	// Add adjusted pelvis transform
	check(!PelvisTransform.ContainsNaN());
	// 将盆骨偏移后的位置数据添加到输出骨骼中
	OutBoneTransforms.Add(FBoneTransform(PelvisBoneIndex, PelvisTransform));

	// Compute final offset to use below
	// 获取盆骨调整后的差值
	PelvisOffset = (PelvisTransform.GetLocation() - InitialPelvisLocation);

	// Rotate Thigh bones to help IK, and maintain leg shape.
	// 翻译:旋转大腿骨骼以适配脚步ik,同时保证腿部的形状(应该是为了防止位移过大导致变形)
	if (bCompensateIKUsingFKThighRotation)
	{
		for (auto& Foot : FootData)
		{
			// 获取大腿骨位置和脚步位置
			const FTransform ThighTransform = Output.Pose.GetComponentSpaceTransform(Foot.ThighBoneIndex);
			const FTransform FKFootTransform = Output.Pose.GetComponentSpaceTransform(Foot.FKFootBoneIndex);

			// 将盆骨偏移应用的大腿骨的位置中
			FTransform AdjustedThighTransform = ThighTransform;
			AdjustedThighTransform.AddToTranslation(PelvisOffset);

			// 获取当前的脚步-大腿朝向以及目标的脚步-大腿朝向
			const FVector InitialDir = (FKFootTransform.GetLocation() - ThighTransform.GetLocation()).GetSafeNormal();
			const FVector TargetDir = (Foot.IKFootBoneTransform.GetLocation() - AdjustedThighTransform.GetLocation()).GetSafeNormal();
			
#if ENABLE_ANIM_DEBUG
			if (bDebugging
#if WITH_EDITORONLY_DATA
				&& bDebugDrawThighAdjustment
#endif
			)
			{
				AnimInstanceProxy->AnimDrawDebugLine(
					AnimInstanceProxy->GetComponentTransform().TransformPosition(ThighTransform.GetLocation()),
					AnimInstanceProxy->GetComponentTransform().TransformPosition(FKFootTransform.GetLocation()),
					FColor::Red, false, 0.f, 2.f * DebugDrawScale);

				AnimInstanceProxy->AnimDrawDebugLine(
					AnimInstanceProxy->GetComponentTransform().TransformPosition(AdjustedThighTransform.GetLocation()),
					AnimInstanceProxy->GetComponentTransform().TransformPosition(Foot.IKFootBoneTransform.GetLocation()),
					FColor::Green, false, 0.f, 2.f * DebugDrawScale);
			}
#endif
			// Find Delta Rotation take takes us from Old to New dir
			// 获取两个方向之间的旋转值
			const FQuat DeltaRotation = FQuat::FindBetweenNormals(InitialDir, TargetDir);

			// Rotate our Joint quaternion by this delta rotation
			// 将旋转值应用值大腿骨
			AdjustedThighTransform.SetRotation(DeltaRotation * AdjustedThighTransform.GetRotation());

			// Add adjusted thigh transform
			check(!AdjustedThighTransform.ContainsNaN());
			// 将调整后的骨骼添加到输出中
			OutBoneTransforms.Add(FBoneTransform(Foot.ThighBoneIndex, AdjustedThighTransform));

			// Clamp IK Feet bone based on FK leg. To prevent over-extension and preserve animated motion.
			// 通过大腿的FK限制脚步IK防止腿部过度拉伸
			// 如果调整后的脚步IK骨与调整后的大腿骨的距离大于FK的距离则使用FK的距离重新调整这个脚步IK的位置
			if (bClampIKUsingFKLimits)
			{
				const float FKLength = FVector::Dist(FKFootTransform.GetLocation(), ThighTransform.GetLocation());
				const float IKLength = FVector::Dist(Foot.IKFootBoneTransform.GetLocation(), AdjustedThighTransform.GetLocation());
				if (IKLength > FKLength)
				{
					const FVector ClampedFootLocation = AdjustedThighTransform.GetLocation() + TargetDir * FKLength;
					Foot.IKFootBoneTransform.SetLocation(ClampedFootLocation);
				}
			}
		}
	}

	// Add final IK feet transforms
	// 将调整后的脚步数据应用到输出数据中
	for (auto& Foot : FootData)
	{
#if ENABLE_ANIM_DEBUG
		if (bDebugging
#if WITH_EDITORONLY_DATA
			&& bDebugDrawIKFootFinal
#endif
		)
		{
			AnimInstanceProxy->AnimDrawDebugSphere(AnimInstanceProxy->GetComponentTransform().TransformPosition(Foot.IKFootBoneTransform.GetLocation()), 8.f * DebugDrawScale, 16, FColor::Blue);
		}
#endif
		check(!Foot.IKFootBoneTransform.ContainsNaN());
		OutBoneTransforms.Add(FBoneTransform(Foot.IKFootBoneIndex, Foot.IKFootBoneTransform));
	}

	// Sort OutBoneTransforms so indices are in increasing order.
	// 按照骨骼树的位置对骨骼进行排序让其对应骨骼树中的索引
	OutBoneTransforms.Sort(FCompareBoneTransformIndex());
}