QuartzUIBindingComponentBase: declaration reference

#pragma once

#include "Components/ActorComponent.h"
#include "Containers/Ticker.h"
#include "CoreMinimal.h"

#include "QuartzUIBindingComponentBase.generated.h"

class ULocalPlayer;
class UQuartzUIView;

/** Shared, native-only lifecycle used by feature-owned QuartzUI binding components. */
enum class EQuartzUIBindingComponentLifecycleState : uint8
{
	Inactive,
	WaitingForLocalPlayer,
	WaitingForShell,
	WaitingForBinding,
	Bound,
	Failed
};

/** Result of a derived component's exact-player shell attachment attempt. */
enum class EQuartzUIBindingAttachResult : uint8
{
	Attached,
	Retry,
	Fatal
};

/**
 * Common exact-player resolution, retained-shell startup, retry, failure, and
 * teardown machinery for feature-owned QuartzUI binding components.
 */
UCLASS(Abstract, BlueprintType, Blueprintable, ClassGroup = (QuartzUI))
class QUARTZUIRUNTIME_API UQuartzUIBindingComponentBase : public UActorComponent
{
	GENERATED_BODY()

public:
	UQuartzUIBindingComponentBase();

	/** Resolves a LocalPlayer only through this component's bounded owner chain. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Component")
	ULocalPlayer* GetBindingLocalPlayer() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Component")
	FName GetLastBindingFailure() const { return LastFailure; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Component")
	bool IsBindingRequested() const { return bBindingRequested; }

	/** Starts or reuses the retained exact-player shell when needed. */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Binding Component")
	bool bStartShellIfNeeded = true;

	/** Suitable for client components installed by GameFeatureAction_AddComponents. */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Binding Component")
	bool bBindOnBeginPlay = true;

	/** Exact-player/shell reconciliation interval while the feature is active. */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Binding Component",
		meta = (ClampMin = "0.05", ClampMax = "5.0"))
	float RetryIntervalSeconds = 0.1f;

protected:
	virtual void BeginPlay() override;
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;
	virtual void OnComponentDestroyed(bool bDestroyingHierarchy) override;

	bool ActivateBindingRequest();
	bool DeactivateBindingRequest();
	bool RetryBindingRequest();

	void SetBindingLifecycleState(EQuartzUIBindingComponentLifecycleState NewState);
	EQuartzUIBindingComponentLifecycleState GetBindingLifecycleState() const
	{
		return LifecycleState;
	}

	/** Fails closed, releases any partial binding, and broadcasts through the derived API. */
	void FailBinding(FName ErrorCode);

	/** Re-enters retained-shell reconciliation after a bound scope detaches itself. */
	void RestartBindingAfterDetach();

	virtual bool ValidateBindingRequest(FName& OutError) const;
	virtual bool HasLiveBinding() const;
	virtual EQuartzUIBindingAttachResult AttachBinding(
		ULocalPlayer* LocalPlayer,
		UQuartzUIView* Shell,
		FName& OutError);
	virtual void ReleaseBinding();
	virtual void HandleBindingAttached();
	virtual void HandleBindingLifecycleStateChanged(
		EQuartzUIBindingComponentLifecycleState PreviousState,
		EQuartzUIBindingComponentLifecycleState NewState);
	virtual void HandleBindingFailure(FName ErrorCode);

private:
	EQuartzUIBindingAttachResult TryAttach();
	bool HandleRetryTick(float DeltaSeconds);
	void StartRetryTicker();
	void StopRetryTicker();

	FTSTicker::FDelegateHandle RetryTicker;
	EQuartzUIBindingComponentLifecycleState LifecycleState =
		EQuartzUIBindingComponentLifecycleState::Inactive;
	FName LastFailure;
	bool bBindingRequested = false;
};