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

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

#pragma once

#include "GMS_MovementSystemComponent.h"
#include "GameFramework/Character.h"
#include "GMS_CharacterMovementSystemComponent.generated.h"

class UGMS_CharacterMovementSetting_Default;
class UGMS_CharacterRotationSetting_Default;

/**
 * Movement system component for characters.
 * 角色的运动系统组件。
 */
UCLASS(ClassGroup=GMS, BlueprintType, Blueprintable, meta=(BlueprintSpawnableComponent), DisplayName="GMS Movement System Component(Character)")
class GENERICMOVEMENTSYSTEM_API UGMS_CharacterMovementSystemComponent : public UGMS_MovementSystemComponent
{
	GENERATED_BODY()

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

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

	/**
	 * Gets the character movement component.
	 * 获取角色运动组件。
	 * @return The character movement component. 角色运动组件。
	 */
	UCharacterMovementComponent* GetCharacterMovement() const { return CharacterMovement; };

protected:
	/**
	 * The character movement component.
	 * 角色运动组件。
	 */
	UPROPERTY()
	TObjectPtr<UCharacterMovementComponent> CharacterMovement;

	/**
	 * The owning character.
	 * 拥有该组件的角色。
	 */
	UPROPERTY()
	TObjectPtr<ACharacter> OwnerCharacter{nullptr};

	/**
	 * Maps movement modes to gameplay tags.
	 * 将运动模式映射到游戏标签。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|GameplayTags", meta=(Categories="GMS.LocomotionMode"))
	TMap<TEnumAsByte<EMovementMode>, FGameplayTag> MovementModeToTagMapping;

	/**
	 * Maps custom movement modes to gameplay tags.
	 * 将自定义运动模式映射到游戏标签。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|GameplayTags", meta=(Categories="GMS.LocomotionMode"))
	TMap<uint8, FGameplayTag> CustomMovementModeToTagMapping;

	/**
	 * Whether to apply movement settings to the character movement component.
	 * 是否将运动设置应用于角色运动组件。
	 * @note Can be disabled for external control (e.g., AI). 可禁用以进行外部控制（例如AI）。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|DynamicMovementState")
	bool bAllowRefreshCharacterMovementSettings{true};

	/**
	 * Curve mapping ground speed to movement state index (e.g., walk, jog, sprint).
	 * 将地面速度映射到运动状态索引的曲线（例如走、慢跑、冲刺）。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings|DynamicMovementState", meta=(EditCondition="!bAllowRefreshCharacterMovementSettings"))
	TObjectPtr<UCurveFloat> SpeedToMovementStateCurve;

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

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

	/**
	 * Called when the game ends.
	 * 游戏结束时调用。
	 * @param EndPlayReason The reason for ending. 结束原因。
	 */
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;

public:
	/**
	 * Called every frame.
	 * 每帧调用。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @param TickType The type of tick. tick类型。
	 * @param ThisTickFunction The tick function. tick函数。
	 */
	virtual void TickComponent(float DeltaTime, ELevelTick TickType, FActorComponentTickFunction* ThisTickFunction) override;

protected:
	/**
	 * Called when the character's movement mode changes.
	 * 角色运动模式更改时调用。
	 * @param InCharacter The character. 角色。
	 * @param PrevMovementMode The previous movement mode. 之前的运动模式。
	 * @param PreviousCustomMode The previous custom mode. 之前的自定义模式。
	 */
	UFUNCTION()
	virtual void OnCharacterMovementModeChanged(ACharacter* InCharacter, EMovementMode PrevMovementMode, uint8 PreviousCustomMode = 0);

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

	/**
	 * Calculates the actual movement state.
	 * 计算实际的运动状态。
	 * @return The actual movement state. 实际的运动状态。
	 */
	virtual FGameplayTag CalculateActualMovementState();

	/**
	 * Applies the desired movement state settings to the character movement component.
	 * 将期望的运动状态设置应用于角色运动组件。
	 */
	virtual void ApplyMovementSetting() override;

	/**
	 * Called when the rotation mode changes.
	 * 旋转模式更改时调用。
	 * @param PreviousRotationMode The previous rotation mode. 之前的旋转模式。
	 */
	virtual void OnRotationModeChanged_Implementation(const FGameplayTag& PreviousRotationMode) override;

	virtual void RefreshMovementBase() override;

#pragma region MovementState

public:
	/**
	 * Gets the desired movement state.
	 * 获取期望的运动状态。
	 * @return The desired movement state. 期望的运动状态。
	 */
	virtual const FGameplayTag& GetDesiredMovementState() const override;

	/**
	 * Sets the desired movement state.
	 * 设置期望的运动状态。
	 * @param NewDesiredMovement The new desired movement state. 新的期望运动状态。
	 */
	virtual void SetDesiredMovement(const FGameplayTag& NewDesiredMovement) override;

	/**
	 * Gets the current movement state.
	 * 获取当前的运动状态。
	 * @return The current movement state. 当前的运动状态。
	 */
	virtual const FGameplayTag& GetMovementState() const override;

protected:
	/**
	 * Sets the movement state.
	 * 设置运动状态。
	 * @param NewMovementState The new movement state. 新运动状态。
	 */
	virtual void SetMovementState(const FGameplayTag& NewMovementState);

	/**
	 * Refreshes the movement state.
	 * 刷新运动状态。
	 */
	virtual void RefreshMovementState();

private:
	/**
	 * Sets the desired movement state with optional RPC.
	 * 设置期望的运动状态，可选择是否发送RPC。
	 * @param NewDesiredMovement The new desired movement state. 新的期望运动状态。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void SetDesiredMovement(const FGameplayTag& NewDesiredMovement, bool bSendRpc);

	/**
	 * Client RPC to set the desired movement state.
	 * 客户端RPC设置期望的运动状态。
	 * @param NewDesiredMovement The new desired movement state. 新的期望运动状态。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetDesiredMovement(const FGameplayTag& NewDesiredMovement);
	virtual void ClientSetDesiredMovement_Implementation(const FGameplayTag& NewDesiredMovement);

	/**
	 * Server RPC to set the desired movement state.
	 * 服务器RPC设置期望的运动状态。
	 * @param NewDesiredMovement The new desired movement state. 新的期望运动状态。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetDesiredMovement(const FGameplayTag& NewDesiredMovement);
	virtual void ServerSetDesiredMovement_Implementation(const FGameplayTag& NewDesiredMovement);
#pragma endregion

#pragma region RotationMode

public:
	/**
	 * Gets the desired rotation mode.
	 * 获取期望的旋转模式。
	 * @return The desired rotation mode. 期望的旋转模式。
	 */
	virtual const FGameplayTag& GetDesiredRotationMode() const override;

	/**
	 * Sets the desired rotation mode.
	 * 设置期望的旋转模式。
	 * @param NewDesiredRotationMode The new desired rotation mode. 新的期望旋转模式。
	 */
	virtual void SetDesiredRotationMode(const FGameplayTag& NewDesiredRotationMode) override;

	/**
	 * Gets the current rotation mode.
	 * 获取当前的旋转模式。
	 * @return The current rotation mode. 当前的旋转模式。
	 */
	virtual const FGameplayTag& GetRotationMode() const override;

protected:
	/**
	 * Sets the rotation mode.
	 * 设置旋转模式。
	 * @param NewRotationMode The new rotation mode. 新旋转模式。
	 */
	virtual void SetRotationMode(const FGameplayTag& NewRotationMode);

	/**
	 * Refreshes the rotation mode.
	 * 刷新旋转模式。
	 */
	virtual void RefreshRotationMode();

private:
	/**
	 * Sets the desired rotation mode with optional RPC.
	 * 设置期望的旋转模式，可选择是否发送RPC。
	 * @param NewDesiredRotationMode The new desired rotation mode. 新的期望旋转模式。
	 * @param bSendRpc Whether to send RPC. 是否发送RPC。
	 */
	void SetDesiredRotationMode(const FGameplayTag& NewDesiredRotationMode, bool bSendRpc);

	/**
	 * Client RPC to set the desired rotation mode.
	 * 客户端RPC设置期望的旋转模式。
	 * @param NewDesiredRotationMode The new desired rotation mode. 新的期望旋转模式。
	 */
	UFUNCTION(Client, Reliable)
	void ClientSetDesiredRotationMode(const FGameplayTag& NewDesiredRotationMode);
	virtual void ClientSetDesiredRotationMode_Implementation(const FGameplayTag& NewDesiredRotationMode);

	/**
	 * Server RPC to set the desired rotation mode.
	 * 服务器RPC设置期望的旋转模式。
	 * @param NewDesiredRotationMode The new desired rotation mode. 新的期望旋转模式。
	 */
	UFUNCTION(Server, Reliable)
	void ServerSetDesiredRotationMode(const FGameplayTag& NewDesiredRotationMode);
	virtual void ServerSetDesiredRotationMode_Implementation(const FGameplayTag& NewDesiredRotationMode);
#pragma endregion

#pragma region Input

public:
	/**
	 * Gets the movement intent.
	 * 获取移动意图。
	 * @return The movement intent vector. 移动意图向量。
	 */
	virtual FVector GetMovementIntent() const override;

	/**
	 * Sets the movement intent.
	 * 设置移动意图。
	 * @param NewMovementIntent The new movement intent vector. 新移动意图向量。
	 */
	void SetMovementIntent(FVector NewMovementIntent);

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

	/**
	 * Replicated movement intent.
	 * 复制的移动意图。
	 */
	UPROPERTY(VisibleAnywhere, Category="State|Input", Transient, Replicated)
	FVector_NetQuantizeNormal MovementIntent;

	/**
	 * Desired movement state.
	 * 期望的运动状态。
	 */
	UPROPERTY(EditAnywhere, Category="Settings", Replicated, meta=(Categories="GMS.MovementState"))
	FGameplayTag DesiredMovementState{GMS_MovementStateTags::Jog};

	/**
	 * Desired rotation mode.
	 * 期望的旋转模式。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="Settings", Replicated, meta=(Categories="GMS.RotationMode"))
	FGameplayTag DesiredRotationMode{GMS_RotationModeTags::ViewDirection};

	/**
	 * Current movement state.
	 * 当前的运动状态。
	 */
	UPROPERTY(VisibleAnywhere, Category="State", Transient, meta=(Categories="GMS.MovementState"))
	FGameplayTag MovementState{GMS_MovementStateTags::Jog};

	/**
	 * Current rotation mode.
	 * 当前的旋转模式。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", Transient, meta=(Categories="GMS.RotationMode"))
	FGameplayTag RotationMode{GMS_RotationModeTags::ViewDirection};
#pragma endregion

#pragma region ViewSystem
	/**
	 * Refreshes the view system.
	 * 刷新视图系统。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshView(float DeltaTime);
#pragma endregion

#pragma region Abstraction

public:
	/**
	 * Checks if the character is crouching.
	 * 检查角色是否在蹲伏。
	 * @return True if crouching. 如果在蹲伏返回true。
	 */
	virtual bool IsCrouching() const override;

	/**
	 * Gets the maximum speed.
	 * 获取最大速度。
	 * @return The maximum speed. 最大速度。
	 */
	virtual float GetMaxSpeed() const override;

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

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

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

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

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

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

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

	virtual bool IsMovingOnGround() const override;

#pragma endregion

#pragma region Locomotion

protected:
	/**
	 * Early refresh for locomotion.
	 * 运动的早期刷新。
	 */
	virtual void RefreshLocomotionEarly();

	/**
	 * Refreshes locomotion state.
	 * 刷新运动状态。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshLocomotion(float DeltaTime);

	/**
	 * Late refresh for locomotion.
	 * 运动的后期刷新。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshLocomotionLate(float DeltaTime);

	/**
	 * Refreshes dynamic movement state.
	 * 刷新动态运动状态。
	 */
	virtual void RefreshDynamicMovementState();
#pragma endregion

#pragma region Rotation System

public:
	/**
	 * Sets rotation instantly.
	 * 立即设置旋转。
	 * @param TargetYawAngle The target yaw angle. 目标偏航角。
	 * @param Teleport The teleport type. 传送类型。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|MovementSystem")
	void SetRotationInstant(const float TargetYawAngle, const ETeleportType Teleport);

	/**
	 * Sets rotation smoothly.
	 * 平滑设置旋转。
	 * @param TargetYawAngle The target yaw angle. 目标偏航角。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @param InterpolationHalfLife The rotation interpolation speed. 旋转插值速度。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|MovementSystem")
	void SetRotationSmooth(float TargetYawAngle, float DeltaTime, float InterpolationHalfLife);

	/**
	 * Sets rotation with extra smoothness.
	 * 额外平滑设置旋转。
	 * @param TargetYawAngle The target yaw angle. 目标偏航角。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @param InterpolationHalfLife The rotation interpolation speed. 旋转插值速度。
	 * @param TargetYawAngleRotationSpeed The target yaw rotation speed. 目标偏航旋转速度。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|MovementSystem")
	void SetRotationExtraSmooth(float TargetYawAngle, float DeltaTime, float InterpolationHalfLife, float TargetYawAngleRotationSpeed);

protected:
	/**
	 * Refreshes the character's rotation.
	 * 刷新角色的旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	void RefreshRotation(float DeltaTime);
	virtual void RefreshRotation_Implementation(float DeltaTime);

	/**
	 * Refreshes grounded rotation.
	 * 刷新地面旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshGroundedRotation(float DeltaTime);

	/**
	 * Refreshes rotation when grounded and not moving.
	 * 地面上且不移动时刷新旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshGroundedNotMovingRotation(float DeltaTime);


	virtual float CalculateGroundedMovingRotationInterpolationSpeed(TObjectPtr<UCurveFloat> SpeedCurve, float Default = 12.0f) const;

	/**
	 * Refreshes rotation when grounded and moving.
	 * 地面上且移动时刷新旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshGroundedMovingRotation(float DeltaTime);

	/**
	 * Constrains aiming rotation.
	 * 约束瞄准旋转。
	 * @param ActorRotation The actor's rotation. Actor的旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @param bApplySecondaryConstraint Whether to apply secondary constraints. 是否应用次级约束。
	 * @return True if rotation was constrained. 如果旋转被约束返回true。
	 */
	virtual bool ConstrainAimingRotation(FRotator& ActorRotation, float DeltaTime, bool bApplySecondaryConstraint = false);

	/**
	 * Applies rotation yaw speed animation curve.
	 * 应用旋转偏航速度动画曲线。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @return True if the curve was applied. 如果应用了曲线返回true。
	 */
	bool ApplyRotationYawSpeedAnimationCurve(float DeltaTime);

	/**
	 * Custom rotation logic for grounded moving state.
	 * 地面移动状态的自定义旋转逻辑。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @return True if default rotation logic should be skipped. 如果应跳过默认旋转逻辑返回true。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	bool RefreshCustomGroundedMovingRotation(float DeltaTime);

	/**
	 * Custom rotation logic for grounded not moving state.
	 * 地面不移动状态的自定义旋转逻辑。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @return True if default rotation logic should be skipped. 如果应跳过默认旋转逻辑返回true。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	bool RefreshCustomGroundedNotMovingRotation(float DeltaTime);

	/**
	 * Refreshes in-air rotation.
	 * 刷新空中旋转。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 */
	virtual void RefreshInAirRotation(float DeltaTime);

	/**
	 * Refreshes the target yaw angle using actor's rotation.
	 * 使用Actor的旋转刷新目标偏航角。
	 */
	void RefreshTargetYawAngleUsingActorRotation();

	/**
	 * Sets the target yaw angle.
	 * 设置目标偏航角。
	 * @param TargetYawAngle The target yaw angle. 目标偏航角。
	 */
	void SetTargetYawAngle(float TargetYawAngle);

	/**
	 * Sets the target yaw angle smoothly.
	 * 平滑设置目标偏航角。
	 * @param TargetYawAngle The target yaw angle. 目标偏航角。
	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
	 * @param RotationSpeed The rotation speed. 旋转速度。
	 */
	void SetTargetYawAngleSmooth(float TargetYawAngle, float DeltaTime, float RotationSpeed);

	/**
		 * Refreshes the view-relative target yaw angle.
		 * 刷新相对于视图的目标偏航角。
		 */
	void RefreshViewRelativeTargetYawAngle();

	virtual void SetActorRotation(FRotator DesiredRotation);

#pragma endregion

#pragma region DistanceMatching

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

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