第一次提交

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/Locomotions/GMS_LocomotionStructLibrary.h
+++ b/Plugins/GMS/Source/GenericMovementSystem/Public/Locomotions/GMS_LocomotionStructLibrary.h
@@ -0,0 +1,601 @@
+// 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;
+};