PHY/Plugins/GMS/Source/GenericMovementSystem/Public/GMS_MovementSystemComponent.h

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

#pragma once

#include "CoreMinimal.h"
#include "Engine/NetSerialization.h"
#include "Components/ActorComponent.h"
#include "Locomotions/GMS_LocomotionStructLibrary.h"
#include "Settings/GMS_SettingStructLibrary.h"
#include "Utility/GMS_Tags.h"
#include "GMS_MovementSystemComponent.generated.h"

class IPoseSearchTrajectoryPredictorInterface;
class UGMS_MainAnimInstance;
class UGMS_MovementControlSetting_Default;
class UGMS_AnimGraphSetting;
class UGMS_MovementSystemComponentSettings;
class APawn;
class UAnimInstance;
class UGMS_MovementDefinition;

/**
 * Delegate for movement set change events.
 * 运动集更改事件的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FMovementSetChangedSignature, const FGameplayTag&, PreviousMovementSet);

/**
 * Delegate for movement state change events.
 * 运动状态更改事件的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FMovementChangedSignature, const FGameplayTag&, PreviousMovement);

/**
 * Delegate for overlay mode change events.
 * 覆盖模式更改事件的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOverlayModeChangedSignature, const FGameplayTag&, PreviousMovement);

/**
 * Delegate for rotation mode change events.
 * 旋转模式更改事件的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FRotationModeChangedSignature, const FGameplayTag&, PreviousRotationMode);

/**
 * Delegate for locomotion mode change events.
 * 运动模式更改事件的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FLocomotionModeChangedSignature, const FGameplayTag&, PreviousLocomotionMode);

/**
 * Base movement system component.
 * 基础运动系统组件。
 * @details This is the bridge between the movement logic part and animation part. 这是运动逻辑和动画之间的桥梁。
 */
UCLASS(BlueprintType, Abstract, NotBlueprintable, HideCategories = (Navigation,Cooking,ComponentReplication,Sockets))
class GENERICMOVEMENTSYSTEM_API UGMS_MovementSystemComponent : public UActorComponent
{
	GENERATED_BODY()

	friend UGMS_MainAnimInstance;

public:
	/**
	 * Constructor with object initializer.
	 * 使用对象初始化器构造函数。
	 */
	explicit UGMS_MovementSystemComponent(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get());

	virtual void PostLoad() override;
	/**
	 * Initializes the component.
	 * 初始化组件。
	 */
	virtual void InitializeComponent() override;

	/**
	 * Called when the game starts.
	 * 游戏开始时调用。
	 */
	virtual void BeginPlay() override;

	/**
	 * Gets lifetime replicated properties.
	 * 获取生命周期复制属性。
	 * @param OutLifetimeProps The lifetime properties. 生命周期属性。
	 */
	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

	/**
	 * Gets the movement system component from an actor.
	 * 从Actor获取运动系统组件。
	 * @param Actor The actor to query. 要查询的Actor。
	 * @return The movement system component. 运动系统组件。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem", meta=(DefaultToSelf="Actor", DisplayName="Get Movement System Component"))
	static UGMS_MovementSystemComponent* GetMovementSystemComponent(const AActor* Actor);

	/**
	 * Finds the movement system component on an actor.
	 * 在Actor上查找运动系统组件。
	 * @param Actor The actor to query. 要查询的Actor。
	 * @param Instance The found instance (output). 找到的实例（输出）。
	 * @return True if found. 如果找到返回true。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", meta=(DisplayName="Find Movement System Component", DefaultToSelf="Actor", ExpandBoolAsExecs = "ReturnValue"))
	static bool K2_FindMovementComponent(const AActor* Actor, UGMS_MovementSystemComponent*& Instance);

	/**
	 * Finds the movement system component with a specific class.
	 * 查找特定类的运动系统组件。
	 * @param Actor The actor to query. 要查询的Actor。
	 * @param DesiredClass The desired component class. 期望的组件类。
	 * @param Instance The found instance (output). 找到的实例（输出）。
	 * @return True if found. 如果找到返回true。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem",
		meta=(DisplayName="Find Movement System Component(Ext)", DefaultToSelf="Actor", ExpandBoolAsExecs = "ReturnValue", DeterminesOutputType=DesiredClass, DynamicOutputParam="Instance"))
	static bool K2_FindMovementComponentExt(const AActor* Actor, TSubclassOf<UGMS_MovementSystemComponent> DesiredClass, UGMS_MovementSystemComponent*& Instance);

	/**
	 * Gets combined gameplay tags from owned tags and tag provider.
	 * 获取拥有的标签和标签提供者的合并游戏标签。
	 * @return The combined gameplay tags. 合并的游戏标签。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem", meta=(BlueprintThreadSafe))
	FGameplayTagContainer GetGameplayTags() const;

	/**
	 * Sets the gameplay tags provider.
	 * 设置游戏标签提供者。
	 * @param Provider The object providing gameplay tags. 提供游戏标签的对象。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void SetGameplayTagsProvider(UObject* Provider);

#pragma region GameplayTags

	/**
	 * Adds a single gameplay tag.
	 * 添加单个游戏标签。
	 * @param TagToAdd The tag to add. 要添加的标签。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void AddGameplayTag(FGameplayTag TagToAdd);

	/**
	 * Removes a single gameplay tag.
	 * 移除单个游戏标签。
	 * @param TagToRemove The tag to remove. 要移除的标签。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void RemoveGameplay(FGameplayTag TagToRemove);

	/**
	 * Sets gameplay tags, overriding existing ones.
	 * 设置游戏标签，覆盖现有标签。
	 * @param TagsToSet The new tags to set. 要设置的新标签。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void SetGameplayTags(FGameplayTagContainer TagsToSet);

private:
	/**
	 * Adds a gameplay tag with optional RPC.
	 * 添加游戏标签，可选择是否发送RPC。
	 * @param TagToAdd The tag to add. 要添加的标签。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void AddGameplayTag(const FGameplayTag& TagToAdd, bool bSendRpc);

	/**
	 * Removes a gameplay tag with optional RPC.
	 * 移除游戏标签，可选择是否发送RPC。
	 * @param TagToRemove The tag to remove. 要移除的标签。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void RemoveGameplayTag(const FGameplayTag& TagToRemove, bool bSendRpc);

	/**
	 * Sets gameplay tags with optional RPC.
	 * 设置游戏标签，可选择是否发送RPC。
	 * @param TagsToSet The new tags to set. 要设置的新标签。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void SetGameplayTags(const FGameplayTagContainer& TagsToSet, bool bSendRpc);

	/**
	 * Client RPC to add a gameplay tag.
	 * 客户端RPC添加游戏标签。
	 * @param TagToAdd The tag to add. 要添加的标签。
	 */
	UFUNCTION(Client, Reliable)
	void ClientAddGameplayTag(const FGameplayTag& TagToAdd);

	/**
	 * Server RPC to add a gameplay tag.
	 * 服务器RPC添加游戏标签。
	 * @param TagToAdd The tag to add. 要添加的标签。
	 */
	UFUNCTION(Server, Reliable)
	void ServerAddGameplayTag(const FGameplayTag& TagToAdd);

	/**
	 * Client RPC to remove a gameplay tag.
	 * 客户端RPC移除游戏标签。
	 * @param TagToRemove The tag to remove. 要移除的标签。
	 */
	UFUNCTION(Client, Reliable)
	void ClientRemoveGameplayTag(const FGameplayTag& TagToRemove);

	/**
	 * Server RPC to remove a gameplay tag.
	 * 服务器RPC移除游戏标签。
	 * @param TagToRemove The tag to remove. 要移除的标签。
	 */
	UFUNCTION(Server, Reliable)
	void ServerRemoveGameplayTag(const FGameplayTag& TagToRemove);

	/**
	 * Client RPC to set gameplay tags.
	 * 客户端RPC设置游戏标签。
	 * @param TagsToSet The new tags to set. 要设置的新标签。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetGameplayTags(const FGameplayTagContainer& TagsToSet);

	/**
	 * Server RPC to set gameplay tags.
	 * 服务器RPC设置游戏标签。
	 * @param TagsToSet The new tags to set. 要设置的新标签。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetGameplayTags(const FGameplayTagContainer& TagsToSet);

#pragma endregion

#pragma region Abstraction

public:
	virtual TScriptInterface<IPoseSearchTrajectoryPredictorInterface> GetTrajectoryPredictor() const;

	/**
	 * Checks if the character is crouching.
	 * 检查角色是否在蹲伏。
	 * @return True if crouching. 如果在蹲伏返回true。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem", meta=(BlueprintThreadSafe))
	virtual bool IsCrouching() const;

	/**
	 * Gets the maximum speed.
	 * 获取最大速度。
	 * @return The maximum speed. 最大速度。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual float GetMaxSpeed() const;

	/**
	 * Gets the scaled capsule radius.
	 * 获取缩放的胶囊体半径。
	 * @return The capsule radius. 胶囊体半径。
	 */
	virtual float GetScaledCapsuleRadius() const { return 0.0f; };

	/**
	 * Gets the scaled capsule half height.
	 * 获取缩放的胶囊体半高。
	 * @return The capsule half height. 胶囊体半高。
	 */
	virtual float GetScaledCapsuleHalfHeight() const { return 0.0f; };

	/**
	 * Gets the maximum acceleration.
	 * 获取最大加速度。
	 * @return The maximum acceleration. 最大加速度。
	 */
	virtual float GetMaxAcceleration() const;

	/**
	 * Gets the maximum braking deceleration.
	 * 获取最大制动减速度。
	 * @return The maximum braking deceleration. 最大制动减速度。
	 */
	virtual float GetMaxBrakingDeceleration() const { return 0; };

	/**
	 * Gets the walkable floor Z value.
	 * 获取可行走地面Z值。
	 * @return The walkable floor Z. 可行走地面Z值。
	 */
	virtual float GetWalkableFloorZ() const { return 0; }

	/**
	 * Gets the gravity Z value.
	 * 获取重力Z值。
	 * @return The gravity Z. 重力Z值。
	 */
	virtual float GetGravityZ() const { return 0; }

	/**
	 * Gets the skeletal mesh component.
	 * 获取骨骼网格组件。
	 * @return The skeletal mesh component. 骨骼网格组件。
	 */
	virtual USkeletalMeshComponent* GetMesh() const { return nullptr; };

	/** Returns true if currently moving on the ground (e.g. walking or driving) */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", meta=(BlueprintThreadSafe))
	virtual bool IsMovingOnGround() const;

#pragma endregion

#pragma region Locomotion

	/**
	 * Gets the locomotion state.
	 * 获取运动状态。
	 * @return The locomotion state. 运动状态。
	 */
	const FGMS_LocomotionState& GetLocomotionState() const;

	/**
	 * Gets the locomotion mode.
	 * 获取运动模式。
	 * @return The locomotion mode. 运动模式。
	 */
	const FGameplayTag& GetLocomotionMode() const;

	const FGMS_MovementBaseState& GetMovementBase() const;

	/**
	 * Sets the locomotion mode.
	 * 设置运动模式。
	 * @param NewLocomotionMode The new locomotion mode. 新运动模式。
	 */
	void SetLocomotionMode(const FGameplayTag& NewLocomotionMode);

protected:
	/**
	 * Sets the desired velocity yaw angle.
	 * 设置期望的速度偏航角。
	 * @param NewDesiredVelocityYawAngle The new velocity yaw angle. 新速度偏航角。
	 */
	void SetDesiredVelocityYawAngle(float NewDesiredVelocityYawAngle);

	/**
	 * Server RPC to set the desired velocity yaw angle.
	 * 服务器RPC设置期望的速度偏航角。
	 * @param NewDesiredVelocityYawAngle The new velocity yaw angle. 新速度偏航角。
	 */
	UFUNCTION(Server, Unreliable)
	void ServerSetDesiredVelocityYawAngle(float NewDesiredVelocityYawAngle);
	virtual void ServerSetDesiredVelocityYawAngle_Implementation(float NewDesiredVelocityYawAngle);

	/**
	 * Called when the locomotion mode is replicated.
	 * 运动模式复制时调用。
	 * @param PreviousLocomotionMode The previous locomotion mode. 之前的运动模式。
	 */
	UFUNCTION()
	virtual void OnReplicated_LocomotionMode(const FGameplayTag& PreviousLocomotionMode);

	/**
	 * Called when the locomotion mode changes.
	 * 运动模式更改时调用。
	 * @param PreviousLocomotionMode The previous locomotion mode. 之前的运动模式。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	void OnLocomotionModeChanged(const FGameplayTag& PreviousLocomotionMode);
	virtual void OnLocomotionModeChanged_Implementation(const FGameplayTag& PreviousLocomotionMode);

#pragma endregion

#pragma region MovementBase

	virtual void RefreshMovementBase();

#pragma endregion

#pragma region MovementSet

public:
	/**
	 * Gets the current movement set.
	 * 获取当前运动集。
	 * @return The current movement set. 当前运动集。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	const FGameplayTag& GetMovementSet() const;

	/**
	 * Gets the current movement definition.
	 * 获取当前运动定义。
	 * @return The movement definition. 运动定义。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	TSoftObjectPtr<const UGMS_MovementDefinition> GetMovementDefinition() const;

	/**
	 * Gets the previous movement definition.
	 * 获取之前的运动定义。
	 * @return The previous movement definition. 之前的运动定义。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	TSoftObjectPtr<const UGMS_MovementDefinition> GetPrevMovementDefinition() const;

	/**
	 * Gets the current loaded movement definition.
	 * 获取当前已经加载的运动定义。
	 * @return The movement definition. 运动定义。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	const UGMS_MovementDefinition* GetLoadedMovementDefinition() const;

	/**
	 * Gets the current movement set setting.
	 * 获取当前运动集设置。
	 * @return The movement set setting. 运动集设置。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual const FGMS_MovementSetSetting& GetMovementSetSetting() const;

	/**
	 * Gets the current movement state setting.
	 * 获取当前运动状态设置。
	 * @return The movement state setting. 运动状态设置。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	const FGMS_MovementStateSetting& GetMovementStateSetting() const;

	/**
	 * Gets the current control setting.
	 * 获取当前控制设置。
	 * @return The control setting. 控制设置。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	const UGMS_MovementControlSetting_Default* GetControlSetting() const;

	/**
	 * Gets the number of movement state settings.
	 * 获取运动状态设置的数量。
	 * @return The number of movement state settings. 运动状态设置数量。
	 */
	int32 GetNumOfMovementStateSettings() const;

	/**
	 * Sets the movement set.
	 * 设置运动集。
	 * @param NewMovementSet The new movement set. 新运动集。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", Meta = (AutoCreateRefTerm = "NewMovementSet"))
	void SetMovementSet(UPARAM(meta=(Categories="GMS.MovementSet"))
		const FGameplayTag& NewMovementSet);

	/**
	 * Set a new movement definition, refreshing the movement set.
	 * 设置新的运动定义，刷新运动集。
	 * @param NewDefinition The new movement definition. 新运动定义。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void SetMovementDefinition(TSoftObjectPtr<UGMS_MovementDefinition> NewDefinition);

	/**
	 * Set a new movement definition, refreshing the movement set.
	 * 设置新的运动定义，刷新运动集。
	 * @details This allowed locally quick switch movement set without networking involved. 此函数允许快速在本地切换运动集，而无需涉及网络。
	 * @param NewDefinition The new movement definition. 新运动定义。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void LocalSetMovementDefinition(TSoftObjectPtr<UGMS_MovementDefinition> NewDefinition);

	/**
	 * Pushes a new movement definition, refreshing the movement set.
	 * 推送新的运动定义，刷新运动集。
	 * @param NewDefinition The new movement definition. 新运动定义。
	 * @param bPopCurrent Whether to pop the current definition. 是否弹出当前定义。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", meta=(DeprecatedFunction, DeprecationMessage="Use SetMovementDefinition instead."))
	void PushAvailableMovementDefinition(TSoftObjectPtr<UGMS_MovementDefinition> NewDefinition, bool bPopCurrent = true);

	/**
	 * Removes the last movement definition, refreshing the movement set.
	 * 移除最后一个运动定义，刷新运动集。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", meta=(DeprecatedFunction, DeprecationMessage="No longer needed!"))
	void PopAvailableMovementDefinition();

private:
	void InternalSetMovementDefinition(const TSoftObjectPtr<UGMS_MovementDefinition> NewDefinition, bool bSendRpc = true);

	/**
	 * Client RPC to set a movement definition.
	 * 客户端RPC设置运动定义。
	 * @param NewDefinition The new movement definition. 新运动定义。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetMovementDefinition(const TSoftObjectPtr<UGMS_MovementDefinition>& NewDefinition);
	void ClientSetMovementDefinition_Implementation(const TSoftObjectPtr<UGMS_MovementDefinition>& NewDefinition);

	/**
	 * Server RPC to set a movement definition.
	 * 服务器RPC设置运动定义。
	 * @param NewDefinition The new movement definition. 新运动定义。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetMovementDefinition(const TSoftObjectPtr<UGMS_MovementDefinition>& NewDefinition);
	virtual void ServerSetMovementDefinition_Implementation(const TSoftObjectPtr<UGMS_MovementDefinition>& NewDefinition);

	/**
	 * Sets the movement set with optional RPC.
	 * 设置运动集，可选择是否发送RPC。
	 * @param NewMovementSet The new movement set. 新运动集。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void SetMovementSet(const FGameplayTag& NewMovementSet, bool bSendRpc);

	/**
	 * Client RPC to set the movement set.
	 * 客户端RPC设置运动集。
	 * @param NewMovementSet The new movement set. 新运动集。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetMovementSet(const FGameplayTag& NewMovementSet);

	/**
	 * Server RPC to set the movement set.
	 * 服务器RPC设置运动集。
	 * @param NewMovementSet The new movement set. 新运动集。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetMovementSet(const FGameplayTag& NewMovementSet);
	virtual void ServerSetMovementSet_Implementation(const FGameplayTag& NewMovementSet);

protected:
	/**
	 * Called when movement definition are replicated.
	 * 运动定义复制时调用。
	 */
	UFUNCTION()
	virtual void OnReplicated_MovementDefinition();

	/**
	 * Called when the movement set is replicated.
	 * 运动集复制时调用。
	 * @param PreviousMovementSet The previous movement set. 之前的运动集。
	 */
	UFUNCTION()
	void OnReplicated_MovementSet(const FGameplayTag& PreviousMovementSet);

	/**
	 * Updates the current movement set setting.
	 * 更新当前运动集设置。
	 */
	virtual void RefreshMovementSetSetting();

	/**
	 * Updates the current control setting.
	 * 更新当前控制设置。
	 */
	virtual void RefreshControlSetting();

	/**
	 * Updates the current movement state setting.
	 * 更新当前运动状态设置。
	 */
	virtual void RefreshMovementStateSetting();

	/**
	 * Applies the current movement settings.
	 * 应用当前运动设置。
	 */
	virtual void ApplyMovementSetting();

	/**
	 * Called when the movement set changes.
	 * 运动集更改时调用。
	 * @param PreviousMovementSet The previous movement set. 之前的运动集。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	void OnMovementSetChanged(const FGameplayTag& PreviousMovementSet);
	virtual void OnMovementSetChanged_Implementation(const FGameplayTag& PreviousMovementSet);

#pragma endregion

#pragma region MovementState

public:
	/**
	 * Gets the desired movement state.
	 * 获取期望的运动状态。
	 * @return The desired movement state. 期望的运动状态。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual const FGameplayTag& GetDesiredMovementState() const;

	/**
	 * Sets the desired movement state.
	 * 设置期望的运动状态。
	 * @param NewDesiredMovement The new desired movement state. 新的期望运动状态。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", Meta = (DisplayName="Set Desired Movement State", AutoCreateRefTerm = "NewDesiredMovement"))
	virtual void SetDesiredMovement(UPARAM(meta=(Categories="GMS.MovementState"))
		const FGameplayTag& NewDesiredMovement);

	/**
	 * Cycles through desired movement states.
	 * 循环切换期望的运动状态。
	 * @param bForward Whether to cycle forward. 是否向前循环。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	virtual void CycleDesiredMovementState(bool bForward = true);

	/**
	 * Gets the current movement state.
	 * 获取当前的运动状态。
	 * @return The current movement state. 当前的运动状态。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual const FGameplayTag& GetMovementState() const;

	/**
	 * Gets the speed level.
	 * 获取速度级别。
	 * @return The speed level. 速度级别。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	int32 GetSpeedLevel() const;

	virtual float GetMappedMovementSpeedLevel(float Speed) const;

protected:
	/**
	 * Called when the movement state changes.
	 * 运动状态更改时调用。
	 * @param PreviousMovementState The previous movement state. 之前的运动状态。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	void OnMovementStateChanged(const FGameplayTag& PreviousMovementState);
	virtual void OnMovementStateChanged_Implementation(const FGameplayTag& PreviousMovementState);

#pragma endregion

#pragma region Input

public:
	/**
	 * Gets the character movement intent.
	 * 获取角色移动意图。
	 * @return The movement intent vector. 移动意图向量。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual FVector GetMovementIntent() const;

	/**
	 * Applies turn input at a specified rate.
	 * 以指定速率应用转向输入。
	 * @param Direction The turn direction. 转向方向。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	void TurnAtRate(float Direction);

protected:
	/**
	 * Refreshes input handling.
	 * 刷新输入处理。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshInput(float DeltaTime);
#pragma endregion

#pragma region ViewSystem

public:
	/**
	 * Gets the view state.
	 * 获取视图状态。
	 * @return The view state. 视图状态。
	 */
	const FGMS_ViewState& GetViewState() const;

protected:
	/**
	 * Sets the replicated view rotation.
	 * 设置复制的视图旋转。
	 * @param NewViewRotation The new view rotation. 新视图旋转。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	virtual void SetReplicatedViewRotation(const FRotator& NewViewRotation, bool bSendRpc);

	/**
	 * Server RPC to set the replicated view rotation.
	 * 服务器RPC设置复制的视图旋转。
	 * @param NewViewRotation The new view rotation. 新视图旋转。
	 */
	UFUNCTION(Server, Unreliable)
	virtual void ServerSetReplicatedViewRotation(const FRotator& NewViewRotation);
	virtual void ServerSetReplicatedViewRotation_Implementation(const FRotator& NewViewRotation);

	/**
	 * Called when the view rotation is replicated.
	 * 视图旋转复制时调用。
	 */
	UFUNCTION()
	virtual void OnReplicated_ReplicatedViewRotation();

#pragma endregion

#pragma region Rotation Mode

	/**
		 * Gets the desired rotation mode.
		 * 获取期望的旋转模式。
		 * @return The desired rotation mode. 期望的旋转模式。
		 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual const FGameplayTag& GetDesiredRotationMode() const;

	/**
	 * Sets the desired rotation mode.
	 * 设置期望的旋转模式。
	 * @param NewDesiredRotationMode The new desired rotation mode. 新的期望旋转模式。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem", Meta = (AutoCreateRefTerm = "NewDesiredRotationMode"))
	virtual void SetDesiredRotationMode(UPARAM(meta=(Categories="GMS.RotationMode"))
		const FGameplayTag& NewDesiredRotationMode);

	/**
	 * Gets the current rotation mode.
	 * 获取当前的旋转模式。
	 * @return The current rotation mode. 当前的旋转模式。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	virtual const FGameplayTag& GetRotationMode() const;

	/**
		 * Called when the rotation mode changes.
		 * 旋转模式更改时调用。
		 * @param PreviousRotationMode The previous rotation mode. 之前的旋转模式。
		 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	void OnRotationModeChanged(const FGameplayTag& PreviousRotationMode);
	virtual void OnRotationModeChanged_Implementation(const FGameplayTag& PreviousRotationMode);

#pragma endregion

#pragma region OverlayMode

public:
	/**
	 * Gets the current overlay mode.
	 * 获取当前的覆盖模式。
	 * @return The current overlay mode. 当前的覆盖模式。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|MovementSystem")
	const FGameplayTag& GetOverlayMode() const;

	/**
	 * Sets the overlay mode.
	 * 设置覆盖模式。
	 * @param NewOverlayMode The new overlay mode. 新覆盖模式。
	 */
	UFUNCTION(BlueprintCallable, Category = "GMS|MovementSystem", Meta = (AutoCreateRefTerm = "NewOverlayMode", Categories="GMS.OverlayMode"))
	void SetOverlayMode(const FGameplayTag& NewOverlayMode);

private:
	/**
	 * Sets the overlay mode with optional RPC.
	 * 设置覆盖模式，可选择是否发送RPC。
	 * @param NewOverlayMode The new overlay mode. 新覆盖模式。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void SetOverlayMode(const FGameplayTag& NewOverlayMode, bool bSendRpc);

	/**
	 * Client RPC to set the overlay mode.
	 * 客户端RPC设置覆盖模式。
	 * @param NewOverlayMode The new overlay mode. 新覆盖模式。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetOverlayMode(const FGameplayTag& NewOverlayMode);

	/**
	 * Server RPC to set the overlay mode.
	 * 服务器RPC设置覆盖模式。
	 * @param NewOverlayMode The new overlay mode. 新覆盖模式。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetOverlayMode(const FGameplayTag& NewOverlayMode);

	/**
	 * Called when the overlay mode is replicated.
	 * 覆盖模式复制时调用。
	 * @param PreviousOverlayMode The previous overlay mode. 之前的覆盖模式。
	 */
	UFUNCTION()
	void OnReplicated_OverlayMode(const FGameplayTag& PreviousOverlayMode);

protected:
	/**
	 * Called when the overlay mode changes.
	 * 覆盖模式更改时调用。
	 * @param PreviousOverlayMode The previous overlay mode. 之前的覆盖模式。
	 */
	UFUNCTION(BlueprintNativeEvent, Category = "GMS|MovementSystem")
	void OnOverlayModeChanged(const FGameplayTag& PreviousOverlayMode);
#pragma endregion

#pragma region DistanceMatching

public:
	/**
	 * Gets parameters for predicting ground movement stop location.
	 * 获取预测地面运动停止位置的参数。
	 * @return The stop location parameters. 停止位置参数。
	 */
	virtual FGMS_PredictGroundMovementStopLocationParams GetPredictGroundMovementStopLocationParams() const
	{
		return FGMS_PredictGroundMovementStopLocationParams();
	};

	/**
	 * Gets parameters for predicting ground movement pivot location.
	 * 获取预测地面运动枢轴位置的参数。
	 * @return The pivot location parameters. 枢轴位置参数。
	 */
	virtual FGMS_PredictGroundMovementPivotLocationParams GetPredictGroundMovementPivotLocationParams() const
	{
		return FGMS_PredictGroundMovementPivotLocationParams();
	};
#pragma endregion

#pragma region Properties

	/**
	 * Event for locomotion mode changes.
	 * 运动模式更改事件。
	 */
	UPROPERTY(BlueprintAssignable, Category="Event")
	FLocomotionModeChangedSignature OnLocomotionModeChangedEvent;

	/**
	 * Event for movement set changes.
	 * 运动集更改事件。
	 */
	UPROPERTY(BlueprintAssignable, Category="Event")
	FMovementSetChangedSignature OnMovementSetChangedEvent;

	/**
	 * Event for rotation mode changes.
	 * 旋转模式更改事件。
	 */
	UPROPERTY(BlueprintAssignable, Category="Event")
	FRotationModeChangedSignature OnRotationModeChangedEvent;

	/**
	 * Event for movement state changes.
	 * 运动状态更改事件。
	 */
	UPROPERTY(BlueprintAssignable, Category="Event")
	FMovementChangedSignature OnMovementStateChangedEvent;

	/**
	 * Event for overlay mode changes.
	 * 覆盖模式更改事件。
	 */
	UPROPERTY(BlueprintAssignable, Category="Event")
	FOverlayModeChangedSignature OnOverlayModeChangedEvent;

protected:
#if WITH_EDITORONLY_DATA
	/**
	 * Available movement definitions for the component.
	 * 组件可用的运动定义。
	 * @note Lower definitions have higher priority. 较低的定义具有较高优先级。
	 * @details Queries matching MovementSetSetting from bottom to top when MovementSet changes. 当运动集更改时，从下到上查询匹配的运动集设置。
	 * @attention Used to dynamically add/remove movement sets at runtime (e.g., equipping a Greatsword). 用于在运行时动态添加/移除运动集（例如装备大剑）。
	 */
	UE_DEPRECATED(1.5, "deprecated and will be removed in 1.6")
	UPROPERTY(EditAnywhere, Category="Advanced", meta=(EditCondition=false, DeprecatedProperty, DeprecationMessage="Deprecated in faver of SetMovementDefinition."))
	TArray<TSoftObjectPtr<const UGMS_MovementDefinition>> MovementDefinitions;
#endif
	/** 
	 * Current selected movement definition.
	 * 当前选择的运动定义。
	 */
	UPROPERTY(EditAnywhere, Category="Settings|Definitions", ReplicatedUsing=OnReplicated_MovementDefinition)
	TSoftObjectPtr<const UGMS_MovementDefinition> MovementDefinition{nullptr};

	UPROPERTY(VisibleInstanceOnly, Category="Settings|Definitions")
	TSoftObjectPtr<const UGMS_MovementDefinition> PrevMovementDefinition{nullptr};

	/**
	 * Current selected movement set setting.
	 * 当前选择的运动集设置。
	 */
	UPROPERTY(VisibleInstanceOnly, Category="Settings|Definitions")
	FGMS_MovementSetSetting MovementSetSetting;

	/**
	 * Current selected control setting.
	 * 当前选择的控制设置。
	 */
	UPROPERTY(VisibleInstanceOnly, Category="Settings|Definitions")
	TObjectPtr<const UGMS_MovementControlSetting_Default> ControlSetting;

	/**
	 * Current selected movement state setting.
	 * 当前选择的运动状态设置。
	 */
	UPROPERTY(VisibleInstanceOnly, Category="Settings|Definitions")
	FGMS_MovementStateSetting MovementStateSetting;

	/**
	 * Current movement set.
	 * 当前的运动集。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="Settings", ReplicatedUsing = "OnReplicated_MovementSet", meta=(Categories="GMS.MovementSet"))
	FGameplayTag MovementSet{FGameplayTag::EmptyTag};

	/**
	 * Will check and adjust the desired rotation mode based on whether the current movement state settings allows it.
	 * 若勾选，当运动状态/旋转模式变更时，会先检查当前运动状态设置是否允许“DesiredRotationMode”，并进行调整。
	 * @details Uncheck if you want decouple movement state from rotation mode(for example:sprinting in view direction)
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings")
	bool bRespectAllowedRotationModesSettings{true};

	/**
	 * Current gameplay tags owned by the component.
	 * 组件拥有的当前游戏标签。
	 * @note GameplayTagsProvider is preferred. 更推荐使用GameplayTagsProvider。
	 */
	UPROPERTY(EditAnywhere, Replicated, Category="Settings|GameplayTags")
	FGameplayTagContainer OwnedTags;

	/**
	 * Optional object providing gameplay tags.
	 * 提供游戏标签的可选对象。
	 * @note Can integrate with Gameplay Ability System (GAS) by setting an Ability System Component as the provider. 可通过将能力系统组件设置为提供者与游戏能力系统（GAS）集成。
	 */
	UPROPERTY(VisibleAnywhere, Category="Settings|GameplayTags")
	TObjectPtr<UObject> GameplayTagsProvider{nullptr};

	/**
	 * Tags that block grounded rotation.
	 * 阻止地面旋转的标签。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|GameplayTags")
	FGameplayTagContainer GroundedRotationBlockingTags;

	/**
	 * Tags that block in-air rotation.
	 * 阻止空中旋转的标签。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|GameplayTags")
	FGameplayTagContainer InAirRotationBlockingTags;

	/**
	 * Current locomotion mode.
	 * 当前的运动模式。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", ReplicatedUsing = "OnReplicated_LocomotionMode", meta=(Categories="GMS.LocomotionMode"))
	FGameplayTag LocomotionMode{GMS_MovementModeTags::Grounded};

	/**
	 * Current overlay mode.
	 * 当前的覆盖模式。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "State", ReplicatedUsing = "OnReplicated_OverlayMode")
	FGameplayTag OverlayMode{GMS_OverlayModeTags::Default};

public:
	/**
	 * Animation graph settings for different skeletons or layers.
	 * 用于不同骨架或层的动画图设置。
	 * @note Useful for projects with multiple skeletons or custom animation layers without runtime retargeting. 适用于具有多个骨架或不需要运行时重定向的自定义动画层的项目。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="Settings|Animation")
	TObjectPtr<UGMS_AnimGraphSetting> AnimGraphSetting{nullptr};

protected:
	/**
	 * Desired velocity yaw angle, clamped between -180 and 180 degrees.
	 * 期望的速度偏航角，限制在-180到180度之间。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", Transient, Replicated, Meta = (ClampMin = -180, ClampMax = 180, ForceUnits = "deg"))
	float DesiredVelocityYawAngle{0.0f};

	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "State", Transient)
	FGMS_MovementBaseState MovementBase;
	/**
	 * Replicated raw view rotation, in world or movement base space.
	 * 复制的原始视图旋转，在世界或运动基础空间中。
	 * @note Use FGMS_ViewState::Rotation for network smoothing. 使用FGMS_ViewState::Rotation进行网络平滑。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", Transient, ReplicatedUsing = "OnReplicated_ReplicatedViewRotation")
	FRotator ReplicatedViewRotation{ForceInit};

	/**
	 * Current locomotion state.
	 * 当前的运动状态。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State", Transient)
	FGMS_LocomotionState LocomotionState;

	/**
	 * Current view state.
	 * 当前的视图状态。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", Transient)
	FGMS_ViewState ViewState;

	/**
	 * Main animation instance (weak reference).
	 * 主动画实例（弱引用）。
	 */
	UPROPERTY(VisibleInstanceOnly, Category="State", Transient, meta=(ShowInnerProperties))
	TWeakObjectPtr<UAnimInstance> MainAnimInstance{nullptr};

	/**
	 * Animation instance.
	 * 动画实例。
	 */
	UPROPERTY()
	TObjectPtr<UAnimInstance> AnimationInstance{nullptr};

	/**
	 * Owning pawn.
	 * 拥有该组件的Pawn。
	 */
	UPROPERTY(Transient)
	TObjectPtr<APawn> OwnerPawn{nullptr};

#pragma endregion

#if WITH_EDITOR
	/**
	 * Validates data in the editor.
	 * 在编辑器中验证数据。
	 * @param Context The validation context. 验证上下文。
	 * @return The validation result. 验证结果。
	 */
	virtual EDataValidationResult IsDataValid(class FDataValidationContext& Context) const override;
#endif
};