QuartzUIProtocol: 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.

Pinned source (source: Source/QuartzUIRuntime/Public/QuartzUIProtocol.h) · integration recipe · practical guide

EQuartzUIProtocolError

Internal type. Protocol Error: a declared type in version-one envelopes, strict parsing, serialization and stable errors; use its exact fields/operations below.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L8)

FQuartzUIRequestEnvelope

Internal type. Validated web-to-Unreal protocol-v1 request.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L26)

FQuartzUIResponseEnvelope

Internal type. Protocol-v1 response returned through the JavaScript Promise transport.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L43)

FQuartzUIProtocolResult

Internal type. Protocol Result: a declared type in version-one envelopes, strict parsing, serialization and stable errors; use its exact fields/operations below.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L66)

EQuartzUIOutboundMessageType

Internal type. Outbound Message Type: a declared type in version-one envelopes, strict parsing, serialization and stable errors; use its exact fields/operations below.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L75)

FQuartzUIOutboundEnvelope

Internal type. Validated Unreal-to-web state snapshot or transient event.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L83)

FQuartzUIProtocolV1

Internal type. Framework-neutral, bounded JSON wire contract shared by the future bridge and tests.

Prerequisites / integration: Exact local player and configured app; Slate/UMG dependencies for native presentation work. Use the QuartzUIProtocol recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use QuartzUIClient.request rather than constructing raw envelopes. Bounded per-message values; request IDs/session correlate responses.

Avoid: Unknown fields, oversized payloads, non-object payloads. 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/QuartzUIProtocol.h#L101)

Complete header

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

#pragma once

#include "CoreMinimal.h"

#include "QuartzUIProtocol.generated.h"

UENUM(BlueprintType)
enum class EQuartzUIProtocolError : uint8
{
	None,
	EmptyEnvelope,
	EnvelopeTooLarge,
	MalformedJson,
	RootNotObject,
	UnknownField,
	MissingField,
	UnsupportedVersion,
	UnsupportedType,
	InvalidCorrelationId,
	InvalidName,
	InvalidPayload
};

/** Validated web-to-Unreal protocol-v1 request. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIRequestEnvelope
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString CorrelationId;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString Name;

	/** Condensed JSON object retained until an explicitly registered endpoint validates its schema. */
	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString PayloadJson;
};

/** Protocol-v1 response returned through the JavaScript Promise transport. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIResponseEnvelope
{
	GENERATED_BODY()

	/** Empty only when malformed input did not provide a trustworthy request ID. */
	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString CorrelationId;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	bool bSuccess = false;

	/** Condensed object payload emitted only for successful responses. */
	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString PayloadJson = TEXT("{}");

	/** Lowercase dotted stable code emitted only for failed responses. */
	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString ErrorCode;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString ErrorMessage;
};

struct QUARTZUIRUNTIME_API FQuartzUIProtocolResult
{
	EQuartzUIProtocolError Error = EQuartzUIProtocolError::None;
	FString Details;

	bool IsSuccess() const { return Error == EQuartzUIProtocolError::None; }
};

UENUM(BlueprintType)
enum class EQuartzUIOutboundMessageType : uint8
{
	State,
	Event
};

/** Validated Unreal-to-web state snapshot or transient event. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIOutboundEnvelope
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	EQuartzUIOutboundMessageType Type = EQuartzUIOutboundMessageType::State;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString Name;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	int64 Sequence = 0;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Protocol")
	FString PayloadJson = TEXT("{}");
};

/** Framework-neutral, bounded JSON wire contract shared by the future bridge and tests. */
class QUARTZUIRUNTIME_API FQuartzUIProtocolV1 final
{
public:
	static constexpr int32 Version = 1;
	static constexpr int32 MaxEnvelopeBytes = 256 * 1024;
	static constexpr int32 MaxStatePatchEntries = 128;
	static constexpr int32 MaxCorrelationIdLength = 64;
	static constexpr int32 MaxMessageNameLength = 128;
	static constexpr int32 MaxErrorMessageLength = 512;

	static bool TryParseRequest(
		const FString& Json,
		FQuartzUIRequestEnvelope& OutEnvelope,
		FQuartzUIProtocolResult& OutResult);

	static bool TrySerializeRequest(
		const FQuartzUIRequestEnvelope& Envelope,
		FString& OutJson,
		FQuartzUIProtocolResult& OutResult);

	static bool TrySerializeResponse(
		const FQuartzUIResponseEnvelope& Envelope,
		FString& OutJson,
		FQuartzUIProtocolResult& OutResult);

	static bool TrySerializeOutbound(
		const FQuartzUIOutboundEnvelope& Envelope,
		FString& OutJson,
		FQuartzUIProtocolResult& OutResult);

	/** Serializes one bounded set of unique named object states as a single wire patch. */
	static bool TrySerializeStatePatch(
		const TArray<FQuartzUIOutboundEnvelope>& States,
		int64 Sequence,
		FString& OutJson,
		FQuartzUIProtocolResult& OutResult);

	/** Shared validator for endpoint registration and protocol parsing. */
	static bool IsValidMessageName(const FString& Value);

	/** Stable wire code for a request validation error. */
	static FString GetErrorCode(EQuartzUIProtocolError Error);
};