第一次提交

2026-03-03 01:23:02 +08:00
commit 3e434877e8
1053 changed files with 102411 additions and 0 deletions
--- a/Plugins/GMS/Source/GenericMovementSystem/Public/GMS_CharacterMovementSystemComponent.h
+++ b/Plugins/GMS/Source/GenericMovementSystem/Public/GMS_CharacterMovementSystemComponent.h
@@ -0,0 +1,616 @@
+// 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
+};