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

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

## FQuartzUIMotionStateContract

**Public type.** Exact local-player motion snapshot published as quartzui.motion. Values are presentation-ready so every browser component uses one coherent camera response instead of independently sampling, smoothing, and shaking. Wire role: payload of `quartzui.motion` (state).

**Prerequisites / integration:** Exact-player view plus native asset/source ownership; GAS additionally requires GameplayAbilities. Use the [QuartzUIMotionComponent recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuimotioncomponent) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** `client.subscribeState('quartzui.motion', value => { /* read this DTO */ })`. Tick belongs to component; EndPlay clears state.

**Avoid:** Expecting component to start shell or automatically implement reduced-motion UI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIMotionComponent.h#L15`)

## UQuartzUIMotionComponent

**Public type.** Optional PlayerController component that owns camera-driven UI perspective, inertial offset, and transient shake for one exact local player.

**Prerequisites / integration:** Exact-player view plus native asset/source ownership; GAS additionally requires GameplayAbilities. Use the [QuartzUIMotionComponent recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuimotioncomponent) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Add to local PlayerController; AddMotionImpulse; subscribe quartzui.motion. Tick belongs to component; EndPlay clears state.

**Avoid:** Expecting component to start shell or automatically implement reduced-motion UI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIMotionComponent.h#L59`)

## 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 "Components/ActorComponent.h"

#include "QuartzUIMotionComponent.generated.h"

/**
 * Exact local-player motion snapshot published as quartzui.motion.
 *
 * Values are presentation-ready so every browser component uses one coherent
 * camera response instead of independently sampling, smoothing, and shaking.
 */
USTRUCT(BlueprintType, meta = (QuartzUITypeName = "QuartzUIMotionState"))
struct QUARTZUIRUNTIME_API FQuartzUIMotionStateContract
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "enabled"))
	bool bEnabled = true;

	/** Final local-player camera yaw normalized to [0, 360) for retained compass bindings. */
	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "headingDegrees"))
	float HeadingDegrees = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "tiltX"))
	float TiltX = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "tiltY"))
	float TiltY = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "roll"))
	float Roll = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "offsetX"))
	float OffsetX = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "offsetY"))
	float OffsetY = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "shakeX"))
	float ShakeX = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "shakeY"))
	float ShakeY = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "intensity"))
	float Intensity = 0.0f;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Motion", meta = (QuartzUIName = "revision"))
	int32 Revision = 0;
};

/**
 * Optional PlayerController component that owns camera-driven UI perspective,
 * inertial offset, and transient shake for one exact local player.
 */
UCLASS(Blueprintable, ClassGroup = (QuartzUI), meta = (BlueprintSpawnableComponent, DisplayName = "QuartzUI Motion"))
class QUARTZUIRUNTIME_API UQuartzUIMotionComponent : public UActorComponent
{
	GENERATED_BODY()

public:
	UQuartzUIMotionComponent();

	/** Adds a screen-space shake impulse. Direction is normalized when non-zero. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Motion")
	void AddMotionImpulse(FVector2D ScreenDirection, float Strength = 1.0f);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Motion")
	void SetMotionEffectsEnabled(bool bEnabled);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Motion")
	bool AreMotionEffectsEnabled() const { return bMotionEffectsEnabled; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Motion")
	FQuartzUIMotionStateContract GetMotionState() const { return MotionState; }

	/** Publishes the current retained snapshot immediately when a shell exists. */
	bool PublishMotionState();

protected:
	virtual void BeginPlay() override;
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;
	virtual void TickComponent(
		float DeltaTime,
		ELevelTick TickType,
		FActorComponentTickFunction* ThisTickFunction) override;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion")
	bool bMotionEffectsEnabled = true;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "1.0", ClampMax = "60.0"))
	float PublishRateHz = 60.0f;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "0.0", ClampMax = "10.0"))
	float Response = 7.5f;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "0.0", ClampMax = "8.0"))
	float MaximumTiltDegrees = 2.2f;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "0.0", ClampMax = "48.0"))
	float MaximumOffsetPixels = 12.0f;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "0.0", ClampMax = "48.0"))
	float MaximumShakePixels = 8.0f;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Motion", meta = (ClampMin = "0.1", ClampMax = "12.0"))
	float TraumaDecay = 3.2f;

private:
	class APlayerController* ResolveLocalPlayerController() const;
	void ResetSamples();
	void UpdateMotion(float DeltaTime);
	void ClearMotionState(bool bEnabled);

	UPROPERTY(Transient)
	FQuartzUIMotionStateContract MotionState;

	FRotator PreviousCameraRotation = FRotator::ZeroRotator;
	FVector PreviousCameraLocation = FVector::ZeroVector;
	FVector PreviousCameraVelocity = FVector::ZeroVector;
	FVector SmoothedAngularVelocity = FVector::ZeroVector;
	FVector2D ImpulseDirection = FVector2D(0.8f, -0.6f);
	float Trauma = 0.0f;
	float ImpulsePhase = 0.0f;
	float PublishAccumulator = 0.0f;
	bool bHasCameraSample = false;
	bool bHasVelocitySample = false;
};
```

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