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

# QuartzUIProjectSettings: 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/QuartzUIProjectSettings.h`) · [integration recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) · [practical guide](https://betterbuilt.games/docs/quartz-ui/first-ui)

## EQuartzUIStartupPolicy

**Internal type.** Whether the canonical shell is started by a later host adapter or explicitly by game code.

**Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIProjectSettings recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Select DefaultApp and Manual startup, then Start UI Shell. Config=Game; saved in project defaults.

**Avoid:** Putting Node paths or secrets into shared runtime policy. 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/QuartzUIProjectSettings.h#L19`)

## EQuartzUINativeFallbackPolicy

**Internal type.** Native presentation used when Chromium is unavailable or terminally failed.

**Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIProjectSettings recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Select DefaultApp and Manual startup, then Start UI Shell. Config=Game; saved in project defaults.

**Avoid:** Putting Node paths or secrets into shared runtime policy. 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/QuartzUIProjectSettings.h#L27`)

## EQuartzUICookPolicy

**Internal type.** Version-one packaging contract. Unknown values fail validation.

**Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIProjectSettings recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Select DefaultApp and Manual startup, then Start UI Shell. Config=Game; saved in project defaults.

**Avoid:** Putting Node paths or secrets into shared runtime policy. 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/QuartzUIProjectSettings.h#L35`)

## EQuartzUISecurityPolicy

**Internal type.** Compiled Shipping boundary. Per-app assets cannot override this policy.

**Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIProjectSettings recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Select DefaultApp and Manual startup, then Start UI Shell. Config=Game; saved in project defaults.

**Avoid:** Putting Node paths or secrets into shared runtime policy. 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/QuartzUIProjectSettings.h#L42`)

## UQuartzUIProjectSettings

**Public type.** Shareable runtime policy shown at Project Settings > Plugins > QuartzUI. Machine-local Node, Vite, and DevTools preferences remain in UQuartzUIEditorSettings (EditorPerProjectUserSettings).

**Prerequisites / integration:** Compatible C++ Unreal 5.8 Win64 host, installed plugin and host-owned app files. Use the [QuartzUIProjectSettings recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiprojectsettings) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Select DefaultApp and Manual startup, then Start UI Shell. Config=Game; saved in project defaults.

**Avoid:** Putting Node paths or secrets into shared runtime policy. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIProjectSettings.h#L53`)

## 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/DeveloperSettings.h"
#include "QuartzUIApp.h"
#include "QuartzUIInput.h"
#include "QuartzUILoadRecovery.h"
#include "QuartzUIReadiness.h"

#include "QuartzUIProjectSettings.generated.h"

class UStringTable;
class UUserWidget;
class UQuartzUISoundHandler;
class UQuartzUISoundSet;

/** Whether the canonical shell is started by a later host adapter or explicitly by game code. */
UENUM(BlueprintType)
enum class EQuartzUIStartupPolicy : uint8
{
	Manual,
	Automatic
};

/** Native presentation used when Chromium is unavailable or terminally failed. */
UENUM(BlueprintType)
enum class EQuartzUINativeFallbackPolicy : uint8
{
	BuiltIn,
	ProjectWidget
};

/** Version-one packaging contract. Unknown values fail validation. */
UENUM(BlueprintType)
enum class EQuartzUICookPolicy : uint8
{
	UFSOnly
};

/** Compiled Shipping boundary. Per-app assets cannot override this policy. */
UENUM(BlueprintType)
enum class EQuartzUISecurityPolicy : uint8
{
	LockedDown
};

/**
 * Shareable runtime policy shown at Project Settings > Plugins > QuartzUI.
 * Machine-local Node, Vite, and DevTools preferences remain in
 * UQuartzUIEditorSettings (EditorPerProjectUserSettings).
 */
UCLASS(Config = Game, DefaultConfig, meta = (DisplayName = "QuartzUI"))
class QUARTZUIRUNTIME_API UQuartzUIProjectSettings final : public UDeveloperSettings
{
	GENERATED_BODY()

public:
	static const UQuartzUIProjectSettings* Get();

	virtual FName GetContainerName() const override { return TEXT("Project"); }
	virtual FName GetCategoryName() const override { return TEXT("Plugins"); }
	virtual FName GetSectionName() const override { return TEXT("QuartzUI"); }

	/** Canonical project-owned shell app. Empty is valid while startup is Manual. */
	UPROPERTY(Config, EditAnywhere, Category = "Default Shell", meta = (AllowedClasses = "/Script/QuartzUIRuntime.QuartzUIAppAsset"))
	TSoftObjectPtr<UQuartzUIAppAsset> DefaultApp;

	/** Additional advanced apps registered by project configuration. */
	UPROPERTY(Config, EditAnywhere, Category = "Default Shell", meta = (AllowedClasses = "/Script/QuartzUIRuntime.QuartzUIAppAsset"))
	TArray<TSoftObjectPtr<UQuartzUIAppAsset>> RegisteredApps;

	UPROPERTY(Config, EditAnywhere, Category = "Startup")
	EQuartzUIStartupPolicy StartupPolicy = EQuartzUIStartupPolicy::Manual;

	/** Initial client-side screen/route intent. */
	UPROPERTY(Config, EditAnywhere, Category = "Startup")
	FName DefaultScreen = TEXT("main-menu");

	/** Initial built-in layer used by the canonical shell host. */
	UPROPERTY(Config, EditAnywhere, Category = "Startup")
	FName StartupLayer = TEXT("quartzui.hud");

	UPROPERTY(Config, EditAnywhere, Category = "Startup", meta = (ClampMin = "-10000", ClampMax = "10000"))
	int32 ViewportZOrder = 1000;

	/** Project-relative frontend source root; never written beneath an installed plugin. */
	UPROPERTY(Config, EditAnywhere, Category = "Resource Roots")
	FString FrontendSourceRoot = TEXT("QuartzUI/Source");

	/** Project-relative compiled-output root. */
	UPROPERTY(Config, EditAnywhere, Category = "Resource Roots")
	FString FrontendBuildRoot = TEXT("QuartzUI/Build");

	/** Fixed project Content-relative production app parent for v1. */
	UPROPERTY(Config, EditAnywhere, Category = "Resource Roots")
	FString CookedAppRoot = TEXT("Content/QuartzUI/Apps");

	/** Optional Unreal String Table retained as localization authority. */
	UPROPERTY(Config, EditAnywhere, Category = "Localization")
	TSoftObjectPtr<UStringTable> LocalizationStringTable;

	/** Project-relative generated localization catalog root. */
	UPROPERTY(Config, EditAnywhere, Category = "Localization")
	FString GeneratedLocalizationRoot = TEXT("QuartzUI/Generated/Localization");

	/** BCP-47-style cultures compiled for the web shell. Empty defers to project localization settings. */
	UPROPERTY(Config, EditAnywhere, Category = "Localization")
	TArray<FString> SupportedCultures;

	/** Optional app used while the retained shell cannot present loading state. */
	UPROPERTY(Config, EditAnywhere, Category = "Loading and Fallback", meta = (AllowedClasses = "/Script/QuartzUIRuntime.QuartzUIAppAsset"))
	TSoftObjectPtr<UQuartzUIAppAsset> LoadingApp;

	UPROPERTY(Config, EditAnywhere, Category = "Loading and Fallback")
	EQuartzUINativeFallbackPolicy NativeFallbackPolicy = EQuartzUINativeFallbackPolicy::BuiltIn;

	/** Required only when NativeFallbackPolicy is ProjectWidget. */
	UPROPERTY(Config, EditAnywhere, Category = "Loading and Fallback", meta = (EditCondition = "NativeFallbackPolicy == EQuartzUINativeFallbackPolicy::ProjectWidget"))
	TSoftClassPtr<UUserWidget> NativeFallbackWidgetClass;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation", meta = (ClampMin = "0.75", ClampMax = "2.0"))
	float DefaultTextScale = 1.0f;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation")
	bool bDefaultReducedMotion = false;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation")
	bool bDefaultHighContrast = false;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation")
	bool bDefaultTransparency = true;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation")
	bool bDefaultTextSelection = false;

	UPROPERTY(Config, EditAnywhere, Category = "Presentation")
	bool bDefaultSceneBackdrop = true;

	UPROPERTY(Config, EditAnywhere, Category = "Input")
	FQuartzUIInputConfig DefaultInputConfig;

	/** Base semantic cue mapping for every local player's sound-set stack. */
	UPROPERTY(Config, EditAnywhere, Category = "Audio")
	TSoftObjectPtr<UQuartzUISoundSet> DefaultSoundSet;

	/** Project-wide backend used when a resolving sound set has no override. */
	UPROPERTY(Config, EditAnywhere, Category = "Audio")
	TSoftClassPtr<UQuartzUISoundHandler> DefaultSoundHandlerClass;

	UPROPERTY(Config, EditAnywhere, Category = "Performance", meta = (ClampMin = "1", ClampMax = "120"))
	int32 DefaultBrowserFrameRate = 60;

	UPROPERTY(Config, EditAnywhere, Category = "Performance", meta = (ClampMin = "1", ClampMax = "8"))
	int32 MaxViewsPerPlayer = 1;

	UPROPERTY(Config, EditAnywhere, Category = "Performance", meta = (ClampMin = "1", ClampMax = "16"))
	int32 MaxTotalViews = 4;

	UPROPERTY(Config, EditAnywhere, Category = "Performance", meta = (ClampMin = "100", ClampMax = "30000"))
	int32 MaxStartupMilliseconds = 5000;

	UPROPERTY(Config, EditAnywhere, Category = "Performance", meta = (ClampMin = "16", ClampMax = "2048"))
	int32 MaxSurfaceMemoryMiB = 256;

	UPROPERTY(Config, EditAnywhere, Category = "Recovery", meta = (ClampMin = "0", ClampMax = "8"))
	int32 DefaultMaxLoadRecoveryAttempts = FQuartzUILoadRecoveryPolicy::DefaultMaxAttempts;

	UPROPERTY(Config, EditAnywhere, Category = "Recovery", meta = (ClampMin = "0.1", ClampMax = "30.0"))
	float DefaultHandshakeTimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds;

	UPROPERTY(Config, EditAnywhere, Category = "Cooking")
	EQuartzUICookPolicy CookPolicy = EQuartzUICookPolicy::UFSOnly;

	/** Project-relative deterministic manifest output. */
	UPROPERTY(Config, EditAnywhere, Category = "Cooking")
	FString ManifestOutput = TEXT("Saved/QuartzUI/quartzui-staging-manifest.json");

	UPROPERTY(Config, EditAnywhere, Category = "Cooking")
	bool bRejectSourceMaps = true;

	UPROPERTY(Config, EditAnywhere, Category = "Cooking")
	bool bRequireCurrentContract = true;

	UPROPERTY(Config, EditAnywhere, Category = "Cooking")
	bool bRequireCurrentLocalization = true;

	UPROPERTY(Config, EditAnywhere, Category = "Diagnostics")
	bool bEnableRuntimeDiagnostics = true;

	/** Shipping validation rejects this even if configuration data is edited by hand. */
	UPROPERTY(Config, EditAnywhere, Category = "Diagnostics")
	bool bEnableVerboseShippingDiagnostics = false;

	/** Shareable permission; the machine-local editor setting still chooses whether to start DevTools. */
	UPROPERTY(Config, EditAnywhere, Category = "Secure Runtime Policy")
	bool bPermitEditorDevTools = true;

	/** Shareable permission; actual Node path, Vite port, and process ownership remain per-user. */
	UPROPERTY(Config, EditAnywhere, Category = "Secure Runtime Policy")
	bool bPermitEditorDevelopmentOrigins = true;

	UPROPERTY(Config, EditAnywhere, Category = "Secure Runtime Policy")
	EQuartzUISecurityPolicy ShippingSecurityPolicy = EQuartzUISecurityPolicy::LockedDown;

	/** Explicitly loads the configured default app, or returns null when none is selected. */
	UQuartzUIAppAsset* LoadDefaultAppAsset() const;

	/** C++ resolution path used by the canonical shell and validation service. */
	bool TryResolveAppDefinition(
		const UQuartzUIAppAsset* App,
		FQuartzUIAppDefinition& OutDefinition,
		FString& OutError) const;

#if WITH_EDITOR
	virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent) override;
#endif
};
```

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