// Copyright 2025 https://yuewu.dev/en All Rights Reserved. #pragma once #include "GMS_LocomotionStructLibrary.h" #include "Engine/TimerHandle.h" #include "TimerManager.h" #include "Animation/AnimExecutionContext.h" #include "Animation/AnimInstance.h" #include "Animation/AnimNodeReference.h" #include "Engine/World.h" #include "Settings/GMS_SettingStructLibrary.h" #include "Locomotions/GMS_AnimState.h" #include "Utility/GMS_Tags.h" #include "GMS_MainAnimInstance.generated.h" class IPoseSearchTrajectoryPredictorInterface; class UGMS_AnimLayerSetting_Additive; class UGMS_AnimLayer; class UGMS_AnimLayerSetting; class UGMS_AnimLayerSetting_View; class UGMS_AnimLayerSetting_Overlay; class UGMS_AnimLayerSetting_States; class UGMS_MovementDefinition; class UGMS_MovementSystemComponent; /** * Base animation template for the main animation instance. * 主动画实例的动画模板基类。 */ UCLASS(BlueprintType) class GENERICMOVEMENTSYSTEM_API UGMS_MainAnimInstance : public UAnimInstance { GENERATED_BODY() public: /** * Gets the movement system component. * 获取运动系统组件。 * @return The movement system component. 运动系统组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) UGMS_MovementSystemComponent* GetMovementSystemComponent() const; /** * Constructor. * 构造函数。 */ UGMS_MainAnimInstance(); /** * Initializes the animation. * 初始化动画。 */ virtual void NativeInitializeAnimation() override; /** * Uninitializes the animation. * 取消初始化动画。 */ virtual void NativeUninitializeAnimation() override; /** * Called when the game starts. * 游戏开始时调用。 */ virtual void NativeBeginPlay() override; /** * Updates the animation. * 更新动画。 * @param DeltaTime Time since last update. 自上次更新以来的时间。 */ virtual void NativeUpdateAnimation(float DeltaTime) override; /** * Thread-safe animation update. * 线程安全的动画更新。 * @param DeltaTime Time since last update. 自上次更新以来的时间。 */ virtual void NativeThreadSafeUpdateAnimation(float DeltaTime) override; /** * Applies an animation layer setting to an animation layer instance. * 将动画层设置应用于动画层实例。 * @param LayerSetting The layer setting to apply. 要应用的层设置。 * @param LayerInstance The layer instance to apply the setting to. 要应用设置的层实例。 */ virtual void SetAnimLayerBySetting(const UGMS_AnimLayerSetting* LayerSetting, TObjectPtr& LayerInstance); /** * Registers animation state name to tag mappings for a given animation instance. * 为给定的动画实例注册动画状态名称到标签的映射。 * @param SourceAnimInstance The animation instance to register mappings for. 要注册映射的动画实例。 * @param Mapping The state name to tag mappings. 状态名称到标签的映射。 */ UFUNCTION(BlueprintCallable, Category="GMS|Animation") virtual void RegisterStateNameToTagMapping(UAnimInstance* SourceAnimInstance, TArray Mapping); /** * Unregisters animation state name to tag mappings for a given animation instance. * 为给定的动画实例取消注册动画状态名称到标签的映射。 * @param SourceAnimInstance The animation instance to unregister mappings for. 要取消注册映射的动画实例。 */ UFUNCTION(BlueprintCallable, Category="GMS|Animation") virtual void UnregisterStateNameToTagMapping(UAnimInstance* SourceAnimInstance); /** * Refreshes layer settings when core state changes (e.g., movement set, locomotion mode). * 当核心状态(如运动集、运动模式)更改时刷新层设置。 * @note Override if custom movement definitions include additional animation layer settings. 如果自定义运动定义包含额外的动画层设置,则需覆盖。 */ UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|Animation") void RefreshLayerSettings(); virtual void RefreshLayerSettings_Implementation(); /** * Sets the offset root bone rotation mode. * 设置偏移根骨骼旋转模式。 * @param NewRotationMode The new rotation mode. 新的旋转模式。 */ UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|Animation", meta=(BlueprintThreadSafe)) void SetOffsetRootBoneRotationMode(EOffsetRootBoneMode NewRotationMode); /** * Gets the current offset root bone rotation mode. * 获取当前偏移根骨骼旋转模式。 * @return The current rotation mode. 当前旋转模式。 */ UFUNCTION(BlueprintCallable, BlueprintPure, BlueprintNativeEvent, Category="GMS|Animation", meta=(BlueprintThreadSafe)) EOffsetRootBoneMode GetOffsetRootBoneRotationMode() const; /** * Gets the current offset root bone translation mode. * 获取当前偏移根骨骼平移模式。 * @return The current translation mode. 当前平移模式。 */ UFUNCTION(BlueprintCallable, BlueprintPure, BlueprintNativeEvent, Category="GMS|Animation", meta=(BlueprintThreadSafe)) EOffsetRootBoneMode GetOffsetRootBoneTranslationMode() const; /** * Sets the offset root bone translation mode. * 设置偏移根骨骼平移模式。 * @param NewTranslationMode The new translation mode. 新的平移模式。 */ UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|Animation", meta=(BlueprintThreadSafe)) void SetOffsetRootBoneTranslationMode(EOffsetRootBoneMode NewTranslationMode); protected: /** * Called when the locomotion mode changes. * 运动模式更改时调用。 * @param Prev The previous locomotion mode. 之前的运动模式。 */ UFUNCTION(BlueprintNativeEvent, Category="GMS|Animation") void OnLocomotionModeChanged(const FGameplayTag& Prev); /** * Called when the rotation mode changes. * 旋转模式更改时调用。 * @param Prev The previous rotation mode. 之前的旋转模式。 */ UFUNCTION(BlueprintNativeEvent, Category="GMS|Animation") void OnRotationModeChanged(const FGameplayTag& Prev); /** * Called when the movement set changes. * 运动集更改时调用。 * @param Prev The previous movement set. 之前的运动集。 */ UFUNCTION(BlueprintNativeEvent, Category="GMS|Animation") void OnMovementSetChanged(const FGameplayTag& Prev); /** * Called when the movement state changes. * 运动状态更改时调用。 * @param Prev The previous movement state. 之前的运动状态。 */ UFUNCTION(BlueprintNativeEvent, Category="GMS|Animation") void OnMovementStateChanged(const FGameplayTag& Prev); /** * Called when the overlay mode changes. * 叠层模式更改时调用。 * @param Prev The previous overlay mode. 之前的叠层模式。 */ UFUNCTION(BlueprintNativeEvent, Category="GMS|Animation") void OnOverlayModeChanged(const FGameplayTag& Prev); /** * Refreshes Trajectory-related data. * 刷新Trajectory相关数据。 * @param DeltaTime Time since last update. 自上次更新以来的时间。 */ virtual void RefreshTrajectoryState(float DeltaTime); /** * Refreshes view-related data. * 刷新视图相关数据。 * @param DeltaTime Time since last update. 自上次更新以来的时间。 */ virtual void RefreshView(float DeltaTime); /** * Refreshes locomotion data. * 刷新运动数据。 * @param DeltaTime Time since last update. 自上次更新以来的时间。 */ virtual void RefreshLocomotion(const float DeltaTime); /** * Refreshes block state. * 刷新阻塞状态。 */ virtual void RefreshBlock(); /** * Gather information from game world. * 从游戏世界获取信息。 */ virtual void RefreshStateOnGameThread(); /** * Refreshes animation node relevance tags on the game thread. * 在游戏线程上刷新动画节点相关性标签。 */ virtual void RefreshRelevanceOnGameThread(); /** * Refreshes grounded state data. * 刷新地面状态数据。 */ virtual void RefreshGrounded(); /** * Refreshes lean data for grounded state. * 刷新地面状态的倾斜数据。 */ virtual void RefreshGroundedLean(); /** * Gets the relative acceleration amount for leaning. * 获取用于倾斜的相对加速度量。 * @return 2D vector of relative acceleration. 相对加速度的2D向量。 */ virtual FVector2f GetRelativeAccelerationAmount() const; /** * Refreshes in-air state data. * 刷新空中状态数据。 */ virtual void RefreshInAir(); /** * Refreshes ground prediction data. * 刷新地面预测数据。 */ virtual void RefreshGroundPrediction(); /** * Refreshes lean data for in-air state. * 刷新空中状态的倾斜数据。 */ virtual void RefreshInAirLean(); /** * Refreshes the offset root bone state. * 刷新偏移根骨骼状态。 * @param Context Animation update context. 动画更新上下文。 * @param Node Animation node reference. 动画节点引用。 */ UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|Animation", meta=(BlueprintThreadSafe)) void RefreshOffsetRootBone(UPARAM(ref) FAnimUpdateContext& Context, UPARAM(ref) FAnimNodeReference& Node); public: /** * Gets the clamped curve value (0 to 1) for a given curve name. * 获取给定曲线名称的限制曲线值(0到1)。 * @param CurveName The name of the curve. 曲线名称。 * @return The clamped curve value. 限制的曲线值。 */ float GetCurveValueClamped01(const FName& CurveName) const; /** * Gets the named blend profile. * 获取命名的混合配置文件。 * @param BlendProfileName The name of the blend profile. 混合配置文件名称。 * @return The blend profile. 混合配置文件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) UBlendProfile* GetNamedBlendProfile(const FName& BlendProfileName) const; UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) FGameplayTagContainer GetAggregatedTags() const; /** * Gets the yaw value for aim offset. * 获取瞄准偏移的偏航值。 * @return The aim offset yaw value. 瞄准偏移偏航值。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) float GetAOYawValue() const; /** * Selects a cardinal direction based on an angle. * 根据角度选择主要方向。 * @param Angle The angle to evaluate. 要评估的角度。 * @param DeadZone The dead zone for direction changes. 方向变化的死区。 * @param CurrentDirection The current direction. 当前方向。 * @param bUseCurrentDirection Whether to consider the current direction. 是否考虑当前方向。 * @return The selected cardinal direction. 选择的主要方向。 */ EGMS_MovementDirection SelectCardinalDirectionFromAngle(float Angle, float DeadZone, EGMS_MovementDirection CurrentDirection, bool bUseCurrentDirection) const; /** * Selects an octagonal direction based on an angle. * 根据角度选择八方向。 * @param Angle The angle to evaluate. 要评估的角度。 * @param DeadZone The dead zone for direction changes. 方向变化的死区。 * @param CurrentDirection The current direction. 当前方向。 * @param bUseCurrentDirection Whether to consider the current direction. 是否考虑当前方向。 * @return The selected octagonal direction. 选择的八方向。 */ EGMS_MovementDirection_8Way SelectOctagonalDirectionFromAngle(float Angle, float DeadZone, EGMS_MovementDirection_8Way CurrentDirection, bool bUseCurrentDirection) const; /** * Gets the opposite cardinal direction. * 获取相反的主要方向。 * @param CurrentDirection The current direction. 当前方向。 * @return The opposite cardinal direction. 相反的主要方向。 */ EGMS_MovementDirection GetOppositeCardinalDirection(EGMS_MovementDirection CurrentDirection) const; /** * Checks if any core state has changed (movement set, state, locomotion, rotation, or overlay mode). * 检查是否有核心状态更改(运动集、状态、运动、旋转或叠层模式)。 * @return True if any core state has changed. 如果任何核心状态更改则返回true。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) bool HasCoreStateChanges() const; /** * Checks if specified core states have changed. * 检查指定的核心状态是否更改。 * @param bCheckLocomotionMode Check locomotion mode changes. 检查运动模式更改。 * @param bCheckMovementSet Check movement set changes. 检查运动集更改。 * @param bCheckRotationMode Check rotation mode changes. 检查旋转模式更改。 * @param bCheckMovementState Check movement state changes. 检查运动状态更改。 * @param bCheckOverlayMode Check overlay mode changes. 检查叠层模式更改。 * @return True if any specified state has changed. 如果任何指定状态更改则返回true。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|Animation", meta=(BlueprintThreadSafe)) bool CheckCoreStateChanges(bool bCheckLocomotionMode, bool bCheckMovementSet, bool bCheckRotationMode, bool bCheckMovementState, bool bCheckOverlayMode) const; /** * Animation state name to gameplay tag mappings. * 动画状态名称到游戏标签的映射。 * @note Used to check if a state node is active via NodeRelevantTags. 用于通过NodeRelevantTags检查状态节点是否活跃。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(TitleProperty="Tag")) TArray AnimStateNameToTagMapping; /** * Current locomotion mode. * 当前运动模式。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.LocomotionMode")) FGameplayTag LocomotionMode{GMS_MovementModeTags::Grounded}; /** * Container for locomotion mode (for chooser only). * 运动模式的容器(仅用于选择器)。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.LocomotionMode")) FGameplayTagContainer LocomotionModeContainer; /** * Current rotation mode. * 当前旋转模式。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.RotationMode")) FGameplayTag RotationMode{GMS_RotationModeTags::ViewDirection}; /** * Container for rotation mode (for chooser only). * 旋转模式的容器(仅用于选择器)。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.RotationMode")) FGameplayTagContainer RotationModeContainer; /** * Current movement state. * 当前运动状态。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.MovementState")) FGameplayTag MovementState{GMS_MovementStateTags::Jog}; /** * Container for movement state (for chooser only). * 运动状态的容器(仅用于选择器)。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.MovementState")) FGameplayTagContainer MovementStateContainer; /** * Current movement set. * 当前运动集。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.MovementSet")) FGameplayTag MovementSet; /** * Container for movement set (for chooser only). * 运动集的容器(仅用于选择器)。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.MovementSet")) FGameplayTagContainer MovementSetContainer; /** * Current overlay mode. * 当前叠层模式。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.OverlayMode")) FGameplayTag OverlayMode{GMS_OverlayModeTags::Default}; /** * Container for overlay mode (for chooser only). * 叠层模式的容器(仅用于选择器)。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings", meta=(Categories="GMS.OverlayMode")) FGameplayTagContainer OverlayModeContainer; /** * Enables ground prediction. * 启用地面预测。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings") bool bEnableGroundPrediction{false}; /** * General animation settings. * 通用动画设置。 */ UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category="Settings") FGMS_AnimDataSetting_General GeneralSetting; UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings", meta=(BlueprintThreadSafe)) TObjectPtr ControlSetting{nullptr}; UPROPERTY(Transient) FGMS_MovementBaseState MovementBase; /** * Locomotion state for the game thread. * 游戏线程的运动状态。 */ UPROPERTY(Transient) FGMS_LocomotionState GameLocomotionState; /** * Root bone animation state. * 根骨骼动画状态。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_Root RootState; /** * Locomotion animation state. * 运动动画状态。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_Locomotion LocomotionState; UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_Trajectory TrajectoryState; /** * View-related animation state. * 视图相关动画状态。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_View ViewState; /** * Lean animation state. * 倾斜动画状态。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_Lean LeanState; /** * Movement intent vector. * 运动意图向量。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State", meta=(DisplayName="Movement Intent")) FVector MovementIntent; /** * In-air animation state. * 空中动画状态。 */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="State") FGMS_AnimState_InAir InAirState; /** * Tags owned by the animation instance. * 动画实例拥有的标签。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") FGameplayTagContainer OwnedTags; /** * Tags indicating active animation nodes. * 指示活跃动画节点的标签。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") FGameplayTagContainer NodeRelevanceTags; /** * Indicates if any montage is playing. * 指示是否有蒙太奇在播放。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bAnyMontagePlaying{false}; /** * Indicates if the movement state has changed. * 指示运动状态是否更改。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bMovementStateChanged{false}; /** * Indicates if the locomotion mode has changed. * 指示运动模式是否更改。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bLocomotionModeChanged{false}; /** * Indicates if the movement set has changed. * 指示运动集是否更改。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bMovementSetChanged{false}; /** * Indicates if the rotation mode has changed. * 指示旋转模式是否更改。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bRotationModeChanged{false}; /** * Indicates if the overlay mode has changed. * 指示叠层模式是否更改。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bOverlayModeChanged{false}; /** * Indicates if movement is blocked. * 指示移动是否被阻塞。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State", meta=(DisplayName="Movement Blocked")) bool bBlocked{false}; /** * Indicates if the character has just landed. * 指示角色是否刚刚着陆。 */ UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="State") bool bJustLanded{false}; /** * Indicates if this is the first update. * 指示这是否是第一次更新。 */ bool bFirstUpdate = true; UPROPERTY() TScriptInterface TrajectoryPredictor; protected: /** * Reference to the movement system component. * 运动系统组件的引用。 */ UPROPERTY() TObjectPtr MovementSystem; /** * Reference to the owning pawn. * 拥有Pawn的引用。 */ UPROPERTY(Transient) TObjectPtr PawnOwner; /** * Runtime mappings of animation state names to tags. * 动画状态名称到标签的运行时映射。 */ UPROPERTY() TMap, FGMS_AnimStateNameToTagWrapper> RuntimeAnimStateNameToTagMappings; /** * Timer handle for initial updates. * 初始更新的计时器句柄。 */ FTimerHandle InitialTimerHandle; /** * Animation layer instance for states. * 状态动画层实例。 */ UPROPERTY(VisibleInstanceOnly, Category="AnimLayers", meta=(ShowInnerProperties)) TObjectPtr StateLayerInstance; /** * Animation layer instance for overlays. * 叠层动画层实例。 */ UPROPERTY(VisibleInstanceOnly, Category="AnimLayers", meta=(ShowInnerProperties)) TObjectPtr OverlayLayerInstance; /** * Animation layer instance for view. * 视图动画层实例。 */ UPROPERTY(VisibleInstanceOnly, Category="AnimLayers", meta=(ShowInnerProperties)) TObjectPtr ViewLayerInstance; /** * Animation layer instance for additive animations. * 附加动画层实例。 */ UPROPERTY(VisibleInstanceOnly, Category="AnimLayers", meta=(ShowInnerProperties)) TObjectPtr AdditiveLayerInstance; /** * Animation layer instance for skeletal controls. * 骨骼控制动画层实例。 */ UPROPERTY(VisibleInstanceOnly, Category="AnimLayers", meta=(ShowInnerProperties)) TObjectPtr SkeletonControlsLayerInstance; };