OLS/Source/OLSAnimation/Public/Libraries/OLSLocomotionBPLibrary.h

// © 2024 Long Ly. All rights reserved. Any unauthorized use, reproduction, or distribution of this trademark is strictly prohibited and may result in legal action.

#pragma once

#include "CoreMinimal.h"
#include "SequenceEvaluatorLibrary.h"
#include "Data/OLSEnumLibrary.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "OLSLocomotionBPLibrary.generated.h"

/**
 * 
 */
UCLASS()
class OLSANIMATION_API UOLSLocomotionBPLibrary : public UBlueprintFunctionLibrary
{
	GENERATED_BODY()

public:

	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static float FindPivotTime(const UAnimSequenceBase* animSequence, const float sampleRate);

	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static float GetCurveValueAtTime(const UAnimSequenceBase* animSequence, const float time, const FName& curveName);
	
	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static float GetTimeAtDistance(const UAnimSequenceBase* animSequence, const float& distance, FName curveName);
	
	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static float GetDistanceRange(const UAnimSequenceBase* animSequence, const FName& curveName);
	
	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static float GetTimeAfterDistanceTraveled(const UAnimSequenceBase* animSequence,
	                                          float currentTime,
	                                          float distanceTraveled, 
	                                          FName curveName,
	                                          const bool shouldAllowLooping);
	
	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static FSequenceEvaluatorReference AdvanceTimeByDistanceMatching(float& outDesiredPlayRate,
																	 const FAnimUpdateContext& updateContext,
	                                                                 const FSequenceEvaluatorReference& sequenceEvaluator,
	                                                                 const float distanceTraveled,
	                                                                 const FName curveName,
	                                                                 const FVector2D playRateClamp = FVector2D(0.75f, 1.25f));


	/**
	 * Adjusts the playback time of an animation sequence to match a specified distance to a target.
	 *
	 * This function ensures that the animation sequence progresses or adjusts its time based on the distance to a target.
	 * It uses a distance curve to determine the appropriate time within the animation sequence that corresponds to the desired distance.
	 * 
	 * @param updateContext            The context for the current animation update, providing necessary time and state information.
	 * @param sequenceEvaluator        A reference to the sequence evaluator, which controls and tracks the animation sequence being played.
	 * @param distanceToTarget         The distance to the target that the animation should match. 
	 *                                 Typically, negative values indicate distance curves storing negative distance.
	 * @param shouldDistanceMatchStop  If true, the distance matching stops once the character reaches the target or passes the threshold.
	 * @param stopDistanceThreshHold   The distance threshold at which distance matching should stop.
	 *                                 If the evaluated distance curve value exceeds this threshold, distance matching will halt.
	 * @param animEndTime              The end time of the animation sequence. If greater than 0, the sequence will not advance past this time.
	 * @param curveName                The name of the curve within the animation sequence that stores distance information.
	 *                                 This curve is evaluated to determine the time corresponding to the distance to the target.
	 * 
	 * @return                         An updated sequence evaluator reference, reflecting the adjusted or advanced animation time.
	 */
	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static FSequenceEvaluatorReference DistanceMatchToTarget(const FAnimUpdateContext& updateContext,
	                                                         const FSequenceEvaluatorReference& sequenceEvaluator,
	                                                         float distanceToTarget,
	                                                         bool shouldDistanceMatchStop, float stopDistanceThreshHold,
	                                                         float animEndTime,
	                                                         FName curveName);

	/**
	 * 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 = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static FSequencePlayerReference SetPlayRateToMatchSpeed(const FSequencePlayerReference& sequencePlayer, 
		float speedToMatch, FVector2D playRateClamp = FVector2D(0.75f, 1.25f));

	/**
	 * 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(BlueprintCallable, BlueprintPure, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static FVector PredictGroundMovementStopLocation(const FVector& velocity, bool shouldUseSeparateBrakingFriction,
													 float brakingFriction, float groundFriction,
													 float brakingFrictionFactor, float brakingDecelerationWalking);

	/**
	 * Predict where the character will change direction during a pivot 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 pivot position in local space to the character. The size of this vector will be the distance to the pivot.
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "OLS|Function Library", meta=(BlueprintThreadSafe))
	static FVector PredictGroundMovementPivotLocation(const FVector& acceleration, const FVector& velocity,
													  float groundFriction);
	
public:
	
	UFUNCTION(BlueprintCallable,BlueprintPure,Category = "OLS|Function Library",meta=(BlueprintThreadSafe))
	static EOLSCardinalDirection SelectCardinalDirectionFromAngle(float angle, float deadZone, EOLSCardinalDirection currentDirection, bool useCurrentDirection = false);

	UFUNCTION(BlueprintCallable,BlueprintPure,Category = "OLS|Function Library",meta=(BlueprintThreadSafe))
	static EOLSCardinalDirection GetOppositeCardinalDirectional(EOLSCardinalDirection currentDirection);
	
	UFUNCTION(BlueprintCallable,BlueprintPure,Category = "OLS|Function Library",meta=(BlueprintThreadSafe))
	static EOLSHipDirection GetOppositeHipDirection(EOLSHipDirection currentHipDirection);
	
public:

	UFUNCTION(BlueprintCallable, Category = "OLS|Function Library")
	static void TryLinkAnimLayer(USkeletalMeshComponent* mesh, TSubclassOf<UAnimInstance> animClass, FName groupName, bool shouldUnlinkGroupIfInvalid);
};