第一次提交

2026-03-03 01:23:02 +08:00
commit 3e434877e8
1053 changed files with 102411 additions and 0 deletions
--- a/Plugins/GCS/Source/GenericGameplayAbilities/Public/Utilities/GGA_GameplayEffectFunctionLibrary.h
+++ b/Plugins/GCS/Source/GenericGameplayAbilities/Public/Utilities/GGA_GameplayEffectFunctionLibrary.h
@@ -0,0 +1,226 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GameplayEffectTypes.h"
+#include "GGA_GameplayEffectContext.h"
+#include "Kismet/BlueprintFunctionLibrary.h"
+#include "Runtime/Launch/Resources/Version.h"
+#if ENGINE_MINOR_VERSION < 5
+#include "InstancedStruct.h"
+#else
+#include "StructUtils/InstancedStruct.h"
+#endif
+#include "GGA_GameplayEffectFunctionLibrary.generated.h"
+
+UENUM()
+enum class EGGA_ContextPayloadResult : uint8
+{
+	Valid,
+	NotValid,
+};
+
+/**
+ * Blueprint function library for gameplay effect operations.
+ * 用于游戏效果操作的蓝图函数库。
+ */
+UCLASS()
+class GENERICGAMEPLAYABILITIES_API UGGA_GameplayEffectFunctionLibrary : public UBlueprintFunctionLibrary
+{
+	GENERATED_BODY()
+
+public:
+#pragma region EffectSpecHandle
+
+	/**
+	 * Retrieves the magnitude of a SetByCaller modifier by tag.
+	 * 通过标签获取SetByCaller修改器的大小。
+	 * @param SpecHandle The gameplay effect spec handle. 游戏效果规格句柄。
+	 * @param DataTag The tag to query. 要查询的标签。
+	 * @param WarnIfNotFound Whether to warn if the tag is not found. 如果未找到标签是否警告。
+	 * @param DefaultIfNotFound Default value if the tag is not found. 如果未找到标签的默认值。
+	 * @return The magnitude value, or default if not found. 大小值，未找到时返回默认值。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect")
+	static float GetSetByCallerMagnitudeByTag(FGameplayEffectSpecHandle SpecHandle, FGameplayTag DataTag, bool WarnIfNotFound = false, float DefaultIfNotFound = 0.0f);
+
+	/**
+	 * Retrieves the magnitude of a SetByCaller modifier by name.
+	 * 通过名称获取SetByCaller修改器的大小。
+	 * @param SpecHandle The gameplay effect spec handle. 游戏效果规格句柄。
+	 * @param DataName The name to query. 要查询的名称。
+	 * @return The magnitude value, or zero if not found. 大小值，未找到时返回零。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect")
+	static float GetSetByCallerMagnitudeByName(FGameplayEffectSpecHandle SpecHandle, FName DataName);
+
+	/**
+	 * Checks if the active gameplay effect handle is valid.
+	 * 检查活动游戏效果句柄是否有效。
+	 * @param Handle The active gameplay effect handle. 活动游戏效果句柄。
+	 * @return True if the handle is valid, false otherwise. 如果句柄有效则返回true，否则返回false。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect")
+	static bool IsActiveGameplayEffectHandleValid(FActiveGameplayEffectHandle Handle);
+
+#pragma endregion
+
+#pragma region EffectSpec
+	/**
+	 * Retrieves the magnitude of a SetByCaller modifier by tag.
+	 * 通过标签获取SetByCaller修改器的大小。
+	 * @param EffectSpec The gameplay effect spec . 游戏效果规格。
+	 * @param DataTag The tag to query. 要查询的标签。
+	 * @param WarnIfNotFound Whether to warn if the tag is not found. 如果未找到标签是否警告。
+	 * @param DefaultIfNotFound Default value if the tag is not found. 如果未找到标签的默认值。
+	 * @return The magnitude value, or default if not found. 大小值，未找到时返回默认值。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect")
+	static float GetSetByCallerMagnitudeByTagFromSpec(const FGameplayEffectSpec& EffectSpec, FGameplayTag DataTag, bool WarnIfNotFound = false, float DefaultIfNotFound = 0.0f);
+
+#pragma endregion
+
+#pragma region Effect Context
+	/**
+	 * Retrieves gameplay tags from the effect context.
+	 * 从效果上下文中获取游戏标签。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @param ActorTagContainer Container for actor tags. 演员标签容器。
+	 * @param SpecTagContainer Container for spec tags. 规格标签容器。
+	 */
+	UFUNCTION(BlueprintCallable, Category = "GGA|GameplayEffect|Context")
+	static void GetOwnedGameplayTags(FGameplayEffectContextHandle EffectContext, FGameplayTagContainer& ActorTagContainer, FGameplayTagContainer& SpecTagContainer);
+
+	/**
+	 * Sets the instigator and effect causer in the effect context.
+	 * 在效果上下文中设置发起者和效果原因。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @param InInstigator The instigator actor. 发起者演员。
+	 * @param InEffectCauser The effect causer actor. 效果原因演员。
+	 */
+	UFUNCTION(BlueprintCallable, Category = "GGA|GameplayEffect|Context")
+	static void AddInstigator(FGameplayEffectContextHandle EffectContext, AActor* InInstigator, AActor* InEffectCauser);
+
+	/**
+	 * Sets the effect causer in the effect context.
+	 * 在效果上下文中设置效果原因。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @param InEffectCauser The effect causer actor. 效果原因演员。
+	 */
+	UFUNCTION(BlueprintCallable, Category = "GGA|GameplayEffect|Context")
+	static void SetEffectCauser(FGameplayEffectContextHandle EffectContext, AActor* InEffectCauser);
+
+	/**
+	 * Sets the ability in the effect context.
+	 * 在效果上下文中设置技能。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @param InGameplayAbility The gameplay ability to set. 要设置的游戏技能。
+	 */
+	UFUNCTION(BlueprintCallable, Category = "GGA|GameplayEffect|Context")
+	static void SetAbility(FGameplayEffectContextHandle EffectContext, const UGameplayAbility* InGameplayAbility);
+
+	/**
+	 * Retrieves the ability CDO from the effect context.
+	 * 从效果上下文中获取技能CDO。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return The ability CDO. 技能CDO。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static const UGameplayAbility* GetAbilityCDO(FGameplayEffectContextHandle EffectContext);
+
+	/**
+	 * Retrieves the ability instance from the effect context.
+	 * 从效果上下文中获取技能实例。
+	 * @attention The ability instance is not replicated so it's only valid on server side. 技能实例未网络复制，因此仅服务端可用。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return The ability instance. 技能实例。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static const UGameplayAbility* GetAbilityInstance(FGameplayEffectContextHandle EffectContext);
+
+	/**
+	 * Retrieves the ability level from the effect context.
+	 * 从效果上下文中获取技能等级。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return The ability level. 技能等级。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static int32 GetAbilityLevel(FGameplayEffectContextHandle EffectContext);
+
+	/**
+	 * Retrieves the instigator's ability system component.
+	 * 获取发起者的技能系统组件。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return The instigator's ability system component. 发起者的技能系统组件。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static UAbilitySystemComponent* GetInstigatorAbilitySystemComponent(FGameplayEffectContextHandle EffectContext);
+
+	/**
+	 * Retrieves the original instigator's ability system component.
+	 * 获取原始发起者的技能系统组件。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return The original instigator's ability system component. 原始发起者的技能系统组件。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static UAbilitySystemComponent* GetOriginalInstigatorAbilitySystemComponent(FGameplayEffectContextHandle EffectContext);
+
+	/**
+	 * Sets the source object in the effect context.
+	 * 在效果上下文中设置源对象。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @param NewSourceObject The source object to set. 要设置的源对象。
+	 */
+	UFUNCTION(BlueprintCallable, Category = "GGA|GameplayEffect|Context")
+	static void AddSourceObject(FGameplayEffectContextHandle EffectContext, const UObject* NewSourceObject);
+
+	/**
+	 * Checks if the effect context has an origin.
+	 * 检查效果上下文是否具有起源。
+	 * @param EffectContext The effect context handle. 效果上下文句柄。
+	 * @return True if the context has an origin, false otherwise. 如果上下文有起源则返回true，否则返回false。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static bool HasOrigin(FGameplayEffectContextHandle EffectContext);
+
+#pragma endregion
+
+#pragma region Custom Effect Context
+
+	/**
+	 * Helper method to safely get the pointer of GGA_GameplayEffectContext.
+	 * 用于安全地获取GGA_GameplayEffectContext的实用函数。
+	 * @param EffectContext The gameplay effect context handle 游戏效果上下文句柄。
+	 * @return The actually FGGA_GameplayEffectContext pointer.
+	 */
+	static FGGA_GameplayEffectContext* GetEffectContextPtr(FGameplayEffectContextHandle EffectContext);
+
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context")
+	static bool HasContextPayload(FGameplayEffectContextHandle EffectContext, const UScriptStruct* PayloadType);
+
+	static bool GetContextPayload(FGameplayEffectContextHandle EffectContext, const UScriptStruct* PayloadType, FInstancedStruct& OutPayload);
+
+	/**
+	 * Do not call this,It's for blueprint only.
+	 * 不要调用这个，这是给蓝图专用的。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GGA|GameplayEffect|Context", meta=(BlueprintInternalUseOnly="true"))
+	static FInstancedStruct GetValidContextPayload(FGameplayEffectContextHandle EffectContext, const UScriptStruct* PayloadType, bool& bValid);
+
+	/**
+	 * Do not call this,It's for blueprint only.
+	 * 不要调用这个，这是给蓝图专用的。
+	 */
+	UFUNCTION(BlueprintCallable, CustomThunk, Category = "GGA|GameplayEffect|Context", meta=(CustomStructureParam = "Value", ExpandEnumAsExecs = "ExecResult", BlueprintInternalUseOnly="true"))
+	static void GetContextPayload(FGameplayEffectContextHandle EffectContext, const UScriptStruct* PayloadType, EGGA_ContextPayloadResult& ExecResult, int32& Value);
+
+	UFUNCTION(BlueprintCallable, CustomThunk, Category = "GGA|GameplayEffect|Context",
+		meta=(CustomStructureParam = "Value", ExpandEnumAsExecs = "ExecResult", BlueprintInternalUseOnly="true"))
+	static void SetContextPayload(FGameplayEffectContextHandle EffectContext, EGGA_ContextPayloadResult& ExecResult, const int32& Value);
+
+private:
+	DECLARE_FUNCTION(execGetContextPayload);
+	DECLARE_FUNCTION(execSetContextPayload);
+#pragma endregion
+};