PHY/Plugins/GMS/Source/GenericMovementSystem/Public/Locomotions/GMS_AnimLayer.h

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

#pragma once

#include "CoreMinimal.h"
#include "GMS_LocomotionStructLibrary.h"
#include "Engine/DataAsset.h"
#include "Animation/AnimInstance.h"
#include "GMS_AnimLayer.generated.h"

class UGMS_MovementDefinition;
class UGMS_AnimLayer;
class UGMS_MovementSystemComponent;
class UGMS_MainAnimInstance;
class APawn;

/**
 * Base class for animation layer settings.
 * 动画层设置的基类。
 */
UCLASS(Abstract, BlueprintType, EditInlineNew, Const, CollapseCategories)
class GENERICMOVEMENTSYSTEM_API UGMS_AnimLayerSetting : public UDataAsset
{
	GENERATED_BODY()

public:
	/**
	 * Gets the override animation layer class.
	 * 获取覆盖的动画层类。
	 * @param OutLayerClass The output animation layer class. 输出的动画层类。
	 * @return True if an override class is provided. 如果提供了覆盖类则返回true。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|AnimationLayer")
	bool GetOverrideAnimLayerClass(TSubclassOf<UGMS_AnimLayer>& OutLayerClass) const;

	/**
	 * Validates the data for this animation layer setting.
	 * 验证此动画层设置的数据。
	 * @param ErrorText The error message if validation fails. 如果验证失败的错误信息。
	 * @return True if data is valid. 如果数据有效则返回true。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|AnimationLayer", meta=(DisplayName="Is Data Valid"))
	bool K2_IsDataValid(FText& ErrorText) const;

#if WITH_EDITOR

public:
	/**
	 * Validates data in the editor.
	 * 在编辑器中验证数据。
	 * @param Context The validation context. 验证上下文。
	 * @return The validation result. 验证结果。
	 */
	virtual EDataValidationResult IsDataValid(class FDataValidationContext& Context) const override;
#endif
};

/**
 * Base class for all animation layers.
 * 所有动画层的基类。
 * @note Classes inheriting from this must only be linked to GMS_MainAnimInstance (the main animation instance). 从该类继承的类只能链接到GMS_MainAnimInstance（主动画实例）。
 */
UCLASS(BlueprintType, Abstract)
class GENERICMOVEMENTSYSTEM_API UGMS_AnimLayer : public UAnimInstance
{
	GENERATED_BODY()

protected:
	/**
	 * The owning pawn of this animation layer.
	 * 此动画层的拥有Pawn。
	 */
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="State", Transient)
	TObjectPtr<APawn> PawnOwner;

	/**
	 * Reference to the movement system component.
	 * 运动系统组件的引用。
	 */
	UPROPERTY(Transient)
	TObjectPtr<UGMS_MovementSystemComponent> MovementSystem;

private:
	/**
	 * Weak reference to the parent main animation instance.
	 * 对父主动画实例的弱引用。
	 */
	UPROPERTY(VisibleAnywhere, Category="State", Transient)
	TWeakObjectPtr<UGMS_MainAnimInstance> Parent;

public:
	/**
	 * Constructor.
	 * 构造函数。
	 */
	UGMS_AnimLayer();

	/**
	 * Gets the parent main animation instance.
	 * 获取父主动画实例。
	 * @return The parent main animation instance. 父主动画实例。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GMS|AnimationLayer", Meta = (BlueprintThreadSafe, ReturnDisplayName = "Parent"))
	UGMS_MainAnimInstance* GetParent() const;

	/**
	 * Called when the animation layer is linked to the main animation instance.
	 * 当动画层链接到主动画实例时调用。
	 * @note Suitable for initialization tasks similar to BeginPlay. 适合执行类似BeginPlay的初始化任务。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|AnimationLayer")
	void OnLinked();
	virtual void OnLinked_Implementation();

	/**
	 * Called when the animation layer is unlinked from the main animation instance.
	 * 当动画层从主动画实例取消链接时调用。
	 * @note Suitable for cleanup tasks similar to EndPlay. 适合执行类似EndPlay的清理任务。
	 */
	UFUNCTION(BlueprintNativeEvent, Category="GMS|AnimationLayer")
	void OnUnlinked();
	virtual void OnUnlinked_Implementation();

	/**
	 * Applies settings to the animation layer.
	 * 向动画层应用设置。
	 * @param Setting The setting object to apply, cast to the desired type. 要应用的设置对象，可转换为所需类型。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|AnimationLayer")
	void ApplySetting(const UGMS_AnimLayerSetting* Setting);
	virtual void ApplySetting_Implementation(const UGMS_AnimLayerSetting* Setting);

	/**
	 * Resets the settings of the animation layer.
	 * 重置动画层的设置。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GMS|AnimationLayer")
	void ResetSetting();
	virtual void ResetSetting_Implementation();

	/**
	 * Initializes the animation.
	 * 初始化动画。
	 */
	virtual void NativeInitializeAnimation() override;

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

	/**
	 * Maps animation state names to gameplay tags for checking node relevance.
	 * 将动画状态名称映射到游戏标签以检查节点相关性。
	 * @note Used to determine if an animation state node is active via NodeRelevantTags in the main animation instance. 用于通过主动画实例中的NodeRelevantTags确定动画状态节点是否活跃。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Settings", meta=(TitleProperty="Tag"))
	TArray<FGMS_AnimStateNameToTag> AnimStateNameToTagMapping;
};