--- title: "QuartzUIApp: declaration reference" description: "Quartz UI 0.57.0-dev: QuartzUIApp: declaration reference. Source-reviewed guidance, usage and limitations." status: approved visibility: public sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9 reviewedAt: 2026-09-24 --- # QuartzUIApp: 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/QuartzUIApp.h`) · [integration recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) · [practical guide](https://betterbuilt.games/docs/quartz-ui/first-ui) ## EQuartzUIAppResourceOwner **Public type.** Selects the immutable cooked root that owns an app's non-UAsset web files. **Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIApp recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) in the host module `QuartzUIRuntime`. **Minimal example / lifecycle:** Create DA_GameUI; choose Project, gameui, Apps/gameui, index.html. Asset persists in the host; runtime copies a normalized definition. **Avoid:** Leaving the fixture defaults or expecting overrides without switches. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems. Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIApp.h#L16`) ## FQuartzUIAppDefinition **Public type.** Native source of truth for one packaged web application entry point. **Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIApp recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) in the host module `QuartzUIRuntime`. **Minimal example / lifecycle:** Create DA_GameUI; choose Project, gameui, Apps/gameui, index.html. Asset persists in the host; runtime copies a normalized definition. **Avoid:** Leaving the fixture defaults or expecting overrides without switches. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems. Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIApp.h#L27`) ## FQuartzUIAppProjectOverrides **Public type.** Explicit per-app choices that override shareable project rendering defaults. **Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIApp recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) in the host module `QuartzUIRuntime`. **Minimal example / lifecycle:** Create DA_GameUI; choose Project, gameui, Apps/gameui, index.html. Asset persists in the host; runtime copies a normalized definition. **Avoid:** Leaving the fixture defaults or expecting overrides without switches. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems. Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIApp.h#L77`) ## FQuartzUIAppPolicy **Internal type.** Bounded validation shared by assets, runtime views, resource origins, and tests. **Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIApp recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) in the host module `QuartzUIRuntime`. **Minimal example / lifecycle:** Create DA_GameUI; choose Project, gameui, Apps/gameui, index.html. Asset persists in the host; runtime copies a normalized definition. **Avoid:** Leaving the fixture defaults or expecting overrides without switches. This named helper is runtime-owned; inspect/use it through the owner above rather than constructing it in gameplay. Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIApp.h#L101`) ## UQuartzUIAppAsset **Public type.** Project-authored Blueprint/C++ asset for a packaged app/view entry. **Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIApp recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiapp) in the host module `QuartzUIRuntime`. **Minimal example / lifecycle:** Create DA_GameUI; choose Project, gameui, Apps/gameui, index.html. Asset persists in the host; runtime copies a normalized definition. **Avoid:** Leaving the fixture defaults or expecting overrides without switches. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems. Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIApp.h#L137`) ## Complete header Source snapshot, not an additional example. Unreal annotations distinguish exposed Blueprint nodes from native-only/private methods. ```cpp #pragma once #include "CoreMinimal.h" #include "Engine/DataAsset.h" #include "QuartzUILoadRecovery.h" #include "QuartzUIReadiness.h" #include "QuartzUIApp.generated.h" class UQuartzUIProjectContractAsset; class UQuartzUIProvider; class UQuartzUIProviderSet; /** Selects the immutable cooked root that owns an app's non-UAsset web files. */ UENUM(BlueprintType) enum class EQuartzUIAppResourceOwner : uint8 { /** Compatibility-only product fixtures shipped inside QuartzUI. */ PluginFixture UMETA(DisplayName = "Plugin fixture"), /** Production files beneath the game's Content/QuartzUI directory. */ Project UMETA(DisplayName = "Project") }; /** Native source of truth for one packaged web application entry point. */ USTRUCT(BlueprintType) struct QUARTZUIRUNTIME_API FQuartzUIAppDefinition { GENERATED_BODY() /** Lowercase DNS label used as the isolated .quartzui.test origin. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App") FName AppId = TEXT("mvp"); /** Root owner. Production apps are project-owned; plugin ownership is reserved for fixtures. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App") EQuartzUIAppResourceOwner ResourceOwner = EQuartzUIAppResourceOwner::PluginFixture; /** Directory below the selected owner's cooked root. Empty selects that root. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App") FString PackagedRoot; /** HTML document below PackagedRoot opened for this view. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App") FString EntryPage = TEXT("index.html"); UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Rendering", meta = (ClampMin = "1", ClampMax = "120")) int32 BrowserFrameRate = 60; UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Rendering") bool bSupportsTransparency = true; UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Interaction") bool bAllowTextSelection = false; UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Rendering") bool bEnableSceneBackdrop = true; UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery", meta = (ClampMin = "0", ClampMax = "8")) int32 MaxLoadRecoveryAttempts = FQuartzUILoadRecoveryPolicy::DefaultMaxAttempts; /** * Shows the native full-surface recovery panel when this view fails. * Optional passive overlays can disable it to fail transparent while still * reporting failure through the normal view lifecycle and diagnostics. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery") bool bShowLoadRecoveryUI = true; /** Bounded wait after document load for the generated native/JavaScript contract handshake. */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery", meta = (ClampMin = "0.1", ClampMax = "30.0")) float HandshakeTimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds; }; /** Explicit per-app choices that override shareable project rendering defaults. */ USTRUCT(BlueprintType) struct QUARTZUIRUNTIME_API FQuartzUIAppProjectOverrides { GENERATED_BODY() UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideBrowserFrameRate = false; UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideTransparency = false; UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideTextSelection = false; UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideSceneBackdrop = false; UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideLoadRecoveryAttempts = false; UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") bool bOverrideHandshakeTimeout = false; }; /** Bounded validation shared by assets, runtime views, resource origins, and tests. */ class QUARTZUIRUNTIME_API FQuartzUIAppPolicy final { public: static constexpr int32 MaxRegisteredApps = 64; static constexpr int32 MaxRelativePathLength = 512; /** * Returns the lowercase wire/path representation of an app ID. * * FName comparisons are case-insensitive and ToString() can inherit the * display casing of an earlier name in the process. App origins and cooked * paths must never depend on that process-global display casing. */ static FString GetCanonicalAppId(FName AppId); static bool IsValidAppId(FName AppId); static bool TryNormalizeDefinition( const FQuartzUIAppDefinition& Definition, FQuartzUIAppDefinition& OutNormalized, FString& OutError); static bool TryBuildResourcePath( const FString& PackagedRoot, const FString& RelativePath, FString& OutResourcePath, FString& OutError); static FQuartzUIAppDefinition MakeLegacyDefinition(FName AppId); private: static bool TryNormalizeRelativePath( const FString& Value, bool bAllowEmpty, FString& OutNormalized, FString& OutError); }; /** Project-authored Blueprint/C++ asset for a packaged app/view entry. */ UCLASS(BlueprintType) class QUARTZUIRUNTIME_API UQuartzUIAppAsset final : public UDataAsset { GENERATED_BODY() public: UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|App") FQuartzUIAppDefinition Definition; /** * Selects which app-definition presentation/recovery fields beat project * defaults when this asset is resolved through UQuartzUIProjectSettings. * Identity, ownership, roots, and entry are always app-specific. Security * and cook invariants are never overrideable here. */ UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults") FQuartzUIAppProjectOverrides ProjectOverrides; /** * Explicit, ordered contract fragments used only by this app. Empty keeps * the immutable middleware core contract, including for loading/fixture apps. */ UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Contract", meta = (AllowedClasses = "/Script/QuartzUIRuntime.QuartzUIProjectContractAsset")) TArray> RegisteredProjectContracts; /** * Explicit data-facade classes for this app. Their supported UPROPERTY, * delegate, and UFUNCTION surface is generated automatically. */ UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Providers") TArray> RegisteredProviders; /** * Reusable provider collections participating in this app's exact contract * closure. OnShellReady sets are also instantiated for the canonical shell. */ UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Providers") TArray> RegisteredProviderSets; UFUNCTION(BlueprintPure, Category = "QuartzUI|App") bool IsDefinitionValid(FString& OutError) const; /** Cook-generated wire metadata, including stable reflected display names. */ UPROPERTY() TMap CookedContractMetadata; #if WITH_EDITOR private: virtual void PreSave(FObjectPreSaveContext SaveContext) override; virtual void CookAdditionalFilesOverride( const TCHAR* PackageFilename, const ITargetPlatform* TargetPlatform, TFunctionRef WriteAdditionalFile) override; #endif }; ``` Canonical HTML: https://betterbuilt.games/docs/quartz-ui/reference-quartzuiapp