PHY/Plugins/GCS/Source/GenericCombatSystem/Public/GCS_CombatStructLibrary.h

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

#pragma once

#include "CoreMinimal.h"
#include "GameplayEffect.h"
#include "GameplayTagContainer.h"
#include "StructUtils/InstancedStruct.h"
#include "UObject/Object.h"
#include "GCS_CombatStructLibrary.generated.h"

class UTargetingPreset;
class UAnimMontage;

/**
 * Structure for tagged value pairs.
 * 标记值对的结构。
 */
USTRUCT(BlueprintType)
struct GENERICCOMBATSYSTEM_API FGCS_TaggedValue
{
	GENERATED_BODY()

	/**
	 * The gameplay tag for the attribute.
	 * 属性的游戏标签。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
	FGameplayTag Attribute;

	/**
	 * The value applied to the attribute.
	 * 应用于属性的值。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
	float Value{0};
};

USTRUCT(BlueprintType, meta=(Hidden))
struct GENERICCOMBATSYSTEM_API FGCS_AbilityActionExtension
{
	GENERATED_BODY()
};

/**
 * Structure for ability actions.
 * 能力动作的结构。
 */
USTRUCT(BlueprintType)
struct GENERICCOMBATSYSTEM_API FGCS_AbilityAction
{
	GENERATED_BODY()

	/**
	 * The animation montage to play.
	 * 要播放的动画蒙太奇。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	TObjectPtr<UAnimMontage> Animation;

	/**
	 * The playback rate for the montage.
	 * 蒙太奇的播放速率。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	float PlayRate{1.f};

	/**
	 * The starting section name for the montage.
	 * 蒙太奇的起始片段名称。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	FName StartSection{NAME_None};

	/**
	 * Whether to stop the montage when the ability ends.
	 * 能力结束时是否停止蒙太奇。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	bool bStopWhenAbilityEnds{true};

	/**
	 * Indicate if the selected anim sequence has root motion enabled.(It was auto calculated during save.)
	 * 标识选择的动画序列是启用了根运动。（保存时自动设置。）
	 */
	UPROPERTY(VisibleAnywhere, Category = "Animation", Meta=(EditCondition=False, EditConditionHides))
	bool bHasRootMotion{false};

	/**
	 * Scale for animation root motion translation.
	 * 动画根运动平移的缩放。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	float AnimRootMotionTranslationScale{1.f};

	/**
	 * Start time for the montage in seconds.
	 * 蒙太奇的起始时间（秒）。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	float StartTimeSeconds{0.f};

	/**
	 * Whether to allow interruption after blend out.
	 * 是否允许在混合结束时中断。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Animation")
	bool bAllowInterruptAfterBlendOut{false};

	/**
	 * Gameplay effect for ability cost.
	 * 能力消耗的游戏效果。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GameplayEffects")
	TSubclassOf<UGameplayEffect> CostGameplayEffect;

	/**
	 * Allowing C++ users to add custom fields to ability action.
	 * 允许C++用户添加自定义字段到AbilityAction。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Extension")
	TInstancedStruct<FGCS_AbilityActionExtension> Extension;

#if WITH_EDITORONLY_DATA
	/**
	 * Editor-friendly name for the ability action.
	 * 能力动作的编辑器友好名称。
	 */
	UPROPERTY(VisibleAnywhere, Category=AlwaysHidden, Meta=(EditCondition=False, EditConditionHides))
	FString EditorFriendlyName;
#endif
};

/**
 * Structure for ability actions with tag queries.
 * 带有标签查询的能力动作结构。
 */
USTRUCT(BlueprintType)
struct GENERICCOMBATSYSTEM_API FGCS_AbilityActionsWithQuery
{
	GENERATED_BODY()

	/**
	 * Source tag query for filtering.
	 * 用于过滤的来源标签查询。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS")
	FGameplayTagQuery SourceTagQuery;

	/**
	 * Target tag query for filtering.
	 * 用于过滤的目标标签查询。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS")
	FGameplayTagQuery TargetTagQuery;

	/**
	 * Array of ability actions.
	 * 能力动作数组。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS", meta=(TitleProperty="EditorFriendlyName"))
	TArray<FGCS_AbilityAction> Actions;

#if WITH_EDITORONLY_DATA
	/**
	 * Editor-friendly name for the action set.
	 * 动作集的编辑器友好名称。
	 */
	UPROPERTY(VisibleAnywhere, Category=AlwaysHidden, Meta=(EditCondition=False, EditConditionHides))
	FString EditorFriendlyName;
#endif
};

/**
 * Structure for ability action sets.
 * 能力动作集的结构。
 */
USTRUCT(BlueprintType)
struct GENERICCOMBATSYSTEM_API FGCS_AbilityActionSet
{
	GENERATED_BODY()

	/**
	 * The gameplay tag for the ability.
	 * 能力的游戏标签。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS")
	FGameplayTag AbilityTag;

	/**
	 * Array of ability actions.
	 * 能力动作数组。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS", meta=(TitleProperty="EditorFriendlyName"))
	TArray<FGCS_AbilityAction> Actions;

	/**
	 * Layered action sets for conditional selection based on tags.
	 * 基于标签条件选择的层次动作集。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "GCS", meta=(TitleProperty="EditorFriendlyName"))
	TArray<FGCS_AbilityActionsWithQuery> Layered;
};

/**
 * Base structure for user settings.
 * 用户设置的基结构。
 */
USTRUCT(BlueprintType)
struct UE_DEPRECATED(1.5, "Using Extension field insted of this one.") GENERICCOMBATSYSTEM_API FGCS_UserSetting
{
	GENERATED_BODY()
};

/**
 * User settings structure for tag-to-float mappings.
 * 标签到浮点映射的用户设置结构。
 */
USTRUCT(BlueprintType)
struct UE_DEPRECATED(1.5, "this sample also deprecated due to FGCS_UserSetting was deprecated.") FGCS_UserSetting_Attributes : public FGCS_UserSetting
{
	GENERATED_BODY()

	/**
	 * Map of gameplay tags to float attributes.
	 * 游戏标签到浮点属性的映射。
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="UserSettings")
	TMap<FGameplayTag, float> Attributes;
};