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

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

#pragma once

#include "CoreMinimal.h"
#include "GMS_MovementSystemComponent.h"
#include "MoverSimulationTypes.h"
#include "GMS_MoverMovementSystemComponent.generated.h"

class UMoverTrajectoryPredictor;
class UNavMoverComponent;
class UGMS_InputProducer;

/**
 * Movement system component for mover-based movement (work in progress).
 * 基于Mover的运动系统组件（开发中）。
 * @note Not recommended for use until production ready. 在标记为生产就绪之前不建议使用。
 */
UCLASS(ClassGroup=GMS, BlueprintType, Blueprintable, meta=(BlueprintSpawnableComponent), DisplayName="GMS Movement System Component(Mover)")
class GENERICMOVEMENTSYSTEM_API UGMS_MoverMovementSystemComponent : public UGMS_MovementSystemComponent, public IMoverInputProducerInterface
{
	GENERATED_BODY()

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

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

	/**
	 * Produces input for the mover simulation.
	 * 为Mover模拟生成输入。
	 * @param SimTimeMs Simulation time in milliseconds. 模拟时间（毫秒）。
	 * @param InputCmdResult The input command context (output). 输入命令上下文（输出）。
	 */
	virtual void ProduceInput_Implementation(int32 SimTimeMs, FMoverInputCmdContext& InputCmdResult) override;

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

	/**
	 * Called before the mover simulation tick.
	 * Mover模拟tick前调用。
	 * @param TimeStep The mover time step. Mover时间步。
	 * @param InputCmd The input command context. 输入命令上下文。
	 */
	UFUNCTION()
	virtual void OnMoverPreSimulationTick(const FMoverTimeStep& TimeStep, const FMoverInputCmdContext& InputCmd);

protected:
	/**
	 * The mover component.
	 * Mover组件。
	 */
	UPROPERTY()
	TObjectPtr<UMoverComponent> MoverComponent{nullptr};


	UPROPERTY()
	TObjectPtr<UMoverTrajectoryPredictor> TrajectoryPredictor{nullptr};

	/**
	 * The skeletal mesh component.
	 * 骨骼网格组件。
	 */
	UPROPERTY()
	TObjectPtr<USkeletalMeshComponent> MeshComponent{nullptr};

	/**
	 * Handles navigation movement data and functions.
	 * 处理导航运动数据和函数。
	 */
	UPROPERTY()
	TObjectPtr<UNavMoverComponent> NavMoverComponent{nullptr};

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

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

	/**
	 * Handle for the movement state modifier (e.g., crouching).
	 * 运动状态修饰符的句柄（例如蹲伏）。
	 */
	FMovementModifierHandle MovementStateModiferHandle;

	/**
	 * Called when the mover movement mode changes.
	 * Mover运动模式更改时调用。
	 * @param PreviousMovementModeName The previous movement mode name. 之前的运动模式名称。
	 * @param NewMovementModeName The new movement mode name. 新运动模式名称。
	 */
	UFUNCTION()
	virtual void OnMoverMovementModeChanged(const FName& PreviousMovementModeName, const FName& NewMovementModeName);

	/**
	 * Applies movement settings.
	 * 应用运动设置。
	 */
	virtual void ApplyMovementSetting() override;

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

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

#pragma region Locomotion

public:
	virtual TScriptInterface<IPoseSearchTrajectoryPredictorInterface> GetTrajectoryPredictor() const override;
	/**
	 * 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;

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

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

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

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

#pragma region Rotation System

public:
	/**
	 * Refreshes the target yaw angle using locomotion rotation.
	 * 使用运动旋转刷新目标偏航角。
	 */
	void RefreshTargetYawAngleUsingActorRotation();

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

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

#pragma region DistanceMatching
	/**
	 * 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

#pragma region MovementState

	virtual void RefreshMovementBase() override;

	/**
	 * 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:
	/**
	 * Applies the movement state and related settings.
	 * 应用运动状态及相关设置。
	 * @param NewMovementState The new movement state. 新运动状态。
	 */
	virtual void ApplyMovementState(const FGameplayTag& NewMovementState);
#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:
	/**
	 * Applies the rotation mode and related settings.
	 * 应用旋转模式及相关设置。
	 * @param NewRotationMode The new rotation mode. 新旋转模式。
	 */
	virtual void ApplyRotationMode(const FGameplayTag& NewRotationMode);
#pragma endregion

#pragma region Input
	/**
	 * Requests movement with an intended directional magnitude.
	 * 请求以指定方向强度移动。
	 * @param DesiredIntent The desired movement intent. 期望的移动意图。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	virtual void RequestMoveByIntent(const FVector& DesiredIntent) { CachedMoveInputIntent = DesiredIntent; }

	/**
	 * Requests movement with a desired velocity.
	 * 请求以指定速度移动。
	 * @param DesiredVelocity The desired velocity. 期望的速度。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	virtual void RequestMoveByVelocity(const FVector& DesiredVelocity) { CachedMoveInputVelocity = DesiredVelocity; }

	/**
	 * Clears movement requests.
	 * 清除移动请求。
	 */
	UFUNCTION(BlueprintCallable, Category="GMS|MovementSystem")
	virtual void ClearMoveRequest()
	{
		CachedMoveInputIntent = FVector::ZeroVector;
		CachedMoveInputVelocity = FVector::ZeroVector;
	}

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

	/**
	 * Produces input for the simulation frame.
	 * 为模拟帧生成输入。
	 * @param DeltaMs Time delta in milliseconds. 时间增量（毫秒）。
	 * @param InputCmd The input command context. 输入命令上下文。
	 * @return The produced input command context. 生成的输入命令上下文。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|MovementSystem")
	FMoverInputCmdContext OnProduceInput(float DeltaMs, FMoverInputCmdContext InputCmd);

	/**
	 * Adjusts orientation intent based on context.
	 * 根据上下文调整方向意图。
	 * @param DeltaSeconds Time since last frame. 上一帧以来的时间。
	 * @param OrientationIntent The orientation intent. 方向意图。
	 * @return The adjusted orientation intent. 调整后的方向意图。
	 */
	virtual FVector AdjustOrientationIntent(float DeltaSeconds, const FVector& OrientationIntent) const;

	/**
	 * Whether to use base-relative movement.
	 * 是否使用基于基础的移动。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Settings|Input")
	bool bUseBaseRelativeMovement = true;

	/**
	 * Whether to maintain the last input orientation after input ceases.
	 * 输入停止后是否保持最后输入方向。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Settings|Input")
	bool bMaintainLastInputOrientation = false;

	/**
	 * Last non-zero movement input.
	 * 最后非零移动输入。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	FVector LastAffirmativeMoveInput = FVector::ZeroVector;

	/**
	 * If true, the actor will remain vertical despite any rotation applied to the actor
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=MoverExamples)
	bool bShouldRemainVertical = true;

	/**
	 * Cached movement input intent.
	 * 缓存的移动输入意图。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="State|Input")
	FVector CachedMoveInputIntent = FVector::ZeroVector;

	/**
	 * Cached movement input velocity.
	 * 缓存的移动输入速度。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="State|Input")
	FVector CachedMoveInputVelocity = FVector::ZeroVector;

	/**
	 * Cached turn input.
	 * 缓存的转向输入。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	FRotator CachedTurnInput = FRotator::ZeroRotator;

	/**
	 * Cached look input.
	 * 缓存的观察输入。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	FRotator CachedLookInput = FRotator::ZeroRotator;

	/**
	 * Current desired movement state.
	 * 当前期望的运动状态。
	 */
	UPROPERTY(EditAnywhere, Category="State|Input", meta=(Categories="GMS.MovementState"))
	FGameplayTag DesiredMovementState{GMS_MovementStateTags::Jog};

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

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

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

public:
	/**
	 * Whether the jump input was just pressed.
	 * 跳跃输入是否刚被按下。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	bool bIsJumpJustPressed = false;

	/**
	 * Whether the jump input is held.
	 * 跳跃输入是否被持续按住。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	bool bIsJumpPressed = false;

	/**
	 * Input tags for the component.
	 * 组件的输入标签。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Transient, Category="State|Input")
	FGameplayTagContainer InputTags;

	/**
	 * Whether flying is active.
	 * 飞行是否激活。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	bool bIsFlyingActive = false;

	/**
	 * Whether to toggle flying.
	 * 是否切换飞行状态。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State|Input")
	bool bShouldToggleFlying = false;

private:
	/**
	 * Flag indicating if input is produced in Blueprint.
	 * 指示是否在蓝图中生成输入的标志。
	 */
	uint8 bHasProduceInputInBpFunc : 1;
#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
};