---
title: "QuartzUIBindingComponentBase: declaration reference"
description: "Quartz UI 0.57.0-dev: QuartzUIBindingComponentBase: declaration reference. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# QuartzUIBindingComponentBase: declaration reference

> **0.57.0-dev · beta source documentation.** Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See [validation and limits](https://betterbuilt.games/docs/quartz-ui/evidence).

Pinned source (source: `Source/QuartzUIRuntime/Public/QuartzUIBindingComponentBase.h`) · [integration recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuibindingcomponentbase) · [practical guide](https://betterbuilt.games/docs/quartz-ui/providers-contracts)

## EQuartzUIBindingComponentLifecycleState

**Advanced type.** Shared, native-only lifecycle used by feature-owned QuartzUI binding components.

**Prerequisites / integration:** Configured app, explicit reflected value types, saved assets and freshly generated app contract. Use the [QuartzUIBindingComponentBase recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuibindingcomponentbase) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Derive through provider/GAS component for ordinary integrations. Component owns player/source retry subscriptions.

**Avoid:** Starting unbounded retries or resolving the first world player. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIBindingComponentBase.h#L13`)

## EQuartzUIBindingAttachResult

**Advanced type.** Result of a derived component's exact-player shell attachment attempt.

**Prerequisites / integration:** Configured app, explicit reflected value types, saved assets and freshly generated app contract. Use the [QuartzUIBindingComponentBase recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuibindingcomponentbase) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Derive through provider/GAS component for ordinary integrations. Component owns player/source retry subscriptions.

**Avoid:** Starting unbounded retries or resolving the first world player. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIBindingComponentBase.h#L24`)

## UQuartzUIBindingComponentBase

**Advanced type.** Common exact-player resolution, retained-shell startup, retry, failure, and teardown machinery for feature-owned QuartzUI binding components.

**Prerequisites / integration:** Configured app, explicit reflected value types, saved assets and freshly generated app contract. Use the [QuartzUIBindingComponentBase recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuibindingcomponentbase) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Derive through provider/GAS component for ordinary integrations. Component owns player/source retry subscriptions.

**Avoid:** Starting unbounded retries or resolving the first world player. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIBindingComponentBase.h#L36`)

## Complete header

Source snapshot, not an additional example. Unreal annotations distinguish exposed Blueprint nodes from native-only/private methods.

```cpp
#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;
};
```

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/reference-quartzuibindingcomponentbase