QuartzUIGASBindingScope: declaration reference

#pragma once

#include "ActiveGameplayEffectHandle.h"
#include "GameplayAbilitySpecHandle.h"
#include "Containers/Ticker.h"
#include "CoreMinimal.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "QuartzUIBindingScope.h"
#include "QuartzUIGASConfig.h"
#include "QuartzUIGASContract.h"
#include "QuartzUITypedEndpoint.h"

#include "QuartzUIGASBindingScope.generated.h"

class APlayerController;
class APawn;
class UAbilitySystemComponent;
class UGameplayAbility;
class ULocalPlayer;
class UQuartzUIGASBindingScope;
class UQuartzUIGASResolver;
struct FAbilityEndedData;
struct FActiveGameplayEffect;
struct FGameplayAbilityActorInfo;
struct FGameplayAbilitySpec;
struct FGameplayEffectSpec;
struct FOnAttributeChangeData;

/** Runtime-only reflected attribute descriptor. Contains no UObject reference. */
struct FQuartzUIGASObservedAttribute
{
	FString Id;
	FGameplayAttribute Attribute;
};

/** Runtime-only gameplay-tag descriptor retained after its first observation. */
struct FQuartzUIGASObservedTag
{
	FString Id;
	FGameplayTag Tag;
};

/** Runtime-only granted-spec descriptor. The handle is never serialized to JavaScript. */
struct FQuartzUIGASObservedAbility
{
	FString Id;
	FSoftObjectPath AbilityClassPath;
	FGameplayTag SpecSourceTag;
	FGameplayAbilitySpecHandle Handle;
	bool bExplicitActivationAllowed = false;
	bool bExplicitCancellationAllowed = false;
};

/** Typed authoritative activation request owned by one GAS binding scope. */
UCLASS()
class QUARTZUIGAS_API UQuartzUIGASActivateEndpoint final : public UQuartzUITypedEndpoint
{
	GENERATED_BODY()

public:
	UQuartzUIGASActivateEndpoint();
	virtual void HandleRequest_Implementation(
		const FInstancedStruct& Payload,
		UQuartzUITypedEndpointRequest* Request) override;
};

/** Typed authoritative cancellation request owned by one GAS binding scope. */
UCLASS()
class QUARTZUIGAS_API UQuartzUIGASCancelEndpoint final : public UQuartzUITypedEndpoint
{
	GENERATED_BODY()

public:
	UQuartzUIGASCancelEndpoint();
	virtual void HandleRequest_Implementation(
		const FInstancedStruct& Payload,
		UQuartzUITypedEndpointRequest* Request) override;
};

/** Delegate registrations owned by one observed active effect. */
struct FQuartzUIGASEffectDelegateHandles
{
	FDelegateHandle Stack;
	FDelegateHandle Time;
	FDelegateHandle Inhibition;
};

/**
 * Optional generic GAS provider for one exact LocalPlayer.
 * Spawned AttributeSets, owned tags, granted specs, and active effects are
 * reflected automatically and converted to immutable typed DTOs.
 */
UCLASS(BlueprintType)
class QUARTZUIGAS_API UQuartzUIGASBindingScope final : public UQuartzUIBindingScope
{
	GENERATED_BODY()

public:
	UQuartzUIGASBindingScope(const FObjectInitializer& ObjectInitializer);

	static constexpr float ReconcileIntervalSeconds = 0.1f;
	static constexpr int32 MaxBrowserActionsPerSecond = 16;

	/** Must be called while detached, before AttachToShell or AttachToView. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|GAS")
	bool InitializeGAS(
		UQuartzUIGASConfig* InConfig = nullptr,
		UQuartzUIGASResolver* InResolver = nullptr,
		EQuartzUIGASBrowserAbilityActionPolicy InActionPolicy =
			EQuartzUIGASBrowserAbilityActionPolicy::Disabled);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|GAS")
	UQuartzUIGASConfig* GetGASConfig() const { return Config; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|GAS")
	bool HasResolvedAbilitySystem() const { return AbilitySystem.IsValid(); }

	/** Re-evaluates the exact controller/PlayerState/pawn context immediately. */
	bool ReconcileAbilitySystem();

	bool HandleAbilityRequest(
		bool bActivate,
		const FQuartzUIGASAbilityActionRequest& Payload,
		FQuartzUIGASAbilityActionResult& OutResult);

protected:
	virtual bool BeginBinding_Implementation(
		ULocalPlayer* LocalPlayer,
		UQuartzUIView* View) override;
	virtual bool PublishInitialState_Implementation() override;
	virtual void EndBinding_Implementation() override;
	virtual bool CanUseReservedContractMessages() const override { return true; }

private:
	bool HandleReconcileTick(float DeltaSeconds);
	void HandlePlayerControllerChanged(APlayerController* NewController);
	void HandlePawnChanged(APawn* NewPawn);
	void UpdateControllerBinding();
	void BindAbilitySystem(UAbilitySystemComponent* NewAbilitySystem);
	void UnbindAbilitySystem();
	bool ReconcileObservedCatalog();
	void RebuildObservedAttributes();
	void RebuildObservedAbilities();
	void InitializeObservedTags();
	void ObserveTag(FGameplayTag Tag, bool bBindDelegate);
	void BindActiveEffect(FActiveGameplayEffectHandle Handle);
	void UnbindActiveEffects();

	FQuartzUIGASContextState BuildContextState() const;
	FQuartzUIGASAttributeState BuildAttributeState() const;
	FQuartzUIGASTagState BuildTagState() const;
	FQuartzUIGASAbilityState BuildAbilityState() const;
	FQuartzUIGASStatusEffectState BuildStatusEffectState();
	FQuartzUIGASAbility BuildAbility(
		const FQuartzUIGASObservedAbility& Observed,
		const FGameplayAbilitySpec* Spec) const;
	bool BuildStatusEffect(
		const FActiveGameplayEffect& Effect,
		FQuartzUIGASStatusEffect& OutEffect);
	bool PublishFullState();
	bool PublishAttributeAndAbilityState();
	bool PublishTagAndAbilityState();
	bool PublishAbilityState(bool bEmitDiffEvents);
	bool PublishStatusAndAbilityState();
	void CommitAbilitySnapshot(
		const FQuartzUIGASAbilityState& AbilitySnapshot,
		bool bEmitDiffEvents);
	void EmitAbilityEvent(const FString& Kind, const FQuartzUIGASAbility& Ability);
	void EmitStatusEffectEvent(const FString& Kind, const FQuartzUIGASStatusEffect& Effect);

	const FGameplayAbilitySpec* FindAbilitySpec(const FQuartzUIGASObservedAbility& Observed) const;
	const FQuartzUIGASObservedAbility* FindObservedAbility(FName AbilityId) const;
	const FQuartzUIGASObservedAbility* FindObservedAbility(
		const UGameplayAbility* Ability,
		const FGameplayAbilitySpec*& OutSpec) const;
	const FQuartzUIGASAbilityMapping* FindAbilityOverride(
		const FGameplayAbilitySpec& Spec) const;
	FString GetAttributeId(const FGameplayAttribute& Attribute) const;
	FString GetTagId(FGameplayTag Tag) const;
	FString GetAbilityId(const FGameplayAbilitySpec& Spec) const;
	FString GetStatusEffectId(const UClass* EffectClass) const;
	bool ShouldObserveStatusEffect(const UClass* EffectClass) const;
	const FGameplayAbilityActorInfo* FindActorInfo(
		const FGameplayAbilitySpec& Spec) const;
	TArray<FString> MapFailureReasons(const FGameplayTagContainer& Tags) const;
	uint32 ComputeAttributeCatalogFingerprint() const;
	uint32 ComputeAbilityCatalogFingerprint() const;
	float GetCaptureTime() const;
	FString GetOrCreateEffectInstanceId(FActiveGameplayEffectHandle Handle);
	bool ConsumeActionBudget();
	void AdvanceRevision();

	void HandleAttributeChanged(const FOnAttributeChangeData& Data);
	void HandleGenericTagChanged(FGameplayTag Tag, int32 NewCount);
	void HandleTagChanged(FGameplayTag Tag, int32 NewCount);
	void HandleAbilityActivated(UGameplayAbility* Ability);
	void HandleAbilityCommitted(UGameplayAbility* Ability);
	void HandleAbilityFailed(
		const UGameplayAbility* Ability,
		const FGameplayTagContainer& FailureReasons);
	void HandleAbilityEnded(const FAbilityEndedData& EndedData);
	void HandleAbilitySpecDirtied(const FGameplayAbilitySpec& Spec);
	void HandleEffectAdded(
		UAbilitySystemComponent* Source,
		const FGameplayEffectSpec& Spec,
		FActiveGameplayEffectHandle Handle);
	void HandleEffectRemoved(const FActiveGameplayEffect& Effect);
	void HandleEffectStackChanged(
		FActiveGameplayEffectHandle Handle,
		int32 NewCount,
		int32 PreviousCount);
	void HandleEffectTimeChanged(
		FActiveGameplayEffectHandle Handle,
		float NewStartTime,
		float NewDuration);
	void HandleEffectInhibitionChanged(
		FActiveGameplayEffectHandle Handle,
		bool bInhibited);

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIGASConfig> Config;

	EQuartzUIGASBrowserAbilityActionPolicy BrowserAbilityActionPolicy =
		EQuartzUIGASBrowserAbilityActionPolicy::Disabled;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIGASResolver> Resolver;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIGASActivateEndpoint> ActivateEndpoint;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIGASCancelEndpoint> CancelEndpoint;

	TWeakObjectPtr<UAbilitySystemComponent> AbilitySystem;
	TWeakObjectPtr<APlayerController> BoundController;
	TWeakObjectPtr<AActor> BoundAvatar;
	FTSTicker::FDelegateHandle ReconcileTicker;
	FDelegateHandle PlayerControllerChangedHandle;
	FDelegateHandle PawnChangedHandle;
	TMap<FGameplayAttribute, FDelegateHandle> AttributeHandles;
	TMap<FGameplayTag, FDelegateHandle> TagHandles;
	TMap<FGameplayTag, int32> LastTagCounts;
	TArray<FQuartzUIGASObservedAttribute> ObservedAttributes;
	TArray<FQuartzUIGASObservedTag> ObservedTags;
	TArray<FQuartzUIGASObservedAbility> ObservedAbilities;
	FDelegateHandle GenericTagHandle;
	FDelegateHandle AbilityActivatedHandle;
	FDelegateHandle AbilityCommittedHandle;
	FDelegateHandle AbilityFailedHandle;
	FDelegateHandle AbilityEndedHandle;
	FDelegateHandle AbilitySpecDirtiedHandle;
	FDelegateHandle EffectAddedHandle;
	FDelegateHandle EffectRemovedHandle;
	TMap<FActiveGameplayEffectHandle, FQuartzUIGASEffectDelegateHandles> ActiveEffectHandles;
	TMap<FActiveGameplayEffectHandle, FString> EffectInstanceIds;
	TMap<FString, FQuartzUIGASAbility> LastAbilities;
	TArray<double> RecentBrowserActionTimes;
	int64 ContextGeneration = 0;
	int64 Revision = 0;
	int64 NextEffectInstance = 0;
	uint32 AttributeCatalogFingerprint = 0;
	uint32 AbilityCatalogFingerprint = 0;

	friend class UQuartzUIGASActivateEndpoint;
	friend class UQuartzUIGASCancelEndpoint;
	friend class FQuartzUIGASTestAccess;
};

UCLASS()
class QUARTZUIGAS_API UQuartzUIGASBlueprintLibrary final : public UBlueprintFunctionLibrary
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|GAS", meta = (DefaultToSelf = "Outer"))
	static UQuartzUIGASBindingScope* CreateGASBindingScope(
		UObject* Outer,
		UQuartzUIGASConfig* Config = nullptr,
		UQuartzUIGASResolver* Resolver = nullptr,
		EQuartzUIGASBrowserAbilityActionPolicy BrowserAbilityActionPolicy =
			EQuartzUIGASBrowserAbilityActionPolicy::Disabled);
};