PHY/Plugins/GMS/Source/GenericMovementSystem/Public/Locomotions/GMS_LocomotionStructLibrary.h

// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.

#pragma once

#include "CoreMinimal.h"
#include "GameplayTagContainer.h"
#include "Animation/CachedAnimData.h"
#include "UObject/Object.h"
#include "GMS_LocomotionStructLibrary.generated.h"

class UBlendSpace1D;
class UAnimSequenceBase;
class UAnimSequence;

/**
 * Stores the locomotion state of a character.
 * 存储角色的运动状态。
 */
USTRUCT(BlueprintType)
struct GENERICMOVEMENTSYSTEM_API FGMS_LocomotionState
{
	GENERATED_BODY()

	/**
	 * Indicates if there is active input.
	 * 表示是否有活跃的输入。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	bool bHasInput{false};

	/**
	 * Input yaw angle in world space.
	 * 世界空间中的输入偏航角。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float InputYawAngle{0.0f};

	/**
	 * Indicates if the character has speed.
	 * 表示角色是否有速度。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	bool bHasVelocity{false};

	/**
	 * Current speed of the character.
	 * 角色的当前速度。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = 0, ForceUnits = "cm/s"))
	float Speed{0.0f};

	/**
	 * Current velocity vector.
	 * 当前速度向量。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FVector Velocity{ForceInit};

	/**
	 * Yaw angle of the character's velocity.
	 * 角色速度的偏航角。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float VelocityYawAngle{0.0f};

	/**
	 * Indicates if the character is moving.
	 * 表示角色是否在移动。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	bool bMoving{false};

	/**
	 * Target yaw angle for the actor's rotation.
	 * Actor旋转的目标偏航角。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float TargetYawAngle{0.0f};

	/**
	 * Smoothed target yaw angle for extra smooth rotation.
	 * 用于平滑旋转的平滑目标偏航角。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float SmoothTargetYawAngle{0.0f};

	/**
	 * Angle between view yaw and target yaw.
	 * 视角偏航角与目标偏航角之间的角度。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float ViewRelativeTargetYawAngle{0.0f};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	uint8 bAimingLimitAppliedThisFrame : 1 {false};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	uint8 bResetAimingLimit : 1 {true};

	/**
	 * Limit for the aiming yaw angle.
	 * 瞄准偏航角的限制。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float AimingYawAngleLimit{180.0f};
};


/**
 * Stores the view state of a character.
 * 存储角色的视图状态。
 */
USTRUCT(BlueprintType)
struct GENERICMOVEMENTSYSTEM_API FGMS_ViewState
{
	GENERATED_BODY()

	/**
	 * Smoothed view rotation, set by replicated view rotation.
	 * 平滑的视角旋转，由复制的视角旋转设置。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FRotator Rotation{ForceInit};

	/**
	 * Speed of camera rotation from left to right.
	 * 相机左右旋转的速度。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = 0, ForceUnits = "deg/s"))
	float YawSpeed{0.0f};

	/**
	 * View yaw angle from the previous frame.
	 * 上一帧的视角偏航角。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float PreviousYawAngle{0.0f};
};


USTRUCT(BlueprintType)
struct GENERICMOVEMENTSYSTEM_API FGMS_MovementBaseState
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadWrite, Category="GMS")
	TObjectPtr<UPrimitiveComponent> Primitive;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FName BoneName;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	uint8 bBaseChanged : 1 {false};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	uint8 bHasRelativeLocation : 1 {false};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	uint8 bHasRelativeRotation : 1 {false};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FVector Location{ForceInit};

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FQuat Rotation{ForceInit};

	/**
	 * 基础对象（例如移动平台）从上一帧到当前帧的旋转变化。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	FRotator DeltaRotation{ForceInit};
};


/**
 * Parameters for predicting ground movement stop location.
 * 预测地面运动停止位置的参数。
 */
USTRUCT()
struct FGMS_PredictGroundMovementStopLocationParams
{
	GENERATED_BODY()

	/**
	 * Current velocity vector.
	 * 当前速度向量。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	FVector Velocity{ForceInit};

	/**
	 * Whether to use separate braking friction.
	 * 是否使用单独的制动摩擦。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	bool bUseSeparateBrakingFriction{ForceInit};

	/**
	 * Braking friction value.
	 * 制动摩擦值。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	float BrakingFriction{ForceInit};

	/**
	 * Ground friction value.
	 * 地面摩擦值。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	float GroundFriction{ForceInit};

	/**
	 * Braking friction factor.
	 * 制动摩擦因子。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	float BrakingFrictionFactor{ForceInit};

	/**
	 * Braking deceleration for walking.
	 * 行走时的制动减速度。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	float BrakingDecelerationWalking{ForceInit};
};

/**
 * Parameters for predicting ground movement pivot location.
 * 预测地面运动枢轴位置的参数。
 */
USTRUCT()
struct FGMS_PredictGroundMovementPivotLocationParams
{
	GENERATED_BODY()

	/**
	 * Current acceleration vector.
	 * 当前加速度向量。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	FVector Acceleration{ForceInit};

	/**
	 * Current velocity vector.
	 * 当前速度向量。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	FVector Velocity{ForceInit};

	/**
	 * Ground friction value.
	 * 地面摩擦值。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	float GroundFriction{0.0f};
};

/**
 * Stores animations for four-directional movement.
 * 存储四方向移动的动画。
 */
USTRUCT(BlueprintType)
struct FGMS_Animations_4Direction
{
	GENERATED_BODY()

	/**
	 * Animation for forward movement.
	 * 前进移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Forward = nullptr;

	/**
	 * Animation for backward movement.
	 * 后退移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Backward = nullptr;

	/**
	 * Animation for left movement.
	 * 左移移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Left = nullptr;

	/**
	 * Animation for right movement.
	 * 右移移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Right = nullptr;

	/**
	 * Checks if all animations are valid.
	 * 检查所有动画是否有效。
	 * @return True if all animations are set. 如果所有动画都设置返回true。
	 */
	bool ValidAnimations() const;

	/**
	 * Checks if any animation has root motion.
	 * 检查是否有动画包含根运动。
	 * @return True if any animation has root motion. 如果有动画包含根运动返回true。
	 */
	bool HasRootMotion() const;
};

/**
 * Stores animations for eight-directional movement.
 * 存储八方向移动的动画。
 */
USTRUCT(BlueprintType)
struct FGMS_Animations_8Direction
{
	GENERATED_BODY()

	/**
	 * Animation for forward movement.
	 * 前进移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Forward = nullptr;

	/**
	 * Animation for forward-left movement.
	 * 前左移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> ForwardLeft = nullptr;

	/**
	 * Animation for forward-right movement.
	 * 前右移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> ForwardRight = nullptr;

	/**
	 * Animation for backward movement.
	 * 后退移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Backward = nullptr;

	/**
	 * Animation for backward-left movement.
	 * 后左移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> BackwardLeft = nullptr;

	/**
	 * Animation for backward-right movement.
	 * 后右移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> BackwardRight = nullptr;

	/**
	 * Animation for left movement.
	 * 左移移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Left = nullptr;

	/**
	 * Animation for right movement.
	 * 右移移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> Right = nullptr;

	/**
	 * Checks if all animations are valid.
	 * 检查所有动画是否有效。
	 * @return True if all animations are set. 如果所有动画都设置返回true。
	 */
	bool ValidAnimations() const;

	/**
	 * Checks if any animation has root motion.
	 * 检查是否有动画包含根运动。
	 * @return True if any animation has root motion. 如果有动画包含根运动返回true。
	 */
	bool HasRootMotion() const;
};

/**
 * Stores 1D blend space animations for forward and backward movement.
 * 存储用于前后移动的1D混合空间动画。
 */
USTRUCT(BlueprintType)
struct FGMS_Animations_BS1D_FwdBwd
{
	GENERATED_BODY()

	/**
	 * Blend space for forward movement.
	 * 前进移动的混合空间。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	TObjectPtr<UBlendSpace1D> Forward{nullptr};

	/**
	 * Blend space for backward movement.
	 * 后退移动的混合空间。
	 */
	UPROPERTY(EditAnywhere, Category="GMS")
	TObjectPtr<UBlendSpace1D> Backward{nullptr};
};

/**
 * Stores animations for starting movement while facing forward.
 * 存储面向前进时开始移动的动画。
 */
USTRUCT(BlueprintType)
struct FGMS_Animations_StartForwardFacing
{
	GENERATED_BODY()

	/**
	 * Animation for starting movement forward.
	 * 前进开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForward = nullptr;

	/**
	 * Animation for starting movement forward with a 90-degree left turn.
	 * 前进并向左90度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardL90 = nullptr;

	/**
	 * Animation for starting movement forward with a 90-degree right turn.
	 * 前进并向右90度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardR90 = nullptr;

	/**
	 * Animation for starting movement forward with a 180-degree left turn.
	 * 前进并向左180度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardL180 = nullptr;

	/**
	 * Animation for starting movement forward with a 180-degree right turn.
	 * 前进并向右180度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardR180 = nullptr;
};

/**
 * Stores animations for starting movement while facing forward in eight directions.
 * 存储面向前进时八方向开始移动的动画。
 */
USTRUCT(BlueprintType)
struct FGMS_Animations_StartForwardFacing_8Direction
{
	GENERATED_BODY()

	/**
	 * Animation for starting movement forward.
	 * 前进开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForward = nullptr;

	/**
	 * Animation for starting movement forward with a 90-degree left turn.
	 * 前进并向左90度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardL90 = nullptr;

	/**
	 * Animation for starting movement forward with a 90-degree right turn.
	 * 前进并向右90度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardR90 = nullptr;

	/**
	 * Animation for starting movement forward with a 180-degree left turn.
	 * 前进并向左180度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardL180 = nullptr;

	/**
	 * Animation for starting movement forward with a 180-degree right turn.
	 * 前进并向右180度开始移动的动画。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS")
	TObjectPtr<UAnimSequence> StartForwardR180 = nullptr;
};

/**
 * Stores an animation with an associated distance.
 * 存储与距离关联的动画。
 */
USTRUCT(BlueprintType)
struct GENERICMOVEMENTSYSTEM_API FGMS_AnimationWithDistance
{
	GENERATED_BODY()

	/**
	 * The animation sequence.
	 * 动画序列。
	 */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="GMS")
	TObjectPtr<UAnimSequence> Animation = nullptr;

	/**
	 * The distance associated with the animation.
	 * 与动画关联的距离。
	 */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="GMS", meta=(ClampMin=0))
	float Distance{200};

#if WITH_EDITORONLY_DATA
	/**
	 * Editor-friendly name for the animation.
	 * 动画的编辑器友好名称。
	 */
	UPROPERTY(VisibleAnywhere, Category=AlwaysHidden, Meta=(EditCondition=False, EditConditionHides))
	FString EditorFriendlyName;
#endif
};

/**
 * Maps animation state names to gameplay tags.
 * 将动画状态名称映射到游戏标签。
 */
USTRUCT(BlueprintType)
struct FGMS_AnimStateNameToTag
{
	GENERATED_BODY()

	/**
	 * The gameplay tag for the animation state.
	 * 动画状态的游戏标签。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GMS", meta=(Categories="GMS.SM"))
	FGameplayTag Tag;

	/**
	 * The cached animation state data.
	 * 缓存的动画状态数据。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category= "GMS")
	FCachedAnimStateData State;

	/**
	 * Equality operator for comparing two animation state mappings.
	 * 比较两个动画状态映射的相等运算符。
	 * @param Lhs Left-hand side mapping. 左侧映射。
	 * @param RHS Right-hand side mapping. 右侧映射。
	 * @return True if mappings are equal. 如果映射相等返回true。
	 */
	friend bool operator==(const FGMS_AnimStateNameToTag& Lhs, const FGMS_AnimStateNameToTag& RHS)
	{
		return Lhs.Tag == RHS.Tag
			&& Lhs.State.StateMachineName == RHS.State.StateMachineName && Lhs.State.StateName == RHS.State.StateName;
	}

	/**
	 * Inequality operator for comparing two animation state mappings.
	 * 比较两个动画状态映射的不等运算符。
	 * @param Lhs Left-hand side mapping. 左侧映射。
	 * @param RHS Right-hand side mapping. 右侧映射。
	 * @return True if mappings are not equal. 如果映射不相等返回true。
	 */
	friend bool operator!=(const FGMS_AnimStateNameToTag& Lhs, const FGMS_AnimStateNameToTag& RHS)
	{
		return !(Lhs == RHS);
	}
};

/**
 * Wrapper for a list of animation state to tag mappings.
 * 动画状态到标签映射列表的包装器。
 */
USTRUCT()
struct FGMS_AnimStateNameToTagWrapper
{
	GENERATED_BODY()

	/**
	 * Array of animation state to tag mappings.
	 * 动画状态到标签映射的数组。
	 */
	UPROPERTY()
	TArray<FGMS_AnimStateNameToTag> AnimStateNameToTagMapping;
};