QuartzUISubsystem: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "Containers/Ticker.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "QuartzUIProviderSet.h"
#include "QuartzUIView.h"

#include "QuartzUISubsystem.generated.h"

class ULocalPlayer;
class UQuartzUILayerHost;
class UQuartzUILayerStack;
class UQuartzUIProvider;
class SWidget;

struct FQuartzUIPlayerPresentation
{
	TWeakObjectPtr<ULocalPlayer> LocalPlayer;
	TWeakObjectPtr<UQuartzUILayerHost> Host;
	TSharedPtr<SWidget> ViewportWidget;
	int32 ZOrder = 0;
};

USTRUCT()
struct FQuartzUIProviderSetBindingRecord
{
	GENERATED_BODY()

	UPROPERTY(Transient)
	TObjectPtr<ULocalPlayer> LocalPlayer;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIView> View;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUIProvider>> Providers;

	bool bAutomatic = false;
};

/** Client-only owner and lookup boundary for logical QuartzUI views. */
UCLASS()
class QUARTZUIRUNTIME_API UQuartzUISubsystem final : public UGameInstanceSubsystem
{
	GENERATED_BODY()

public:
	virtual bool ShouldCreateSubsystem(UObject* Outer) const override;
	virtual void Initialize(FSubsystemCollectionBase& Collection) override;
	virtual void Deinitialize() override;

	/** Creates a view from an explicit validated native/Blueprint descriptor. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	UQuartzUIView* CreateConfiguredView(
		const FQuartzUIAppDefinition& Definition,
		ULocalPlayer* OwningLocalPlayer);

	/** Asset convenience wrapper for CreateConfiguredView. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	UQuartzUIView* CreateAppView(const UQuartzUIAppAsset* App, ULocalPlayer* OwningLocalPlayer);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	bool CloseView(UQuartzUIView* View);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	void CloseAllViews();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Views")
	UQuartzUIView* FindView(FGuid ViewId) const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Views")
	TArray<UQuartzUIView*> GetViewsForLocalPlayer(ULocalPlayer* LocalPlayer) const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Views")
	int32 GetViewCount() const { return Views.Num(); }

	/**
	 * Starts or returns the one configured, retained shell for this exact local player.
	 * The logical shell remains subsystem-owned across map travel and host reconstruction.
	 */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Shell")
	UQuartzUIView* StartShell(ULocalPlayer* LocalPlayer);

	/** Explicitly closes the exact player's canonical shell without affecting advanced views. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Shell")
	bool StopShell(ULocalPlayer* LocalPlayer);

	/** Returns the exact player's canonical shell, or null when it has not been started. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Shell")
	UQuartzUIView* GetShell(ULocalPlayer* LocalPlayer) const;

	/** True only after the shell document and matching contract handshake are ready. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Shell")
	bool IsShellReady(ULocalPlayer* LocalPlayer) const;

	/** Stable startup/view failure for the exact player's shell; empty when no failure exists. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Shell")
	FString GetShellFailure(ULocalPlayer* LocalPlayer) const;

	/** Instantiates one registered set for the exact player's canonical shell. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Providers")
	FQuartzUIProviderSetHandle BindProviderSet(
		ULocalPlayer* LocalPlayer,
		const UQuartzUIProviderSet* ProviderSet);

	/** Releases exactly the providers owned by a prior manual set binding. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Providers")
	bool ReleaseProviderSet(FQuartzUIProviderSetHandle Handle);

	/** Number of local-player CEF request contexts owned by this client game instance. */
	int32 GetBrowserContextCount() const { return BrowserContextIds.Num(); }

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Layers")
	UQuartzUILayerStack* GetOrCreateLayerStack(ULocalPlayer* LocalPlayer);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Layers")
	UQuartzUILayerStack* FindLayerStack(ULocalPlayer* LocalPlayer) const;

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Layers")
	UQuartzUIView* PushConfiguredView(
		const FQuartzUIAppDefinition& Definition,
		FName LayerId,
		ULocalPlayer* OwningLocalPlayer);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Layers")
	UQuartzUIView* PushAppView(
		const UQuartzUIAppAsset* App,
		FName LayerId,
		ULocalPlayer* OwningLocalPlayer);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Layers")
	bool HandleBack(ULocalPlayer* LocalPlayer);

	/** Mounts one layer host through Unreal's exact per-player viewport layer. */
	UQuartzUILayerHost* MountPlayerUI(ULocalPlayer* LocalPlayer, int32 ZOrder = 1000);

	bool UnmountPlayerUI(ULocalPlayer* LocalPlayer);

	UQuartzUILayerHost* GetMountedPlayerHost(ULocalPlayer* LocalPlayer) const;

	/** Releases views, layers, presentation, and browser storage for one departing player. */
	bool ShutdownPlayerUI(ULocalPlayer* LocalPlayer);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	bool SuspendView(UQuartzUIView* View);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Views")
	bool ResumeView(UQuartzUIView* View);

	/** Native presentation-host notifications. */
	bool NotifyViewLoading(UQuartzUIView* View);
	bool NotifyViewReady(UQuartzUIView* View);
	bool NotifyViewFailed(UQuartzUIView* View, const FString& Reason);

private:
#if WITH_DEV_AUTOMATION_TESTS
	friend class FQuartzUIShellAutomaticStartupTest;
#endif
	UQuartzUIView* CreateResolvedView(
		const FQuartzUIAppDefinition& Definition,
		ULocalPlayer* OwningLocalPlayer,
		const UQuartzUIAppAsset* ContractApp);
	bool OwnsView(const UQuartzUIView* View) const;
	bool OwnsLocalPlayer(const ULocalPlayer* LocalPlayer, bool bAllowRemovedPlayer = false) const;
	FString GetOrCreateBrowserContextId(ULocalPlayer* LocalPlayer);
	void UnregisterBrowserContext(const FString& ContextId);
	void HandleLocalPlayerAdded(ULocalPlayer* LocalPlayer);
	void StartAutomaticShell(ULocalPlayer* LocalPlayer);
	bool RetryAutomaticShells(float DeltaSeconds);
	void HandleLocalPlayerRemoved(ULocalPlayer* LocalPlayer);
	void NotifyPlayerTopologyChanged();
	void SetShellStartupFailure(ULocalPlayer* LocalPlayer, const FString& FailureCode);
	void ClearShellRegistration(UQuartzUIView* View);
	bool BindAutomaticProviderSets(
		ULocalPlayer* LocalPlayer,
		UQuartzUIView* View,
		const UQuartzUIAppAsset* App);
	FQuartzUIProviderSetHandle BindProviderClasses(
		ULocalPlayer* LocalPlayer,
		UQuartzUIView* View,
		const TArray<UClass*>& ProviderClasses,
		bool bAutomatic,
		FName& OutError);
	void ReleaseProviderSetBindingsForView(UQuartzUIView* View);

	UPROPERTY(Transient)
	TMap<FGuid, TObjectPtr<UQuartzUIView>> Views;

	UPROPERTY(Transient)
	TArray<FGuid> ViewOrder;

	/** Strong subsystem ownership of one canonical shell per exact local player. */
	UPROPERTY(Transient)
	TMap<TObjectPtr<ULocalPlayer>, TObjectPtr<UQuartzUIView>> PlayerShells;

	/** Failures that occur before a logical view exists (for example missing settings). */
	UPROPERTY(Transient)
	TMap<TObjectPtr<ULocalPlayer>, FString> ShellStartupFailures;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUILayerStack>> LayerStacks;

	UPROPERTY(Transient)
	TMap<TObjectPtr<ULocalPlayer>, FString> BrowserContextIds;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUILayerHost>> MountedPlayerHosts;

	UPROPERTY(Transient)
	TMap<FGuid, FQuartzUIProviderSetBindingRecord> ProviderSetBindings;

	TArray<FQuartzUIPlayerPresentation> MountedPlayerPresentations;
	TSet<TWeakObjectPtr<ULocalPlayer>> PendingAutomaticShellPlayers;
	FTSTicker::FDelegateHandle AutomaticShellTicker;
	FDelegateHandle LocalPlayerAddedHandle;
	FDelegateHandle LocalPlayerRemovedHandle;
};