치킨 날다

Common UI, UMG ViewModel 플러그인을 근 2달 가량 RnD 한 후기를 두서없이 간략하게 남겨봅니다.

Common UI

• 멀티 플랫폼, 멀티 컨트롤러에 대해 크게 강조를 하였지만 실상은 그다지 효과적이지는 않음.
• 물론 PC-콘솔 멀티 플랫폼에서는 할만 함.
• 하지만 모바일이 들어가면 답이 없어 짐.
• Common UI가 소개하는 기능 대부분이 InputAction을 UI에 Bind하는 것.
• 아직 UI Event에 InputAction Bind는 제대로 동작 안함.
• 게다가 UI의 Focus를 강력하게 체크하는데 모바일은 특성 상 UI의 터치, 드래그 등의 조작이 빈번함.
• 이것저것 편의 기능을 만들었지만 아직 실무에서 활용하기에는 부족함이 큼.

UMG ViewModel

• ViewModel의 근간이 되는 FieldNotify는 UE5 순정 기능.
• MVVMViewModelBase에 선언 된 매크로와 SetProperty 템플릿 함수만 따로 분리해서 사용하는 것도 충분히 좋음.
• ViewModel Creation 방식이 제한적임.
• 가장 무난하게 사용 가능한게 Global Context, 그 다음이 Manual.
• Resolve, Property Path는 구현이 덜 되었거나 제대로 분석이 안되어 사용 불가.
• Creation은 사용 가능하나 현실적인 이유로 사용 불가.
• 현실적인 이유: ViewModel을 BP로 안 만든다.
• UMG ViewModel의 Bind가 BP에서 이루어 지지만, Model과 View의 중간자인 만큼 생성과 데이터 입력은 코드에서 일어날 가능성이 높음.
• 그런데 Native Class에서 선언한 ViewModel 변수를 Bind 받지 못함.
• BP 함수로 Set을 명시적으로 해줘야 함.
• 이 지점에서 일단 사용성이 기대한 것만큼 안 나옴.
• 여기에 ViewModel이 모두 UObject이므로 LifeCycle을 조절해줘야 함.
• 이 부분이 ViewModel을 순정으로 사용 못하고 상당한 별도의 아키텍쳐 설계를 요구함.
• 즉, 어느정도 Utility가 있어야 사용 가능함.

사실 2가지를 모두 섞어서 쓰다가 Common UI는 아직 시기상조이지만 UMG ViewModel은 편의기능만 만들면 쓰기 좋겠다 싶었습니다.

특히 개발자 입장에서는 View에 해당하는 Native C++ 작업을 ViewModel 작업으로 대체.

ViewModel이 제공하는 정보의 종류만 공유가 되면 아티스트와 완전한 병행 작업이 가능하기 때문에 꼭 쓰고 싶었습니다.

하지만 한국에서는 아직 대다수의 구성원들이 업무를 좁게 해석하더군요.

디자이너들도 BP 작업을 완강히 거절하였고, 아티스트도 시각디자인이 아닌 작업을 할 이유를 못 찾겠다 하네요....

혹 이 Plugin에 관심을 가지시는 분들이 계시다면 지나가면서 살짝 보시고 RnD 해보시기 바랍니다.

Common UI의 사용 여부 판단

• 주로 다음 상황에서 Common UI 사용이 권장된다.
  • 복잡한 Multiple Layer UI를 제공해야 하는 경우
  • Cross-Platform을 지원하는 경우
• 반대로 이 두 케이스에 모두 해당되지 않으면 Common UI를 사용하지 않아도 무방하다.
  • RTS 게임
• 이와 별개로, WidgetComponent를 사용하여 배치된 Widget은 가급적 Common UI 사용을 지양하는 것이 좋다.
  • 여기서 WidgetComponent라 함은 3D 월드 상에 표기되는 Widget들을 지칭한다.
    • 캐릭터 닉네임, 체력바, 상태 등등
  • Common UI는 Cursor-Focus Search, Activate Order, Paint Order(LayerID)에 의존한다.
  • 때문에 2D 게임 HUD도 처리 할 수는 있지만, Game World에 배치 된 Widget과 함께 작동하지는 않는다.

Keyboard와 Mouse 입력을 동시에 처리하는 방법

• 일반적으로 Common UI는 Mouse와 Keyboard의 입력을 동시에 지원하지는 않는다.
  • 이를 동시에 지원하게 되면 UI 입장에서는 Mouse가 2개인 것처럼 느껴진다.

• 가장 간단한 방법은 입력을 Toggle로 관리하는 것이다.
  • 보편적인 상황에서는 Keyboard Input으로 메뉴를 띄운다.
  • 특정 키를 입력하고 있으면 Mouse Cursor가 노출된다.
    • 이 때, 모든 키보드 입력은 막히게 된다.
  • Mouse Cursor가 노출되고 있는 동안에는 마우스 커서만으로 입력을 받는다.

UI 성능에 영향을 미치는 Tick이나 일시정지를 우회하는 방법

• Common UI는 LocalPlayerSubsystem으로 동작하여 게임이 일시정지 하면 Tick이 되지 않는다.
  • Tick이 멈추면 CommonBoundActionBar를 포함한 Common UI가 동작하지 않는다.
• 이를 우회하려면 관련 Actor와 Widget에 tickable when paused 옵션을 활성화 해야 한다.
  • UI의 의도된 기능이나 퍼포먼스와 상충되지 않는지 확인 후 작업하자.

KeyHandler Method에서 Analog Input을 얻게 되는 이유

• 현재 InputKey/InputAxis는 PlayerController 단위에서 작업이 통합되어 있다.
  • 이는 가짜 Input 추가를 쉽게 하고, Input Parameter를 하나로 묶어 쉽게 업데이트 하기 위함이다.
• UE5 이전의 코드가 있으면 Analog Input이 Key Handler Callback을 트리거하거나, 반대로 트리거 될 수 있다.
  • Common UI는 이러한 기능으로부터 영향을 받지 않도록 하는 작업이 필요하다.
• 하지만 Input Pipeline 초기에 디버깅 중이라면, 이러한 교차 Trigger는 쉽게 발견할 수 있다.
  • 예를 들어 FCommonAnalogCursor는 Input Processor이므로 Input Pipeline 초기 부분과 상호작용한다.
  • 이 때문에 FCommonAnalogCursor::HandleKeyDownEvent에서 Corss Trigger 현상이 발생할 수 있다.

Input Mode가 Menu일 때 Game Input을 받을 수 있는 이유

bool UCommonUIActionRouterBase::CanProcessNormalGameInput() const
{
	if (GetActiveInputMode() == ECommonInputMode::Menu)
	{
		// We still process normal game input in menu mode if the game viewport has mouse capture
		// This allows manipulation of preview items and characters in the world while in menus. 
		// If this is not desired, disable viewport mouse capture in your desired input config.
		const ULocalPlayer& LocalPlayer = *GetLocalPlayerChecked();
		if (TSharedPtr<FSlateUser> SlateUser = FSlateApplication::Get().GetUser(GetLocalPlayerIndex()))
		{
			return LocalPlayer.ViewportClient && SlateUser->DoesWidgetHaveCursorCapture(LocalPlayer.ViewportClient->GetGameViewportWidget());
		}
	}
	return true;
}

• 이 함수로 인해 Game Viewport에 Mouse Capture가 있으면 Menu Mode에서의 Game Input이 가능하다.
  • 이 때문에 Menu에 있을 때 World 내 Preview Item과 Character를 조작할 수 있다.
• 만약 Game Input을 받고 싶지 않다면 원하는 InputMode에서 Mouse Capture를 비활성화 하면 된다.

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/commonui-input-technical-guide-for-unreal-engine

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/input-fundamentals-for-commonui-in-unreal-engine

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/using-commonui-with-enhnaced-input-in-unreal-engine

• CommonUI의 Input System은 Cross-Platform을 대응할 뿐 아니라 복잡한 다중 Layer Menu 관리에도 용이하다.
• 아래 내용은 Common UI Input System의 작동 방식에 대한 내용이다.

Gamepad Navigation using Synthetic Cursor

• Common UI에서 Gamepad Input은 보이지 않는 Synthetic Cursor를 기반으로 동작한다.
  • 때문에 Mouse를 사용하도록 UI를 설정할 경우, Common UI가 동작함에 있어 필요한 것은 2가지 뿐이다.
    • 보이지 않은 Cursor가 올바른 위치에 있을 것
    • Mouse와 같은 Click 입력을 받을 것.
  • 이 구조는 Cross-Platform에서의 모든 Input을 하나의 Input Path로 간소화 한다.

Click with Synthetic Cursor/Gamepad

• Gamepad의 Accept 혹은 Default Click을 한다고 가정하자.

• Virtual Accept Key는 대체로 EKeys::Virtual_Accept로 Mapping 된다.
• 내부적으로 Input Flow는 GenericApplication으로부터 파생된 Platform Application에서 시작된다.
  • 예를 들어 Windows의 경우 FWindowsApplication을 사용한다.

bool FSlateApplication::OnKeyDown( const int32 KeyCode, const uint32 CharacterCode, const bool IsRepeat ) 
{
	FKey const Key = FInputKeyManager::Get().GetKeyFromCodes( KeyCode, CharacterCode );
	FKeyEvent KeyEvent(Key, PlatformApplication->GetModifierKeys(), GetUserIndexForKeyboard(), IsRepeat, CharacterCode, KeyCode);

	return ProcessKeyDownEvent( KeyEvent );
}

• 이 Input은 FSlateApplication::ProcessKeyDownEvent로 처리가 된다.
  • ProcessKeyDownEvent는 Input 처리를 위해 IInputProcessor Interface를 Implement하고,
    가능하면 Input을 처리하는 Input Processor를 사용한다.
  • Input이 처리되면, 추가 Input 처리가 막히게 됩니다.

bool FSlateApplication::ProcessKeyDownEvent( const FKeyEvent& InKeyEvent )
{
/*...*/
	// Analog cursor gets first chance at the input
	if (InputPreProcessors.HandleKeyDownEvent(*this, InKeyEvent))
	{
		return true;
	}
/*...*/
}

• FCommonAnalogCursor는 FAnalogCursor와 마찬가지로 IInputProcessor의 구현체이다.
• FcommonAnalogCursor는 현재 Widget의 Bound Action으로 캡처되지 않은
  Gamepad의 표준 Accept Action Input을 처리하지 않는다.

bool FCommonAnalogCursor::HandleKeyDownEvent(FSlateApplication& SlateApp, const FKeyEvent& InKeyEvent)
{
	if (IsRelevantInput(InKeyEvent))
	{
/*....*/
		if (bIsVirtualAccept && ActionRouter.ProcessInput(InKeyEvent.GetKey(), InputEventType) == ERouteUIInputResult::Handled)
		{
			return true;
		}
		else if (!bIsVirtualAccept || ShouldVirtualAcceptSimulateMouseButton(InKeyEvent, IE_Pressed))
		{
			// There is no awareness on a mouse event of whether it's real or not, so mark that here.
			UCommonInputSubsystem& InputSubsytem = ActionRouter.GetInputSubsystem();
			InputSubsytem.SetIsGamepadSimulatedClick(bIsVirtualAccept);
			bool bReturnValue = FAnalogCursor::HandleKeyDownEvent(SlateApp, InKeyEvent);
/*....*/
		}
	}
	return false;
}

• 대신 Input을 HandleKeyDownEvent로 전달한다.

bool FAnalogCursor::HandleKeyDownEvent(FSlateApplication& SlateApp, const FKeyEvent& InKeyEvent)
{
	if (IsRelevantInput(InKeyEvent))
	{
		FKey Key = InKeyEvent.GetKey();
/*...*/

		// Bottom face button is a click
		if (Key == EKeys::Virtual_Accept)
		{
			if (!InKeyEvent.IsRepeat())
			{
				if (TSharedPtr<FSlateUser> SlateUser = SlateApp.GetUser(InKeyEvent))
				{
					const bool bIsPrimaryUser = FSlateApplication::CursorUserIndex == SlateUser->GetUserIndex();
					FPointerEvent MouseEvent(
						SlateUser->GetUserIndex(),
						FSlateApplication::CursorPointerIndex,
						SlateUser->GetCursorPosition(),
						SlateUser->GetPreviousCursorPosition(),
						bIsPrimaryUser ? SlateApp.GetPressedMouseButtons() : TSet<FKey>(),
						EKeys::LeftMouseButton,
						0,
						bIsPrimaryUser ? SlateApp.GetModifierKeys() : FModifierKeysState()
					);

					TSharedPtr<FGenericWindow> GenWindow;
					return SlateApp.ProcessMouseButtonDownEvent(GenWindow, MouseEvent);
				}
			}

			return true;
		}
	}

	return false;
}

• 이후, FSlateApplication에서 처리할 Synthetic Mouse Click Event를 생성한다.
• 여기까지 진행되면 Mouse Event는 Regular Click과 유사한 Input Process를 거치고, 최종 Click을 Trigger한다.
  • 좀 더 자세한 흐름을 보고 싶다면 SButton::OnMouseButtonDown에 중단점을 찍고 디버깅을 해보길 추천한다.

TroubleShooting

• Common UI의 Synthetic Cursor Click이 예상과 다른 경우, FPointerEvent의 문제일 가능성이 높다.
  • FPointEvent에서 올바른 User Input을 처리하지 않은 경우
  • Synthetic Cursor가 예상 위치와 멀리 떨어져 있는 경우
  • Click이 FSlateApplication::ProcessMouseButtonDownEvent에서 처리될 때
    Capture가 있는 다른 Widget이 FWidgetPath에 영향을 미친 경우
    • 이는 Input Config의 MouseCaptureMode를 기반으로 발생할 수 있다.
  • FWidgetPath가 FSlateApplication::LocateWindowUnerMouse를 사용하는 위치를 기반으로 자연 생성
    • FWidgetPath에는 Input이 Route되는 Widget List가 포함되어 있다.

How Synthetic Cursor/Gamdpad Navigate and Focus

• 단순 Navigation 측면에서는 Common UI와 UMG의 기본 구현 과정은 크게 다를게 없다.
• 늘 그렇든 Input의 시작은 특정 Platform Application에서 시작한다.
• 아래 예시는 화살표나 Analog 이동의 시나리오를 예시로 삼는다.
• Input Louter System은 이 UI Navigation Input을 UI 내 Widget으로 Route한다.

• Navigation Input은 보통 SWidget::OnKeydown이나 SWidget::OnAnalogValueChanged에 의해 처리된다.
• 하지만 이러한 기본 Method는 Widget Focus를 직접 변경하지 않고 아래와 같이 동작한다.

FReply SWidget::OnKeyDown( const FGeometry& MyGeometry, const FKeyEvent& InKeyEvent )
{
	if (bCanSupportFocus && SupportsKeyboardFocus())
	{
		EUINavigation Direction = FSlateApplicationBase::Get().GetNavigationDirectionFromKey(InKeyEvent);
		// It's the left stick return a navigation request of the correct direction
		if (Direction != EUINavigation::Invalid)
		{
			const ENavigationGenesis Genesis = InKeyEvent.GetKey().IsGamepadKey() ? ENavigationGenesis::Controller : ENavigationGenesis::Keyboard;
			return FReply::Handled().SetNavigation(Direction, Genesis);
		}
	}
	return FReply::Unhandled();
}

FReply SWidget::OnAnalogValueChanged( const FGeometry& MyGeometry, const FAnalogInputEvent& InAnalogInputEvent )
{
	if (bCanSupportFocus && SupportsKeyboardFocus())
	{
		EUINavigation Direction = FSlateApplicationBase::Get().GetNavigationDirectionFromAnalog(InAnalogInputEvent);
		// It's the left stick return a navigation request of the correct direction
		if (Direction != EUINavigation::Invalid)
		{
			return FReply::Handled().SetNavigation(Direction, ENavigationGenesis::Controller);
		}
	}
	return FReply::Unhandled();
}

• FSlateApplication::GetNavigationDirectionFromKey나 FSlateApplication::GetNavigationDirectionFromAnalog를
  이용해 Input을 Navigation Direction으로 변환

EUINavigation FSlateApplication::GetNavigationDirectionFromKey(const FKeyEvent& InKeyEvent) const
{
	TSharedRef<FNavigationConfig> RelevantNavConfig = GetRelevantNavConfig(InKeyEvent.GetUserIndex());
	return RelevantNavConfig->GetNavigationDirectionFromKey(InKeyEvent);
}

EUINavigation FSlateApplication::GetNavigationDirectionFromAnalog(const FAnalogInputEvent& InAnalogEvent)
{
	TSharedRef<FNavigationConfig> RelevantNavConfig = GetRelevantNavConfig(InAnalogEvent.GetUserIndex());
	return RelevantNavConfig->GetNavigationDirectionFromAnalog(InAnalogEvent);
}

• 이 과정에서 Widget에 대한 Navigation Config을 고려한다.

/** An event should return FReply::Handled().SetNavigation( NavigationType ) as a means of asking the system to attempt a navigation*/
FReply& SetNavigation(EUINavigation InNavigationType, const ENavigationGenesis InNavigationGenesis, const ENavigationSource InNavigationSource = ENavigationSource::FocusedWidget)
{
	this->NavigationType = InNavigationType;
	this->NavigationGenesis = InNavigationGenesis;
	this->NavigationSource = InNavigationSource;
	this->NavigationDestination = nullptr;
	return Me();
}

• Navigation Direction은 Capture되어 FReply::Handled에 포함된다.
  • FReply::Handled는 FReply::SetNavigation을 통해 전송된다.

void FSlateApplication::ProcessReply( const FWidgetPath& CurrentEventPath, const FReply& TheReply, const FWidgetPath* WidgetsUnderMouse, const FPointerEvent* InMouseEvent, const uint32 UserIndex )
{
/*...*/
	
	// If we have a valid Navigation request attempt the navigation.
	if (TheReply.GetNavigationDestination().IsValid() || TheReply.GetNavigationType() != EUINavigation::Invalid)
	{
		FWidgetPath NavigationSource;
/*...*/
		if (NavigationSource.IsValid())
		{
			if (!GSlateEnableGamepadEditorNavigation && TheReply.GetNavigationGenesis() == ENavigationGenesis::Controller && !NavigationSource.GetLastWidget()->GetPersistentState().bIsInGameLayer)
			{
				// Gamepad navigation while not in a game layer, do nothing as specified by GSlateEnableGamepadEditorNavigation
			}
			else if (TheReply.GetNavigationDestination().IsValid())
			{
				const bool bAlwaysHandleNavigationAttempt = false;
				ExecuteNavigation(NavigationSource, TheReply.GetNavigationDestination(), UserIndex, bAlwaysHandleNavigationAttempt);
			}
			else
			{
                                TSharedRef<SWindow> NavigationWindow = NavigationSource.GetDeepestWindow();
                                FNavigationEvent NavigationEvent(PlatformApplication->GetModifierKeys(), UserIndex, TheReply.GetNavigationType(), TheReply.GetNavigationGenesis());
                                FNavigationReply NavigationReply = FNavigationReply::Escape();
                                for (int32 WidgetIndex = NavigationSource.Widgets.Num() - 1; WidgetIndex >= 0; --WidgetIndex)
                                {
                                        FArrangedWidget& SomeWidgetGettingEvent = NavigationSource.Widgets[WidgetIndex];
                                        if (SomeWidgetGettingEvent.Widget->IsEnabled())
                                        {
                                                NavigationReply = SomeWidgetGettingEvent.Widget->OnNavigation(SomeWidgetGettingEvent.Geometry, NavigationEvent).SetHandler(SomeWidgetGettingEvent.Widget);
                                                if (NavigationReply.GetBoundaryRule() != EUINavigationRule::Escape || SomeWidgetGettingEvent.Widget == NavigationWindow || WidgetIndex == 0)
                                                {
                                                        AttemptNavigation(NavigationSource, NavigationEvent, NavigationReply, SomeWidgetGettingEvent);
                                                        break;
                                                }
                                        }
                                }
			}
		}
	}

/*...*/

	// Set focus if requested.
	TSharedPtr<SWidget> RequestedFocusRecepient = TheReply.GetUserFocusRecepient();
	if (TheReply.ShouldSetUserFocus() && RequestedFocusRecepient.IsValid())
	{
		if (TheReply.AffectsAllUsers())
		{
			SetAllUserFocus(RequestedFocusRecepient, TheReply.GetFocusCause());
		}
		else
		{
			SlateUser->SetFocus(RequestedFocusRecepient.ToSharedRef(), TheReply.GetFocusCause());
		}
	}
}

• Slate가 FSlateApplication::ProcessREply를 사용하여 Reply를 처리한다.
  • 이 과정에서 Navigation이 발생한다.
  • Navigation Event가 Direction에 의해 대략 정의 된 경우, FSlateApplication::AttemptNavigation은 Navigation 할 Widget을 찾으려 한다.
  • Navigation이 가능한 경우, FSlateExecuteNavigation이 대상 Widget으로 Navigation한다.
• 대상 Widget이 유효한 경우, FSlateApplication::SetUserFocus가 호출된다.
  • 이는 대상 Widget이 지정 되었는지, 다른 Widget을 찾았는지와 무관하게 동작한다.

void FSlateApplication::FinishedInputThisFrame()
{
	const float DeltaTime = GetDeltaTime();

	PlatformApplication->FinishedInputThisFrame();
	
	// Any preprocessors are given a chance to process accumulated values (or do whatever other tick things they want)
	// after we've finished processing all of the input for the frame
	if (PlatformApplication->Cursor.IsValid())
	{
		InputPreProcessors.Tick(DeltaTime, *this, PlatformApplication->Cursor.ToSharedRef());
	}

/*....*/
}

void FSlateApplication::InputPreProcessorsHelper::Tick(const float DeltaTime, FSlateApplication& SlateApp, TSharedRef<ICursor> Cursor)
{
	TGuardValue<bool> IteratingGuard(bIsIteratingPreProcessors, true);

	for (const TSharedPtr<IInputProcessor>& Preprocessor : InputPreProcessorList)
	{
		if (Preprocessor)
		{
			Preprocessor->Tick(DeltaTime, SlateApp, Cursor);
		}
	}
}

• Slate Focus Navigation이 종료된 후,
  FSlateAnalogCursor::Tick에서 자동으로 다음 Tick 도중 Synthetic Cursor를 Focused Widget의 중앙으로 이동시킨다.
  • 이를 통해 Gamepad에서 Hover Effect를 사용할 수 있다.

Customize Synthetic Cursor Behavior in Common UI

• Common UI를 이용하면 고유한 Analogue Cursor나 Synthetic Cursor를 제공할 수 있다.
• Common UI를 통해 고유 Cursor를 제공하는 것에는 몇 가지 이점이 있다.
  • Gamepad와 유사하게 작동하는 Keyboard Navigation을 만들려 하는 경우,
    Gamepad를 사용하지 않을 때에도 FCommonAnalogCursor::Tick이 Widget의 중앙에 Snap되도록 할 수 있다.
  • Synthetic Mouse를 보이도록 하고, Focus가 달라질 때 Tween을 구현할 수 있다.
    • Tween: 그래픽 상으로 두 상태나 프레임 사이를 자동으로 생성하는 Process
• Custom cursor를 만드는 방법은 다음과 같다.
  • UCommonUIActionRouterBase를 상속받은 Custom ActionRouter Class 생성
  • FCommonAnalogCursor를 상속받은 Custom AnalogCursor Class 생성
  • Custom ActionRouter Class에서 MakeAnalogCursor를 Override하여 Custom AnalogCursor Class를 반환
• Custom Router Class에서 ShouldCreateSubsystem은 Override 된 경우 Instance를 생성하지 않는다.
• 이러한 Input Processor를 Customize 할 때에는 한가지 주의할 점이 있다.
  • Input Processor는 모든 Input에서 실행 된다.
    • 이는 Editor도 포함한다.
  • 아래 함수를 이용하면 Application에서 발생한 Input과 그렇지 않은 것을 구분하는데 도움이 될 수 있다.

bool FCommonAnalogCursor::IsGameViewportInFocusPathWithoutCapture() const
{
	if (const UGameViewportClient* ViewportClient = GetViewportClient())
	{
		if (TSharedPtr<SViewport> GameViewportWidget = ViewportClient->GetGameViewportWidget())
		{
			TSharedPtr<FSlateUser> SlateUser = FSlateApplication::Get().GetUser(GetOwnerUserIndex());
			if (SlateUser && !SlateUser->DoesWidgetHaveCursorCapture(GameViewportWidget))
			{
#if PLATFORM_DESKTOP
				// Not captured - is it in the focus path?
				return SlateUser->IsWidgetInFocusPath(GameViewportWidget);
#endif
				// If we're not on desktop, focus on the viewport is irrelevant, as there aren't other windows around to care about
				return true;
			}
		}
	}
	return false;
}

Input Routing

• 간략하게 정리하면 다음과 같다.
  • Common UI는 ActivableWidget을 Navigation을 처리하는 Node Tree로 구성한다.
    • Inactive Widget은 추가되지 않고, 그에 따라 Router 대상으로 고려되지 않는다.
  • CommonGameviewportClient가 Input을 Capture하고, Hierarchy의 최상단에 표시되는 Node를 탐색한다.
  • 탐색된 Node에서 사용 가능 한 Input Handler를 이용해 Input을 처리할 수 있는지 확인한다.
    • Player Input과 일치한 Handler가 없는 경우 자손 Node로 전달한다.
  • 적절한 Node를 찾을 때까지 탐색을 반복한다.
• 이 Process는 모든 Node를 탐색할 때까지 반복한다.

bool FActivatableTreeNode::ProcessNormalInput(ECommonInputMode ActiveInputMode, FKey Key, EInputEvent InputEvent) const
{
	if (IsReceivingInput())
	{
		for (const FActivatableTreeNodeRef& ChildNode : Children)
		{
			if (ChildNode->ProcessNormalInput(ActiveInputMode, Key, InputEvent))
			{
				return true;
			}
		}
		return FActionRouterBindingCollection::ProcessNormalInput(ActiveInputMode, Key, InputEvent);
	}
	return false;
}

• 탐색 방식은 BFS에 가깝다.

Execution Flow

• Synthetic Cursor와 마찬가지로 Input Processor는 Input Routing 발생 전에 Event를 처리할 수 있다.
  • Input Processor에서 처리하지 않는 경우, Input Event는 Common UI의 Input Routing을 진행한다.

Click Event Process

• 특정 Platform Application이 FSlateApplication::ProcessKeyDownEvent를 Trigger 할 때 Input이 시작된다.

bool FSlateApplication::ProcessKeyDownEvent( const FKeyEvent& InKeyEvent )
{
/*...*/
	// Send out key down events.
    if ( !Reply.IsEventHandled() )
    {
        Reply = FEventRouter::RouteAlongFocusPath(this, FEventRouter::FBubblePolicy(EventPath), InKeyEvent, [] (const FArrangedWidget& SomeWidgetGettingEvent, const FKeyEvent& Event)
        {
            if (SomeWidgetGettingEvent.Widget->IsEnabled())
            {
                const FReply TempReply = SomeWidgetGettingEvent.Widget->OnKeyDown(SomeWidgetGettingEvent.Geometry, Event);
                return TempReply;
            }
            return FReply::Unhandled();
        }, ESlateDebuggingInputEvent::KeyDown);
    }
/*...*/
	return Reply.IsEventHandled();
}

• Slate Application은 현재 Focus 경로를 기반으로 Widget에 Input Event를 전달한다.

FReply SViewport::OnKeyDown( const FGeometry& MyGeometry, const FKeyEvent& KeyEvent )
{
	return ViewportInterface.IsValid() ? ViewportInterface.Pin()->OnKeyDown(MyGeometry, KeyEvent) : FReply::Unhandled();
}

• Game 내에서는 보통 SViewport::OnKeyDown Input Event이다.
  • 이 Input Event는 현재 Viewport Interface Implemented Class로 키 누름을 전달한다.

FReply FSceneViewport::OnKeyDown( const FGeometry& InGeometry, const FKeyEvent& InKeyEvent )
{
	// Start a new reply state
	CurrentReplyState = FReply::Handled(); 

	FKey Key = InKeyEvent.GetKey();
	if (Key.IsValid())
	{
		KeyStateMap.Add(Key, true);

		//@todo Slate Viewports: FWindowsViewport checks for Alt+Enter or F11 and toggles fullscreen.  Unknown if fullscreen via this method will be needed for slate viewports. 
		if (ViewportClient && GetSizeXY() != FIntPoint::ZeroValue)
		{
			// Switch to the viewport clients world before processing input
			FScopedConditionalWorldSwitcher WorldSwitcher(ViewportClient);

			if (!ViewportClient->InputKey(FInputKeyEventArgs(this, InKeyEvent.GetInputDeviceId(), Key, InKeyEvent.IsRepeat() ? IE_Repeat : IE_Pressed, 1.0f, false)))
			{
				CurrentReplyState = FReply::Unhandled();
			}
		}
	}
	else
	{
		CurrentReplyState = FReply::Unhandled();
	}
	return CurrentReplyState;
}

• 보통은 키 누름이 전달되면 FSceneViewPort::OnKeyDown이 트리거 된다.
• 마지막으로 SceneViewPort는 Input을 현재 GameViewportClient의 InputKey Method로 전달한다.

bool UCommonGameViewportClient::InputKey(const FInputKeyEventArgs& InEventArgs)
{
	FInputKeyEventArgs EventArgs = InEventArgs;

	if (IsKeyPriorityAboveUI(EventArgs))
	{
		return true;
	}

	// Check override before UI
	if (OnOverrideInputKey().IsBound())
	{
		if (OnOverrideInputKey().Execute(EventArgs))
		{
			return true;
		}
	}

	// The input is fair game for handling - the UI gets first dibs
#if !UE_BUILD_SHIPPING
	if (ViewportConsole && !ViewportConsole->ConsoleState.IsEqual(NAME_Typing) && !ViewportConsole->ConsoleState.IsEqual(NAME_Open))
#endif
	{		
		FReply Result = FReply::Unhandled();
		if (!OnRerouteInput().ExecuteIfBound(EventArgs.InputDevice, EventArgs.Key, EventArgs.Event, Result))
		{
			HandleRerouteInput(EventArgs.InputDevice, EventArgs.Key, EventArgs.Event, Result);
		}

		if (Result.IsEventHandled())
		{
			return true;
		}
	}

	return Super::InputKey(EventArgs);
}

• Common UI를 사용할 때에는 이것이 UCommonGameViewportClient::InputKey이다.
  • 때문에 Common UI를 사용하려면 GameViewportClass가 CommonViewportClient로 설정되어야 한다.

Action Router Process

bool UCommonGameViewportClient::InputKey(const FInputKeyEventArgs& InEventArgs)
{
	FInputKeyEventArgs EventArgs = InEventArgs;

	if (IsKeyPriorityAboveUI(EventArgs))
	{
		return true;
	}

	// Check override before UI
	if (OnOverrideInputKey().IsBound())
	{
		if (OnOverrideInputKey().Execute(EventArgs))
		{
			return true;
		}
	}

	// The input is fair game for handling - the UI gets first dibs
#if !UE_BUILD_SHIPPING
	if (ViewportConsole && !ViewportConsole->ConsoleState.IsEqual(NAME_Typing) && !ViewportConsole->ConsoleState.IsEqual(NAME_Open))
#endif
	{		
		FReply Result = FReply::Unhandled();
		if (!OnRerouteInput().ExecuteIfBound(EventArgs.InputDevice, EventArgs.Key, EventArgs.Event, Result))
		{
			HandleRerouteInput(EventArgs.InputDevice, EventArgs.Key, EventArgs.Event, Result);
		}

		if (Result.IsEventHandled())
		{
			return true;
		}
	}

	return Super::InputKey(EventArgs);
}

• Common UI의 Action Router Process는 Input이 CommonGameViewportClient에 전달되면서 시작합니다.

void UCommonGameViewportClient::HandleRerouteInput(FInputDeviceId DeviceId, FKey Key, EInputEvent EventType, FReply& Reply)
{
	FPlatformUserId OwningPlatformUser = IPlatformInputDeviceMapper::Get().GetUserForInputDevice(DeviceId);
	ULocalPlayer* LocalPlayer = GameInstance->FindLocalPlayerFromPlatformUserId(OwningPlatformUser);
	Reply = FReply::Unhandled();

	if (LocalPlayer)
	{
		UCommonUIActionRouterBase* ActionRouter = LocalPlayer->GetSubsystem<UCommonUIActionRouterBase>();
		if (ensure(ActionRouter))
		{
			ERouteUIInputResult InputResult = ActionRouter->ProcessInput(Key, EventType);
			if (InputResult == ERouteUIInputResult::BlockGameInput)
			{
				// We need to set the reply as handled otherwise the input won't actually be blocked from reaching the viewport.
				Reply = FReply::Handled();
				// Notify interested parties that we blocked the input.
				OnRerouteBlockedInput().ExecuteIfBound(DeviceId, Key, EventType, Reply);
			}
			else if (InputResult == ERouteUIInputResult::Handled)
			{
				Reply = FReply::Handled();
			}
		}
	}	
}

• UCommonGaameViewportClient::InputKey는 ActionLouter에
  UCommonGameViewportClient::HandleRerouteInput의 입력을 처리할 기회를 제공한다.

ERouteUIInputResult UCommonUIActionRouterBase::ProcessInput(FKey Key, EInputEvent InputEvent) const
{
/*....*/
	const auto ProcessNormalInputFunc = [Key, ActiveMode, this](EInputEvent Event)
		{
			bool bHandled = PersistentActions->ProcessNormalInput(ActiveMode, Key, Event);

			if (!bHandled)
			{
				if (bIsActivatableTreeEnabled && ActiveRootNode)
				{
					bHandled = ActiveRootNode->ProcessNormalInput(ActiveMode, Key, Event);
				}

				if (!bHandled)
				{
					bHandled = ProcessInputOnActionDomains(ActiveMode, Key, Event);
				}
			}

			return bHandled;
		};

	bool bHandledInput = ProcessHoldResult == EProcessHoldActionResult::Handled;
	if (!bHandledInput)
	{
		if (ProcessHoldResult == EProcessHoldActionResult::GeneratePress)
		{
			// A hold action was in progress but quickly aborted, so we want to generate a press action now for any normal bindings that are interested
			ProcessNormalInputFunc(IE_Pressed);
		}

		// Even if no widget cares about this input, we don't want to let anything through to the actual game while we're in menu mode
		bHandledInput = ProcessNormalInputFunc(InputEvent); 
	}

	if (bHandledInput)
	{
		return ERouteUIInputResult::Handled;
	}
	return CanProcessNormalGameInput() ? ERouteUIInputResult::Unhandled : ERouteUIInputResult::BlockGameInput;
}

• 성공하면, UCommonUIActionRouterBase::ProcessInput을 호출한다.

• Action Router는 ActivatableWidget Tree에서 현재 Active 중인 Root Node를 유지합니다.

bool FActivatableTreeNode::ProcessNormalInput(ECommonInputMode ActiveInputMode, FKey Key, EInputEvent InputEvent) const
{
	if (IsReceivingInput())
	{
		for (const FActivatableTreeNodeRef& ChildNode : Children)
		{
			if (ChildNode->ProcessNormalInput(ActiveInputMode, Key, InputEvent))
			{
				return true;
			}
		}
		return FActionRouterBindingCollection::ProcessNormalInput(ActiveInputMode, Key, InputEvent);
	}
	return false;
}

• ProcessInput은 Root Node에서 FActivatableTreeNode::ProcessNormalInput을 호출해
  Input 처리 시도를 지시합니다.
  • 이는 반복적으로 모든 Child Node에 ProcessNormalInput을 지시한다.

bool FActionRouterBindingCollection::ProcessNormalInput(ECommonInputMode ActiveInputMode, FKey Key, EInputEvent InputEvent) const
{
	for (FUIActionBindingHandle BindingHandle : ActionBindings)
	{
		if (TSharedPtr<FUIActionBinding> Binding = FUIActionBinding::FindBinding(BindingHandle))
		{
			if (ActiveInputMode == ECommonInputMode::All || ActiveInputMode == Binding->InputMode)
			{
				auto TryConsumeInput = [&](const FKey& InKey, const UInputAction* InInputAction)
				{
					// A persistent displayed action skips the normal rules for reachability, since it'll always appear in a bound action bar
					const bool bIsDisplayedPersistentAction = Binding->bIsPersistent && Binding->bDisplayInActionBar;
					if (InKey == Key && Binding->InputEvent == InputEvent && (bIsDisplayedPersistentAction || IsWidgetReachableForInput(Binding->BoundWidget.Get())))
					{
						// Just in case this was in the middle of a hold process with a different key, reset now
						Binding->CancelHold();

						// If injecting enhanced input. don't fire 'OnExecuteAction' since that can be manually done if desired in BP
						bool bEnhancedInputInjected = false;
						if (InInputAction)
						{
							if (TObjectPtr<const UCommonInputMetadata> CommonInputMetadata = CommonUI::GetEnhancedInputActionMetadata(InInputAction))
							{
								// Non generic actions should inject enhanced input so users can bind to enhanced input events
								if (!CommonInputMetadata->bIsGenericInputAction)
								{
									FInputActionValue RawValue = FInputActionValue(true);
									CommonUI::InjectEnhancedInputForAction(GetActionRouter().GetLocalPlayerChecked(), InInputAction, RawValue);
									bEnhancedInputInjected = true;
								}
							}
						}
						
						if (!bEnhancedInputInjected)
						{
							Binding->OnExecuteAction.ExecuteIfBound();
						}

						if (Binding->bConsumesInput)
						{
							return true;
						}
					}

					return false;
				};


				if (CommonUI::IsEnhancedInputSupportEnabled() && Binding->InputAction.IsValid())
				{
					if (const UInputAction* InputAction = Binding->InputAction.Get())
					{
						TArray<FKey> InputActionKeys;
						CommonUI::GetEnhancedInputActionKeys(GetActionRouter().GetLocalPlayerChecked(), InputAction, InputActionKeys);
						for (const FKey& InputActionKey : InputActionKeys)
						{
							if (TryConsumeInput(InputActionKey, InputAction))
							{
								return true;
							}
						}
					}
				}

				for (const FUIActionKeyMapping& KeyMapping : Binding->NormalMappings)
				{
					if (TryConsumeInput(KeyMapping.Key, nullptr))
					{
						return true;
					}
				}
			}
		}
	}
	return false;
}

• FActivatableTreeNode는 FActionRouterBindingCollection으로,
  Node의 ActivatableWidget에 모든 ActionBinding List를 유지한다.
• 현재 Node 내의 모든 Child Node에서 Input을 처리하지 못하면,
  FActivatableTreeNode::ProcessNormalInput을 호출한다.
  • 이 때 FActivatableTreeNode는 Binding Collection으로서 현재 Node는 Widget의 모든 Action Binding을 확인한다.
  • Action Binding이 해당 Key와 일치하는 경우, 관련 동작이 실행되고 Input이 처리된 것으로 간주된다.

Modify the Input Routing System

• UCommonGameViewportClient를 상속받고 모든 Input Handling Method를 Override 하라.
  • 이후 Project Setting에서 이 Class를 GameVieportClss로 설정한다.
• UCommonUIActionRouterBase를 상속받고 모든 Virtual Function을 Override한다.
  • 예를 들어, FUIInputconfig에서 ApplyUIInputConfig를 Override 할 수 있다.

Change UI Input Handling with Input config

• 현재 활성화 된 Widget을 기반으로 Application의 Input Handling이 변경되어야 하는 경우가 있다.
  • 예를 들어 Social Sidebar 혹은 Pause Menu가 열려 있을 때 Player Input을 막는다던가.
• 이를 처리하기 위해 Common UI에서는 ActivatableWidget의 Inputconfig 옵션을 지원한다.
  • 이는 Common UI 사용에 필수적인 사안은 아니다.

Use Input Config

/**
 * Input Config that can be applied on widget activation. Allows for input setup  (Mouse capture, 
 * UI-only input, move / look ignore, etc), to be controlled by widget activation.
 */
USTRUCT(BlueprintType)
struct COMMONUI_API FUIInputConfig
{
	GENERATED_BODY()

	ECommonInputMode GetInputMode() const { return InputMode; }
	EMouseCaptureMode GetMouseCaptureMode() const { return MouseCaptureMode; }
	EMouseLockMode GetMouseLockMode() const { return MouseLockMode; }
	bool HideCursorDuringViewportCapture() const { return bHideCursorDuringViewportCapture; }

	FUIInputConfig();
	FUIInputConfig(ECommonInputMode InInputMode, EMouseCaptureMode InMouseCaptureMode, bool bInHideCursorDuringViewportCapture = true);
	FUIInputConfig(ECommonInputMode InInputMode, EMouseCaptureMode InMouseCaptureMode, EMouseLockMode InMouseLockMode, bool bInHideCursorDuringViewportCapture = true);

	bool operator==(const FUIInputConfig& Other) const
	{
		return bIgnoreMoveInput == Other.bIgnoreMoveInput
			&& bIgnoreLookInput == Other.bIgnoreLookInput
			&& InputMode == Other.InputMode
			&& MouseCaptureMode == Other.MouseCaptureMode
			&& MouseLockMode == Other.MouseLockMode
			&& bHideCursorDuringViewportCapture == Other.bHideCursorDuringViewportCapture;
	}

	bool operator!=(const FUIInputConfig& Other) const
	{
		return !operator==(Other);
	}

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bIgnoreMoveInput = false;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bIgnoreLookInput = false;

	/** Simplification of config as string */
	FString ToString() const;

protected:


	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	ECommonInputMode InputMode;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	EMouseCaptureMode MouseCaptureMode;


	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	EMouseLockMode MouseLockMode;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bHideCursorDuringViewportCapture = true;
};

• 각 InputConfig는 여러 Input의 상태를 추적한다.
  • Mouse Capture Option
  • 이동 및 시야 축 처리
  • Common UI 전체의 Input Mode등

/**
 * Gets the desired input configuration to establish when this widget activates and can receive input (i.e. all parents are also active).
 * This configuration will override the existing one established by any previous activatable widget and restore it (if valid) upon deactivation.
 */
 TOptional<FUIInputConfig> UCommonActivatableWidget::GetDesiredInputConfig() const
{
	// Check if there is a BP implementation for input configs
	if (GetClass()->IsFunctionImplementedInScript(GET_FUNCTION_NAME_CHECKED(UCommonActivatableWidget, BP_GetDesiredInputConfig)))
	{
		return BP_GetDesiredInputConfig();
	}

	// No particular config is desired by default
	return TOptional<FUIInputConfig>();
}

• ActivatableWidget을 활성화하면 GetDesiredInputConfig를 사용하여 InputConfig를 가져온다.
  • 일반적으로는 null을 반환하지만 Override가 가능하다.
  • GetDesiredInputConfig가 Null을 반환할 때마다 Common UI는 마지막으로 유효했던 InputConfig로 되돌아간다.

/**
* Controls whether a default Input Config will be set when the active CommonActivatableWidgets do not specify a desired one.
* Disable this if you want to control the Input Mode via alternative means.
*/
UPROPERTY(config, EditAnywhere, Category = "Input")
bool bEnableDefaultInputConfig = true;

• 기본적으로 Common UI는 ActivatableWidget으로 지정되지 않는 경우 예비로 InputConfig를 적용한다.
  • 하지만 위 변수를 사용해 이를 비활성화 할 수 있다.

void FActivatableTreeRoot::ApplyLeafmostNodeConfig()
{
#if WITH_EDITOR
	if (!IsViewportWindowInFocusPath(GetActionRouter()))
	{
		return;
	}
#endif
	if (FActivatableTreeNodePtr PinnedLeafmostNode = LeafmostActiveNode.Pin())
	{
		GetActionRouter().SetActiveActivationMetadata(PinnedLeafmostNode->FindActivationMetadata());

		if (ensure(PinnedLeafmostNode->IsReceivingInput()))
		{
			UE_LOG(LogUIActionRouter, Display, TEXT("Applying input config for leaf-most node [%s]"), *PinnedLeafmostNode->GetWidget()->GetName());

			TOptional<FUIInputConfig> DesiredConfig = PinnedLeafmostNode->FindDesiredInputConfig();
			if(DesiredConfig.IsSet())
			{
				GetActionRouter().SetActiveUIInputConfig(DesiredConfig.GetValue(), PinnedLeafmostNode->GetWidget());
			}
			else if(ICommonInputModule::GetSettings().GetEnableDefaultInputConfig())
			{
				// Nobody in the entire tree cares about the config and the default is enabled so fall back to the default
				GetActionRouter().SetActiveUIInputConfig(FUIInputConfig());
			}

			FocusLeafmostNode();
		}
		else
		{
			UE_LOG(LogUIActionRouter, Log, TEXT("Didn't apply input config for leaf-most node [%s] because it's not receiving input right now"), *PinnedLeafmostNode->GetWidget()->GetName());
		}
	}
}

• Widget이 비활성화 되면 Common UI는 이전 InputConfig를 복구한다.
  • 이는 현재 Widget을 지원할 적절한 Inputconfig가 없이 중단되는 것을 방지하기 위함이다.
• 만약 UI의 모든 Widget이 비활성화 되면
  CommonUI는 마지막으로 비활성화 된 Widget의 Default InputConfig를 사용한다.
  • 이 경우 마지막으로 비활성화 된 Widget이 Soft Lock 방지를 위해
    합리적인 InputConfig 상태를 다시 적용하도록 해야 한다.

Recommended Use

• InputConfig를 사용하는 경우 UI에서 표준 InputConfig를 사용하지 않아야 한다.

void UCommonUIActionRouterBase::ApplyUIInputConfig(const FUIInputConfig& NewConfig, bool bForceRefresh)
{
	if (bForceRefresh || NewConfig != ActiveInputConfig.GetValue())
	{
		UE_LOG(LogUIActionRouter, Display, TEXT("UIInputConfig being changed. bForceRefresh: %d"), bForceRefresh ? 1 : 0);
		UE_LOG(LogUIActionRouter, Display, TEXT("\tInputMode: Previous (%s), New (%s)"),
			ActiveInputConfig.IsSet() ? *StaticEnum<ECommonInputMode>()->GetValueAsString(ActiveInputConfig->GetInputMode()) : TEXT("None"), *StaticEnum<ECommonInputMode>()->GetValueAsString(NewConfig.GetInputMode()));

		const ECommonInputMode PreviousInputMode = GetActiveInputMode();

		TOptional<FUIInputConfig> OldConfig = ActiveInputConfig;
		ActiveInputConfig = NewConfig;

		ULocalPlayer& LocalPlayer = *GetLocalPlayerChecked();

		// Note: may not work for splitscreen. We need per-player viewport client settings for mouse capture
		if (UGameViewportClient* GameViewportClient = LocalPlayer.ViewportClient)
		{
			if (TSharedPtr<SViewport> ViewportWidget = GameViewportClient->GetGameViewportWidget())
			{
				if (APlayerController* PC = LocalPlayer.GetPlayerController(GetWorld()))
				{
					if (!OldConfig.IsSet() || OldConfig.GetValue().bIgnoreMoveInput != NewConfig.bIgnoreMoveInput)
					{
						PC->SetIgnoreMoveInput(NewConfig.bIgnoreMoveInput);						
					}
					
					if (!OldConfig.IsSet() || OldConfig.GetValue().bIgnoreLookInput != NewConfig.bIgnoreLookInput)
					{
						PC->SetIgnoreLookInput(NewConfig.bIgnoreLookInput);						
					}

					if (bAutoFlushPressedKeys && NewConfig.GetInputMode() == ECommonInputMode::Menu && PreviousInputMode != NewConfig.GetInputMode())
					{
						// Flushing pressed keys after switching to the Menu InputMode. This prevents the inputs from being artificially "held down".
						// This needs to be delayed by one frame to successfully clear input captured at the end of this frame
						GetWorld()->GetTimerManager().SetTimerForNextTick(this, &ThisClass::FlushPressedKeys);
					}

					const bool bWasCursorHidden = !PC->ShouldShowMouseCursor();

					GameViewportClient->SetMouseCaptureMode(NewConfig.GetMouseCaptureMode());
					GameViewportClient->SetHideCursorDuringCapture(NewConfig.HideCursorDuringViewportCapture() && !ShouldAlwaysShowCursor());
					GameViewportClient->SetMouseLockMode(NewConfig.GetMouseLockMode());

					FReply& SlateOperations = LocalPlayer.GetSlateOperations();
					const EMouseCaptureMode CaptureMode = NewConfig.GetMouseCaptureMode();
					switch (CaptureMode)
					{
					case EMouseCaptureMode::CapturePermanently:
					case EMouseCaptureMode::CapturePermanently_IncludingInitialMouseDown:
					{
						PC->SetShowMouseCursor(ShouldAlwaysShowCursor() || !NewConfig.HideCursorDuringViewportCapture());

						TSharedRef<SViewport> ViewportWidgetRef = ViewportWidget.ToSharedRef();
						SlateOperations.UseHighPrecisionMouseMovement(ViewportWidgetRef);
						SlateOperations.SetUserFocus(ViewportWidgetRef);
						SlateOperations.CaptureMouse(ViewportWidgetRef);

						if (GameViewportClient->ShouldAlwaysLockMouse() || GameViewportClient->LockDuringCapture() || !PC->ShouldShowMouseCursor())
						{
							SlateOperations.LockMouseToWidget(ViewportWidget.ToSharedRef());
						}
						else
						{
							SlateOperations.ReleaseMouseLock();
						}
					}
					break;
					case EMouseCaptureMode::NoCapture:
					case EMouseCaptureMode::CaptureDuringMouseDown:
					case EMouseCaptureMode::CaptureDuringRightMouseDown:
					{
						PC->SetShowMouseCursor(true);

						SlateOperations.ReleaseMouseCapture();

						if (GameViewportClient->ShouldAlwaysLockMouse())
						{
							SlateOperations.LockMouseToWidget(ViewportWidget.ToSharedRef());
						}
						else
						{
							SlateOperations.ReleaseMouseLock();
						}
					}
					break;
					}

					// If the mouse was hidden previously, set it back to the center of the viewport now that we're showing it again 
					if (!bForceRefresh && bWasCursorHidden && PC->ShouldShowMouseCursor())
					{
						const ECommonInputType CurrentInputType = GetInputSubsystem().GetCurrentInputType();
						
						bool bCenterCursor = true;
						switch (CurrentInputType)
						{
							// Touch - Don't do it - the cursor isn't really relevant there.
							case ECommonInputType::Touch:
								bCenterCursor = false;
								break;
							// Gamepad - Let the settings tell us if we should center it.
							case ECommonInputType::Gamepad:
								break;
						}

						if (bCenterCursor)
						{
							TSharedPtr<FSlateUser> SlateUser = LocalPlayer.GetSlateUser();
							TSharedPtr<IGameLayerManager> GameLayerManager = GameViewportClient->GetGameLayerManager();
							if (ensure(SlateUser) && ensure(GameLayerManager))
							{
								FGeometry PlayerViewGeometry = GameLayerManager->GetPlayerWidgetHostGeometry(&LocalPlayer);
								const FVector2D AbsoluteViewCenter = PlayerViewGeometry.GetAbsolutePositionAtCoordinates(FVector2D(0.5f, 0.5f));
								SlateUser->SetCursorPosition(AbsoluteViewCenter);

								UE_LOG(LogUIActionRouter, Verbose, TEXT("Moving the cursor to the viewport center."));
							}
						}
					}
				}
				else
				{
					UE_LOG(LogUIActionRouter, Warning, TEXT("\tFailed to commit change! Local player controller was null."));
				}
			}
			else
			{
				UE_LOG(LogUIActionRouter, Warning, TEXT("\tFailed to commit change! ViewportWidget was null."));
			}
		}
		else
		{
			UE_LOG(LogUIActionRouter, Warning, TEXT("\tFailed to commit change! GameViewportClient was null."));
		}

		if (PreviousInputMode != NewConfig.GetInputMode())
		{
			OnActiveInputModeChanged().Broadcast(NewConfig.GetInputMode());
		}
	}
}

• UCommonUIActionRouterBase::ApplyInputConfig에서는 Config Process 과정에서
  다음 Unreal의 표준 InputConfig들을 기능의 일부로 호출한다.

void AController::SetIgnoreMoveInput(bool bNewMoveInput)
{
	IgnoreMoveInput = FMath::Max(IgnoreMoveInput + (bNewMoveInput ? +1 : -1), 0);
}

void UGameViewportClient::SetMouseCaptureMode(EMouseCaptureMode Mode)
{
	if (MouseCaptureMode != Mode)
	{
		UE_LOG(LogViewport, Display, TEXT("Viewport MouseCaptureMode Changed, %s -> %s"),
			*StaticEnum<EMouseCaptureMode>()->GetNameStringByValue((uint64)MouseCaptureMode),
			*StaticEnum<EMouseCaptureMode>()->GetNameStringByValue((uint64)Mode)
		);

		MouseCaptureMode = Mode;
	}
}

void UGameViewportClient::SetHideCursorDuringCapture(bool InHideCursorDuringCapture)
{
	if (bHideCursorDuringCapture != InHideCursorDuringCapture)
	{
		UE_LOG(LogViewport, Display, TEXT("Viewport HideCursorDuringCapture Changed, %s -> %s"),
			bHideCursorDuringCapture ? TEXT("True") : TEXT("False"),
			InHideCursorDuringCapture ? TEXT("True") : TEXT("False")
		);

		bHideCursorDuringCapture = InHideCursorDuringCapture;
	}
}

• 때문에 다른 곳에서 이런 함수를 호출하며 Common UI의 InputConfig와 혼용할 경우 서로를 Override하여 관리할 때 혼란이 발생할 수 있다.
• Input Config 관리를 간소화하기 위해
  Widget의 Enum값을 기반으로 주로 사용하는 InputConfig를 할당하는 기본 구현을 생성할 수 있다.
  • 이는 Widget별로 몇 개의 고정적인 Async InputConfig만 필요한 경우에 유용하다.

Input Handling State Reference

FUIInputConfig

/**
 * Input Config that can be applied on widget activation. Allows for input setup  (Mouse capture, 
 * UI-only input, move / look ignore, etc), to be controlled by widget activation.
 */
USTRUCT(BlueprintType)
struct COMMONUI_API FUIInputConfig
{
	GENERATED_BODY()

	ECommonInputMode GetInputMode() const { return InputMode; }
	EMouseCaptureMode GetMouseCaptureMode() const { return MouseCaptureMode; }
	EMouseLockMode GetMouseLockMode() const { return MouseLockMode; }
	bool HideCursorDuringViewportCapture() const { return bHideCursorDuringViewportCapture; }

	FUIInputConfig();
	FUIInputConfig(ECommonInputMode InInputMode, EMouseCaptureMode InMouseCaptureMode, bool bInHideCursorDuringViewportCapture = true);
	FUIInputConfig(ECommonInputMode InInputMode, EMouseCaptureMode InMouseCaptureMode, EMouseLockMode InMouseLockMode, bool bInHideCursorDuringViewportCapture = true);

	bool operator==(const FUIInputConfig& Other) const
	{
		return bIgnoreMoveInput == Other.bIgnoreMoveInput
			&& bIgnoreLookInput == Other.bIgnoreLookInput
			&& InputMode == Other.InputMode
			&& MouseCaptureMode == Other.MouseCaptureMode
			&& MouseLockMode == Other.MouseLockMode
			&& bHideCursorDuringViewportCapture == Other.bHideCursorDuringViewportCapture;
	}

	bool operator!=(const FUIInputConfig& Other) const
	{
		return !operator==(Other);
	}

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bIgnoreMoveInput = false;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bIgnoreLookInput = false;

	/** Simplification of config as string */
	FString ToString() const;

protected:


	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	ECommonInputMode InputMode;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	EMouseCaptureMode MouseCaptureMode;


	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	EMouseLockMode MouseLockMode;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = InputConfig)
	bool bHideCursorDuringViewportCapture = true;
};

ECommonInputMode

UENUM(BlueprintType)
enum class ECommonInputMode : uint8
{
	Menu	UMETA(Tooltip = "Input is received by the UI only"),
	Game	UMETA(Tooltip = "Input is received by the Game only"),
	All		UMETA(Tooltip = "Input is received by UI and the Game"),

	MAX UMETA(Hidden)
};

EMouseCaptureMode

UENUM()
enum class EMouseCaptureMode : uint8
{
	/** Do not capture the mouse at all */
	NoCapture,
	/** Capture the mouse permanently when the viewport is clicked, and consume the initial mouse down that caused the capture so it isn't processed by player input */
	CapturePermanently,
	/** Capture the mouse permanently when the viewport is clicked, and allow player input to process the mouse down that caused the capture */
	CapturePermanently_IncludingInitialMouseDown,
	/** Capture the mouse during a mouse down, releases on mouse up */
	CaptureDuringMouseDown,
	/** Capture only when the right mouse button is down, not any of the other mouse buttons */
	CaptureDuringRightMouseDown,
};

EMouseLockMode

UENUM()
enum class EMouseLockMode : uint8
{
	/** Do not lock the mouse cursor to the viewport */
	DoNotLock,
	/** Only lock the mouse cursor to the viewport when the mouse is captured */
	LockOnCapture,
	/** Always lock the mouse cursor to the viewport */
	LockAlways,
	/** Lock the cursor if we're in fullscreen */
	LockInFullscreen,
};

Change Widget Input Respons Using FReply

• FReply는 InputEvent의 처리 상태를 추적한다.

/**
 * An event should return a FReply::Handled() to let the system know that an event was handled.
 */
static FReply Handled( )
{
	return FReply(true);
}

/**
 * An event should return a FReply::Unhandled() to let the system know that an event was unhandled.
 */
static FReply Unhandled( )
{
	return FReply(false);
}

• Slate의 Input은 대부분 FReply::Handled나 FReply::Unhandled를 결과로 반환한다.
• SWidget에서 사용되는 수 많은 Input Event들은 대부분 FReply를 반환한다.
  • 이를 이용해 특정 FReply를 반환하여 원하는 결과를 얻게할 수 있다.
    • 예를들어 특정 InputType의 처리를 허용 또는 중지한다던가.
  • 하지만 대부분은 순정 FReply를 사용해도 크게 문제 없을 것이다.
• FReply를 Customize 할 때에는 Slate Widget 작업에서 문제가 발생하는 경우가 많다.

FReply Settings

• 보통은 FReply의 Handled/UnHandled로만 상태를 추적하지만, 몇 가지 추가 데이터를 제공하기도 한다.
• 이러한 Method는 UMG나 Slate의 일부 Method와 비슷해 보일 수 있다.
  • 하지만 기본적으로 FReply Namespace에 존재하며, Slate에서 FReply를 처리할 때 발생하는 동작을 수정한다.
• FReply에서 이런 Method를 호출하면 FReply 외부의 동등한 Method를 호출한다.
  • 이는 쉽게 복제할 수 없는 조금 다른 동작이 나올 수 있다.

CaptureMouse

/** An event should return a FReply::Handled().CaptureMouse( SomeWidget ) as a means of asking the system to forward all mouse events to SomeWidget */
FReply& CaptureMouse( TSharedRef<SWidget> InMouseCaptor )
{
	this->MouseCaptor = InMouseCaptor;
	return Me();
}

• System에 특정 Widget으로 모든 MouseEvent를 전달하도록 요청

ClearUserFocus

/** An event should return a FReply::Handled().ClearUserFocus() to ask the system to clear user focus*/
FReply& ClearUserFocus(bool bInAllUsers = false)
{
    return ClearUserFocus(EFocusCause::SetDirectly, bInAllUsers);
}

/** An event should return a FReply::Handled().ClearUserFocus() to ask the system to clear user focus*/
SLATECORE_API FReply& ClearUserFocus(EFocusCause ReasonFocusIsChanging, bool bInAllUsers = false)
{
	this->FocusRecipient = nullptr;
	this->FocusChangeReason = ReasonFocusIsChanging;
	this->bReleaseUserFocus = true;
	this->bSetUserFocus = false;
	this->bAllUsers = bInAllUsers;
	return Me();
}

• System에 User Focus를 지우기를 요청

ReleaseMouseCapture

/** 
 * An event should return a FReply::Handled().ReleaseMouse() to ask the system to release mouse capture
 * NOTE: Deactivates high precision mouse movement if activated.
 */
FReply& ReleaseMouseCapture()
{
	this->MouseCaptor.Reset();
	this->bReleaseMouseCapture = true;
	this->bUseHighPrecisionMouse = false;
	return Me();
}

• System에 Mouse Capture 해제를 요청

SetUserFocus

/** An event should return FReply::Handled().SetUserFocus( SomeWidget ) as a means of asking the system to set users focus to the provided widget*/
SLATECORE_API FReply& SetUserFocus(TSharedRef<SWidget> GiveMeFocus, EFocusCause ReasonFocusIsChanging = EFocusCause::SetDirectly, bool bInAllUsers = false)
{
	this->bSetUserFocus = true;
	this->FocusRecipient = GiveMeFocus;
	this->FocusChangeReason = ReasonFocusIsChanging;
	this->bReleaseUserFocus = false;
	this->bAllUsers = bInAllUsers;
	return Me();
}

• System에 User의 Focus를 제공된 Widget으로 설정하도록 요청

SetNavigation

/** An event should return FReply::Handled().SetNavigation( NavigationType ) as a means of asking the system to attempt a navigation*/
FReply& SetNavigation(EUINavigation InNavigationType, const ENavigationGenesis InNavigationGenesis, const ENavigationSource InNavigationSource = ENavigationSource::FocusedWidget)
{
	this->NavigationType = InNavigationType;
	this->NavigationGenesis = InNavigationGenesis;
	this->NavigationSource = InNavigationSource;
	this->NavigationDestination = nullptr;
	return Me();
}

/** An event should return FReply::Handled().SetNavigation( NavigationDestination ) as a means of asking the system to attempt a navigation to the specified destination*/
FReply& SetNavigation(TSharedRef<SWidget> InNavigationDestination, const ENavigationGenesis InNavigationGenesis, const ENavigationSource InNavigationSource = ENavigationSource::FocusedWidget)
{
	this->NavigationType = EUINavigation::Invalid;
	this->NavigationGenesis = InNavigationGenesis;
	this->NavigationSource = InNavigationSource;
	this->NavigationDestination = InNavigationDestination;
	return Me();
}

• System에 지정된 대상으로의 Navigation을 시도하도록 요청

When would we set FReply?

• 예를 들어 특정 Key Input으로 Widget Focus를 설정하거나, 지워야 한다고 가정해보자.
• 보통은 FSlateInputApplication에서 Key Input Handler 관련 함수를 직접 호출할 것이다.
  • 이 방식은 모든 경우에, 특히 Input Routing을 사용할 때 작동하지 않을 수 있다.
  • 현재 Widget에서 Input이 처리되는 동안 Focus 변경/지우기가 발생할 수 있기 때문이다.
• 이를 대신하여 Input이 완전히 처리되고 나서 발생되는 FReply를 사용하는 것이 좋다.
• 과거에는 FReply API가 제어 또는 노출되는 상태일 때에는 FReply만 사용 하도록 하였다.
  • 하지만 이 방식은 너무 제한적이라 위와 같이 언제든 사용 가능하도록 바뀌었다.
  • 현재 버전에서 기존의 가이드 이상으로 강력히 권장되는 방식이다.

Customize Navigation

Navigation Config

/**
 * Navigation context for event
 */
UENUM(BlueprintType)
enum class EUINavigation : uint8
{
	/** Four cardinal directions*/
	Left,
	Right,
	Up,
	Down,

	/** Conceptual next and previous*/
	Next,
	Previous,

	/** Number of navigation types*/
	Num UMETA(Hidden),

	/** Denotes an invalid navigation, more important used to denote no specified navigation*/
	Invalid,
};

• Slate는 CommonUI 사용 여부와 무관하게 기본 Navigation을 지원한다.

/**
 * Sets the navigation config.  If you need to control navigation config dynamically, you
 * should subclass FNavigationConfig to be dynamically adjustable to your needs.
 */
SLATE_API void SetNavigationConfig(TSharedRef<FNavigationConfig> InNavigationConfig)
{
	NavigationConfig->OnUnregister();
	NavigationConfig = InNavigationConfig;
	NavigationConfig->OnRegister();

#if WITH_SLATE_DEBUGGING
	TryDumpNavigationConfig(NavigationConfig);
#endif // WITH_SLATE_DEBUGGING
}

• NavigationConfig를 설정하려면 FSlateApplication::NetNavigationConfig를 호출한다.
• 대체로 FNavigationConfig에서 파생된 Custom Navigation 구성을 할 때 이 함수를 호출한다.
  • 예를 들어 WASD로 UI라 상호작용 한다면 이 부분에서부터 시작하는게 좋다.

void FSlateUser::SetUserNavigationConfig(TSharedPtr<FNavigationConfig> InNavigationConfig)
{
	if (UserNavigationConfig)
	{
		UserNavigationConfig->OnUnregister();
	}

	UserNavigationConfig = InNavigationConfig;
	
	if (InNavigationConfig)
	{
		InNavigationConfig->OnRegister();
	}

#if WITH_SLATE_DEBUGGING
	FSlateApplication::Get().TryDumpNavigationConfig(UserNavigationConfig);
#endif // WITH_SLATE_DEBUGGING
}

• 또한 FSlateUser::SetUserNavigationConfig를 호출해 User 기반으로 Navigation 구성을 설정할 수도 있다.

Manually Control Navigation

• UMG에서 Widget을 선택하고 Details -> Navigation을 선택하면
  Navigation Event 발생 시 어떻게 될지 수동으로 지정할 수 있다.

UENUM(BlueprintType)
enum class EUINavigationRule : uint8
{
	/** Allow the movement to continue in that direction, seeking the next navigable widget automatically. */
	Escape,
	/** Move to a specific widget. */
	Explicit,
	/**
	 * Wrap movement inside this container, causing the movement to cycle around from the opposite side, 
	 * if the navigation attempt would have escaped.
	 */
	Wrap,
	/** Stops movement in this direction */
	Stop,
	/** Custom navigation handled by user code. */
	Custom,
	/** Custom navigation handled by user code if the boundary is hit. */
	CustomBoundary,
	/** Invalid Rule */
	Invalid
};

Activatable Widgets and Action Bind

Set Focus for Activatable Widget on Activation

UWidget* UCommonActivatableWidget::GetDesiredFocusTarget() const
{
	return NativeGetDesiredFocusTarget();
}

UWidget* UCommonActivatableWidget::NativeGetDesiredFocusTarget() const
{
	// Prioritize BP implementation of this function.
	UWidget* DesiredFocusTarget = BP_GetDesiredFocusTarget();

	if (!DesiredFocusTarget)
	{
		// BP didn't specify focus target, fallback to DesiredFocusWidget property on UserWidget.
		DesiredFocusTarget = GetDesiredFocusWidget();
	}

	return DesiredFocusTarget;
}

UWidget* UUserWidget::GetDesiredFocusWidget() const
{
	return DesiredFocusWidget.GetWidget();
}

• ActivatableWidget을 Activate할 때마다 GetDesiredFocusTarget이 호출된다.
  • 이 함수는 User Input 발생 시 Common UI가 Focus해야 할 Widget을 선택한다.
  • 해당 함수를 Customize 하지 않을 시 Common UI에서
    Widget이 Active/Inactive 할 때마다 Focus 할 위치를 파악하는데 어려울 수 있다.
  • 그러니 반드시 Customize를 하자.
• Lyra에서는 ActivatableWidget에서 원하는 Focus Target을 가져오는데 사용할 Method를 Enum Type으로 결정한다.
  • 이는 Focus 대상이 고정된 Async Method를 사용하는 경우에 권장된다.
  • 대부분의 Menu에서라던가.

Change when Input Action Fire Triggered

• Action Bind를 위해 FBindUIActionArgs를 생성할 때 KeyEvent를
  InputAction Event를 Trigger해야 할 Type으로 설정한다.

Console Variable Reference

Use With Enhanced Input

• Unreal Engine 5.2 이전 버전에서는 사용을 권장하지 않음.
  • Enhanced Input이 5.2버전 기준으로 테스트가 충분히 거치지 않음
• 주요 기능인 EnhancedInput의 PlayerMappableKeySettings가 아직 Experimental 단계임.
  • 적어도 Beta가 되기 전까지는 시도를 안 하는 편이 좋음.

필수 사항

• Common UI와 Enhanced Input을 모두 사용할 것
• ViewportClass가 CommonGameViewportClient나 그 하위 Class일 것
• CommonInputData에서 Accept/Back에 대한 Input Action이 등록되어 있을 것

설정법

• Project Settings -> Game -> Common Input Settings에서 Enable Enhanced Input Support를 체크

• Miscellaneous -> DataAsset을 선택해 CommonMappingContextMetadataInterface를 선택해 Asset 생성
  • 해당 Asset은 Common UI Input Data를 설정할 수 있는 Metadata Object를 제공한다.
  • 여기서 쓰이는 Nav Bar Priority는 Common UI와 동일한 개념이다.
  • 만약 기능이 필요하다면 CommonInputMetaData를 상속받아 확장 가능하다.
• 위와 같이 설정
  • Per Action Enhanced Input Metadata
    • 대응 될 InputAction BP
    • Action마다 Asset을 각자 만드는 대신,
      Per Action Enhanced Input Metadata를 사용해 한 Asset에서 여러 Action을 처리할 수 있다.
  • Is Generic Iput Action
    • true로 설정한 이유는 Common UI가 Input Action을 Broadcast하는 것을 방지하기 위함이다.
    • 만약 Generic InputAction이 아닌 InputAction에서 사용하고 싶다면 이 값을 해제하면 된다.
      • 이 경우, 해당 InputAction에는 Input을 Bind할 수 있다.

• InputAction에서 Player Mappable Key Settings에서 Metadata 필드를 설정한다.
  • 여기서 사용하는 Metadata는 위에서 만든 Asset이다.

• 이렇게 만들어진 InputAction은 Input을 받을 수 있는 Common UI에 연결해 사용할 수 있다.
  • CommonButtonBase
  • CommonActionWidget
    • UI가 아닌 InputAction의 Key를 표시할 수 있다.
  • CommonUIInputData
    • 여기서 Default Navigation Action이 정의된다.
• 만약 이 옵션이 보이지 않는다면 Project Settings에서 Enable Enhanced Input Support 옵션을 확인해보자.

• CommonActivatableWidget의 경우, Active 여부에 따라 적용/제거 될 IMC를 지정할 수 있다.
  • 더 좋은 구조를 위해 게임 IMC를 적용 할 때 Common UI IMC를 같이 적용할 것을 권장한다.

https://benui.ca/unreal/common-ui-intro/

https://benui.ca/unreal/common-ui-button/

https://x157.github.io/UE5/CommonUI/

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/using-the-common-bound-action-bar-in-unreal-engine

• Common UI에서 제공하는 class들에 대한 간단한 용도 설명
• 실질적인 코드는 Engine/Plugin/Runtime/CommonUI/Source/CommonUI/Public/ 경로에서 확인 가능

CommonUserWidget

• CommonUI에서 사용하는 BaseWidget

CommonActionWidget

• Platform에 따라 다르게 표현되는 Icon을 표시하고 이에 대한 Input Action을 처리하는 Widget

CommonActivatableWidgetSwitcher

• Lifetime 중에 Activate/Inactivate 될 수 있는 Widget
  • 하지만 이 외에 수정되거나 파괴되지는 않는다.
• 보통은 다음 기능을 제공한다.
  • 화면 상으로 빈번하게 사용되기 때문에 Construct/Destruct만으로 대응이 힘든 상황
    • Hierarchy에 미리 생성해두고 Active/Inactive를 조절하여 사용
    • ex) 모바일에서 조건부로 나타나는 입력 키
  • 현재 Widget에서 뒤로가기를 해야 하는 경우
    • 뒤로 가는 경로를 따라가는 경우
    • 모달을 닫는 경우
  • 이 Widget은 Hierarchy에서 Input을 Routing하는 ActivatableWidget Tree에서 하나의 Node로 작용한다.
• 해당 Class는 다음 기본 설정이 되어 있다.
  • 생성 시 자동으로 Activate되지 않는다.
  • 뒤로가기, 앞으로가기 동작을 수신하도록 등록되어 있지 않다.
  • 뒤로가기 Handler로 구분되어 있을 시, 뒤로가기 Action을 수신하면 자동으로 Deactivate된다.
• ActivatableWidget을 UI로부터 제거하는 것은 UWidget이 제거되지 않았더라도 항상 Widget을 Deactivate한다.
  • 이 때 AutoActivate가 가능하다면,
    기본 SWidget을 다시 생성하는 것만이 유일하게 다시 Widget을 Activate하는 방법이다.

CommonAnimatedSiwtcher

• CommonActivatableWidget 전용 Widget Switcher
• 관련 Animation을 Trigger 하는 기능을 제공한다.

CommonActivatableWidgetSwitcher

• CommonActivableWidgets의 기능을 보존하는 Animation Switcher
• 다른 Widget도 포함될 수 있다.

CommonBorder

• CommonUI Project에서 Default로 설정된 Border Style Template

CommonButtonBase

• CommonUI에서 제공하는 Customized Button
• Widget 전체를 Disable하지 않고 Click을 Disable 할 수 있다.

CommonCustomNavigation

• CommonUI에서 제공하는 Customized Border
• Custom Behavior로 Default Border Navigation을 대체할 수 있는 Event를 노출시킨다.

CommonTextBlock

• CommonUI에서 제공하는 Customized TextBlock
• 다음 기능들을 기본적으로 제공한다.
  • FX를 이용해 자동 스크롤링
  • Large Text
  • 더 많은 Styling Option 제공
  • Mobile 플랫폼에서의 Custom Scaling

CommonDateTimeTextBlock

• DateTime이나 TimeSpan을 직접 입력받아 날짜/시간 정보를 Text로 표시해주는 CommonTextBlock

CommonNumericTextBlock

• Numeric 값을 입력 받아 Text로 표시해주는 CommonTextBlock
• 다음 기능들을 제공한다.
  • 근사(반올림/올림/내림)
  • 숫자 표시
  • 퍼센티지 표시
  • 초 단위 표시
  • 거리 표시

CommonRichTextBlock

• CommonUI에서 제공하는 Customized RichTextBlock
• 다음 기능들을 제공한다.
  • Mobile 플랫폼에서의 Custom Scaling
  • 공간이 부족할 때 Icon만 표시하는 옵션

CommonUIRichTextData

• RichTextData를 구현하는 Class
• Project Settings -> Common UI Setting에서 등록할 수 있다.

CommonHardwareVisibilityBorder

• Platform이나 Input에 따라 Visbility를 조절하는 기능을 제공하는 CommonBorder

CommonHierarchicalScrollBox

• CommonUI에서 제공하는 Customized ScrollBox
• 임의의 Scroll이 가능한 Widget Collection
• 10~100개 정도를 표시하는데 적절하다.
• Virtualization을 제공하지 않는다.
  • Virtualization: List 등에서 화면에 표시되는 영역의 Widget만 Memory에서 들고 있는 기능

CommonLazyImage

• CommonUI에서 제공하는 Customized Image
• Image Resource가 Load되지 않을 때 미리 지정 된 Unloaded Image를 표시해주는 Widget
• SLoadGuard의 또 다른 Wrapper이지만, Image Loading과 Loading 중 Throbber만 관리한다.
• 만약 이 Class가 Text를 표시하도록 바뀌면, 기본적으로 CoreStyle을 유지하게 된다.

CommonLazyWidget

• Widget이 Load되지 않을 때 미리 지정된 Unloaded Widget을 표시해주는 Widget

CommonListView

• CommonUI에서 제공하는 Customized ListView

CommonNativeListItem

• 모든 UMG ListView Class에서 BaseItem으로 사용될 수 있는 Native non-UObject Item

CommonLoadGuard

• CommonUI에서 제공하는 Customized ContentWidget
  • Border와 비슷하게 동작한다.
  • 필요한 Contents가 Load되거나 모종의 준비가 끝날 때까지 기본 Contents를 숨기고
    Loading Spinner와 Message를 출력할 수 있다
• GuardAndLoadAsset 함수를 사용하면 자신이 Load 될 때까지 Loading 상태를 자동으로 표시할 수 있다.
• 수동으로 Guard의 Loading State를 설정할 수 있다.
  • 예를 들어 Async Backend call이 종료될 때까지 대기 한다던가.

CommonPoolableWidgetInterface

• WidgetFactory가 Widget Object 재사용을 구현할 경우에 Widget Pool 기능을 제공하는 Interface

CommonRotator

• 주어진 Text Label을 순회하는 기능을 제공하는 CommonButtonBase
  • Slide Banner처럼 Text를 Shift 할 수 있음

CommonTabListWidgetBase

• Selectable Tab 기능을 제공하는 Base Class
• 다음 기능들을 제공한다. 
  • 연관된 Tab을 Activate
  • 연결된 Switchdr에서 연관된 Tab을 표시해준다.

CommonTileView

• CommonUI에서 제공하는 Customized TileView
• 다음 기능들을 제공한다.
  • Consol에서 Focus Navigation에 특화 됨.
  • Touch로 Focus되지 않을 경우에 Scroll을 제공

CommonTreeView

• CommonUI에서 제공하는 TreeView
• 다음 기능들을 제공한다.
  • Consol에서 Focus Navigation에 특화 됨.
  • Touch로 Focus되지 않을 경우에 Scroll을 제공

CommonVideoPlayer

• CommonUI에서 제공하는 Media 재생 용 Widget

CommonVisibilitySwitcher

• CommonUI에서 제공하는 Customized Overlay
  • Child Widget들의 Visibility를 Toggle하여 한번에 1개의 Widget만 표시하는 Siwtcher의 Base Class
  • 표시되는 Widget이 ActivatableWidget인 경우, 해당 Widget을 Activate한다.

CommonVisibilitySwitcherSlot

• CommonUI에서 제공하는 Customized OverlaySlot

CommonvisualAttachment

• CommonUI에서 제공하는 Customized SizeBox
• Widget을 다른 Widget에 Zero-Size로 부착할수 있도록 한다.
  • 예를 들어 Icon을 Label에 추가하되, Label의 사이즈가 변하지 않도록 한다던가

CommonWidgetCarousel

• CommonUI에서 제공하는 Customized PanelWidget
• 최대 하나의 Widget만 표시되는 Widget
  • Carousel로 미루어 보아 SlideBanner의 Widget 버전으로 추정

CommonWidgetCarouselNavBar

• CommonWidgetCarousel의 Navigation control을 담당하는 Widget

CommonButtonTableRow

• CommonButtonBase를 인식할 수 있는 CommonUI 버전의 Object Table Row
• Mouse Event를 직접적으로 처리하는 대신, 그 자체가 Button이 되어 Event에 반응한다.

CommonHierarchicalScrollBox

• CommonUI에서 제공하는 Customized ScrollBox
• 임의의 숫자의 Widget을 Scroll 할 수 있다.

CommonTileView

• CommonUI에서 제공하는 Customzied TileView

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/common-ui-plugin-for-advanced-user-interfaces-in-unreal-engine

https://velog.io/@yoo06/%EC%96%B8%EB%A6%AC%EC%96%BC-%EC%97%94%EC%A7%84-UE5-Common-UI-%EC%95%8C%EC%95%84%EB%B3%B4%EA%B8%B0

https://ctdidier27.medium.com/common-ui-plugin-ue5-b12050bf1fc0

https://dev.epicgames.com/community/learning/tutorials/BKJ7/unreal-engine-common-ui-tutorial-create-cross-platform-ui-easily-with-this-new-ue5-system

• 화면을 그대로 유지하면서 Overlay 되는 UI를 노출하고, 화면입력을 막고 싶은 경우
• 플랫폼 별로 UI Element를 다르게 관리하고 싶을 때
• Popup들의 버튼을 누를 시 UI가 특정 상태가 되도록 흐름을 제어하고 싶을 때
• 키보드나 콘솔 컨트롤러의 방향키로 UI 선택을 이동시키고 싶을 때(Cardinal Navigation)

핵심 개념

Input Routing

• Selective Interaction을 구현하기 위해 채택한 방식
  • 입력을 수신하는 조건과 시기를 컨트롤 할 수 있다.
• 예를 들어, 서로 다른 Widget에 버튼 별 Input을 분배해서 배치할 수 있다.
  • 이는 입력이 각 Widget에서 처리되는 것이 아니라 공용 Class에 전달되어 일괄처리 되기 때문이다.

Node

• Common UI는 Widget을 Node로 변환해 Visual Hierarchy에 따라 상위에 Rendering 된 Widget의 입력을 Route한다.

• 몇 가지 예외를 제외하고, 대부분의 Common UI는 Slate의 Hierarchy와 동일하게 구성된다.
  • 각 Tree는 Viewport에 직접 배치 된 Widget을 Root Node로,
    Button과 같은 개별 UI Element를 Leaf Node로 취급하여 구성된다.
• Common UI는 Tick당 1번씩 다른 Tree보다 상단에 Render 된 Tree를 탐색해 Root Node로 Input을 Route한다.
• 그럼 Root Widget은 Input을 처리할 수 있는 첫번째 Leaf Node에 입력을 전달한다.
• 입력을 전달 받은 Leaf Node는 이를 처리하거나, 필요하다면 다른 곳으로 재전달한다.

ActivatableWidget

• Common UI 중 Input 처리를 위해 Node로 변환되고, 이를 수신할 수 있는 Widget
  • Input 수신 시 Active 상태로 간주한다.
• Activatable Widget은 다음 기능을 제공한다.
  • Input 수신 가능 여부(Active/Inactive) 상태 토글
  • 같은 Tree 내 다른 Activatable Widget에 Input 전달
  • 뒤로가기 등 특정 상황에서 Inactivate
• 이 Widget을 이용해 현재 Input을 수신중인 Overlay UI가 닫힐 경우,
  적절한 Element로 복구해주는 기능을 작업할 수 있다.
  • Input은 항상 최상단에 Layer에만 Route 되기에 하단 Layer의 Widget도 문제 없이 Active 상태로 둘 수 있다.
  • 이 때 상단 Layer가 닫히면 자연스럽게 하단 Layer에 Input이 Route 된다.

사용법

Viewport Configure

• Edit -> Project Settings -> Engine -> General Settings으로 이동
• Game Viewport Client Class를 CommonGameViewportClient 혹은 이를 상속받은 Custom Class로 설정

Create InputActionDataTable

• 한가지 잊지 말아야 할 점이 있다.
  • CommonUI InputAction DataTable은 Project Setting, Advanced Input System에 사용하는 것과 무관하다.
  • 오직 UI Input 관리에만 사용된다.

• Content Browser 영역 우클릭 -> Miscellaneous -> CommonUI ActionInput Data Table선택

• 위와 같이 Row를 추가해 Input을 설정한다.

• 이렇게 추가된 InputAction은 CommonUI Widget에서 Mapping할 수 있다.
  • 위 사진은 CommonButtonBase의 Class Defaults에서 DataTable과 RowName을 통해
    InputAction을 Button에 Mapping 한 예시이다.
• 좀 더 용이하게 관리하려면 관련된 Action들을 하나의 DataTable에서 작업하여 그룹화 하는 것이 좋다.

CommonInputActionDataBase

USTRUCT(BlueprintType)
struct COMMONUI_API FCommonInputActionDataBase : public FTableRowBase
{
	GENERATED_BODY()

	FCommonInputActionDataBase();
	
	/** User facing name (used when NOT a hold action) */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "CommonInput")
	FText DisplayName;

	/** User facing name used when it IS a hold action */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "CommonInput")
	FText HoldDisplayName;

	/** Priority in nav-bar */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "CommonInput")
	int32 NavBarPriority = 0;

protected:
	/**
	* Key to bind to for each input method
	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	FCommonInputTypeInfo KeyboardInputTypeInfo;

	/**
	* Default input state for gamepads
	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	FCommonInputTypeInfo DefaultGamepadInputTypeInfo;

	/**
	* Override the input state for each input method
	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput", Meta = (GetOptions = "CommonInput.CommonInputBaseControllerData.GetRegisteredGamepads"))
	TMap<FName, FCommonInputTypeInfo> GamepadInputOverrides;

	/**
	* Override the displayed brush for each input method
	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	FCommonInputTypeInfo TouchInputTypeInfo;
};

CommonInputTypeInfo

USTRUCT(BlueprintType)
struct COMMONUI_API FCommonInputTypeInfo
{
	GENERATED_USTRUCT_BODY()

	FCommonInputTypeInfo();
private:
	/** Key this action is bound to	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	FKey Key;
public:

	/** Get the input type key bound to this input type, with a potential override */
	FKey GetKey() const;

	/** Get the input type key bound to this input type, with a potential override */
	void SetKey(FKey InKey)
	{
		Key = InKey;
	};

	/** EInputActionState::Enabled means that the state isn't overriden and the games dynamic control will work */
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	EInputActionState OverrrideState;

	/** Enables hold time if true */
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	bool bActionRequiresHold;

	/** The hold time in seconds */
	UPROPERTY(EditAnywhere, Category = "CommonInput", meta = (EditCondition = "bActionRequiresHold", ClampMin = "0.0", UIMin = "0.0"))
	float HoldTime;

	/**
	*	Time (in seconds) for hold progress to go from 1.0 (completed) to 0.0.
	*	If the hold interaction was interrupted, then hold progress starts to roll back decreasing its value.
	*	Set to 0.0 to disable the rollback functionality.
	*/
	UPROPERTY(EditAnywhere, Category = "CommonInput", meta = (EditCondition = "bActionRequiresHold", ClampMin = "0", UIMin = "0", ClampMax = "10.0", UIMax = "10"))
	float HoldRollbackTime;
	
	/** Override the brush specified by the Key Display Data  */
	UPROPERTY(EditAnywhere, Category = "CommonInput")
	FSlateBrush OverrideBrush;
};

EInputActionState

UENUM(BlueprintType)
enum class EInputActionState : uint8
{
	/** Enabled, will call all callbacks */
	Enabled,
	/** Disabled, will call all the disabled callback if specified otherwise do nothing */
	Disabled,
	
	/** The common input reflector will not visualize this but still calls all callbacks. NOTE: Use this sparingly */
	Hidden,
	
	/** Hidden and disabled behaves as if it were never added with no callbacks being called */
	HiddenAndDisabled,	
};

Default Navigation Action Configure

• Unreal Engine에서 Native Navigation을 지원하지만,
  CommonUI을 사용하면 CommonUIInputData를 기반으로 한 별도의 Navigation이 정의되어야 한다.

• Create New Plueprint Class에서 CommonUIInputData를 선택해 BP 생성
  • 생성한 파일 내에 CommonUI InputActionDataTable과 Row를 지정하여 Navigation을 지정
  • HoldData의 경우 CommonUIHoldInputData를 기반으로 신규 BP를 생성한 뒤, 해당 파일을 연결해줘야 한다.
• Click Action
  • 버튼이나 기타 상호작용 가능한 Element를 Highlight 할 때 Mouse Click을 대체
• Back Action
  • 현재 Menu에서 이전 Menu로 이동할 때 공통으로 사용

• Project Settings -> Game -> Common Input Settings의 InputData에 연결한다.
• 설정 시, 지정된 Asset을 Default Navigation에 사용한다.

Bind Controller Data per Platform

• Controller Data Asset은 Key-Action을 UI Elemnt에 연결해준다.
  • 각 Controller Data Asset은 Input Type, Gamepad, Platform과 연관되어 있다.
• CommonUI는 이 정보를 이용해 현재 Platform과 Input Type을 기반으로
  올바른 Platform 별 UI Element를 자동으로 사용한다.
  • 이를 통해 다수의 Input Type이나 고유한 Gamepad를 지원하는 Platform에서
    User Input을 올바른 GamePad에 전달하거나, Runtime에서 UI Elemnt를 교체할 수도 있다.

• Create New Blueprint Class에서 CommonInputBaseControllerData를 선택해 생성

• 생성한 모든 Controller Data Asset은
  Project Settings -> Game -> Common Input Settings의 Platform Input에 추가되어야 한다.
  • Platform Input에서 입력하는 Default Gamepad Name은
    Controller Data Asset들의 Gamepad Name 필드들로만 입력되어야 한다.
  • 이 값이 일치하지 않으면 Controller Data를 인식하지 못하고 Icon이 표시되지 않는다.
• 보통은 한 Platform의 Controller Data Array에 여러 개의 Gamepad Data를 작성해 다양한 컨트롤러를 지원한다.
  • 만약 별도의 Controller에 대한 게임플레이 지원을 해야 한다면,
    Gamepad Data를 새로 작성해 Controller Data에 추가하면 된다.

CommonInputBaseControllerData

/* Derive from this class to store the Input data. It is referenced in the Common Input Settings, found in the project settings UI. */
UCLASS(Abstract, Blueprintable, ClassGroup = Input, meta = (Category = "Common Input"))
class COMMONINPUT_API UCommonInputBaseControllerData : public UObject
{
	GENERATED_BODY()

public:
	virtual bool NeedsLoadForServer() const override;
	virtual bool TryGetInputBrush(FSlateBrush& OutBrush, const FKey& Key) const;
	virtual bool TryGetInputBrush(FSlateBrush& OutBrush, const TArray<FKey>& Keys) const;

	virtual void PreSave(FObjectPreSaveContext ObjectSaveContext) override;
	virtual void PostLoad() override;

private:
#if WITH_EDITORONLY_DATA
	UPROPERTY(Transient, EditAnywhere, Category = "Editor")
	int32 SetButtonImageHeightTo = 0;
#endif

public:
	UPROPERTY(EditDefaultsOnly, Category = "Default")
	ECommonInputType InputType;
	
	UPROPERTY(EditDefaultsOnly, Category = "Gamepad", meta=(EditCondition="InputType == ECommonInputType::Gamepad", GetOptions = GetRegisteredGamepads))
	FName GamepadName;

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad", meta = (EditCondition = "InputType == ECommonInputType::Gamepad"))
	FText GamepadDisplayName;

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad", meta=(EditCondition="InputType == ECommonInputType::Gamepad"))
	FText GamepadCategory;

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad", meta = (EditCondition = "InputType == ECommonInputType::Gamepad"))
	FText GamepadPlatformName;

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad", meta=(EditCondition="InputType == ECommonInputType::Gamepad"))
	TArray<FInputDeviceIdentifierPair> GamepadHardwareIdMapping;

	UPROPERTY(EditDefaultsOnly, Category = "Display")
	TSoftObjectPtr<UTexture2D> ControllerTexture;

	UPROPERTY(EditDefaultsOnly, Category = "Display")
	TSoftObjectPtr<UTexture2D> ControllerButtonMaskTexture;

	UPROPERTY(EditDefaultsOnly, Category = "Display", Meta = (TitleProperty = "Key"))
	TArray<FCommonInputKeyBrushConfiguration> InputBrushDataMap;

	UPROPERTY(EditDefaultsOnly, Category = "Display", Meta = (TitleProperty = "Keys"))
	TArray<FCommonInputKeySetBrushConfiguration> InputBrushKeySets;

	UFUNCTION()
	static const TArray<FName>& GetRegisteredGamepads();

private:
#if WITH_EDITOR
	virtual void PostEditChangeProperty(struct FPropertyChangedEvent& PropertyChangedEvent) override;
#endif
};

UENUM(BlueprintType)
enum class ECommonInputType : uint8
{
	MouseAndKeyboard,
	Gamepad,
	Touch,
	Count
};

USTRUCT()
struct FInputDeviceIdentifierPair
{
	GENERATED_BODY()

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad")
	FName InputDeviceName;

	UPROPERTY(EditDefaultsOnly, Category = "Gamepad")
	FString HardwareDeviceIdentifier;
};

USTRUCT(Blueprintable)
struct COMMONINPUT_API FCommonInputKeyBrushConfiguration
{
	GENERATED_BODY()

public:
	FCommonInputKeyBrushConfiguration();

	const FSlateBrush& GetInputBrush() const { return KeyBrush; }

public:
	UPROPERTY(EditAnywhere, Category = "Key Brush Configuration")
	FKey Key;

	UPROPERTY(EditAnywhere, Category = "Key Brush Configuration")
	FSlateBrush KeyBrush;
};

USTRUCT(Blueprintable)
struct COMMONINPUT_API FCommonInputKeySetBrushConfiguration
{
	GENERATED_BODY()

public:
	FCommonInputKeySetBrushConfiguration();

	const FSlateBrush& GetInputBrush() const { return KeyBrush; }

public:
	UPROPERTY(EditAnywhere, Category = "Key Brush Configuration", Meta = (TitleProperty = "KeyName"))
	TArray<FKey> Keys;

	UPROPERTY(EditAnywhere, Category = "Key Brush Configuration")
	FSlateBrush KeyBrush;
};

Common UI widget

• Common UI Plugin에서 제공하는 Widget
• 기존에 자주 사용하는 Widget의 기능을 거의 그대로 제공
  • 다만 Base UMG Widget Style 기능은 제공하지 않는다.
  • 대신 Common Style Asset을 참조해 다수의 Menu와 HUD에 일관된 Style을 적용할 수 있다.
  • Styple Asset을 변경하면 모든 Common UI Widget에 효과가 나타난다.
• 자세한 지원 Widget 항목에 대해서는 아래 개별 포스트 참고
  • https://redchiken.tistory.com/394

Common Style Asset

• Create New Blueprint Class를 통해 사진과 같이 Common Style BP를 생성한다.

• 생성한 Common Style BP의 Detail 항목에 필요한 정보를 채워놓는다.

• 생성한 Common Style BP는 이를 필요로 하는 다른 CommonUI에 연결하여 적용한다.
  • 위 사진의 경우, Common Button의 Widget Element인 Common Text에 CommonTextStyle을 적용하였다.

• 생성된 Common Style BP는 Project Settings -> Plugins -> Common UI Editor의 Template Styles에 할당할 수 있다.
  • 그럼 수동으로 설정되지 않은 Common BP에서 Template Style을 자동으로 사용하게 된다.

• 이와 같은 맥락으로, Project Settings -> Plugins -> Common UI Framework에서
  몇 가지 Global Assset을 추가로 지원한다.
  • Loading 화면에서 쓰는 Default Throbber Material
  • Load되지 않은 UI Asset에 표시되는 Default Image Resource Object 등

Technical Guide

• Designer나 Artist는 크게 신경 안 써도 되지만 Tech는 알아둬야 할 코드 영역 내용
• https://redchiken.tistory.com/395

FAQ

• Design이나 구조적으로 자주 나오는 질문에 대한 모음
• https://redchiken.tistory.com/396

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/umg-viewmodel?application_version=5.3#heading=h.qln36ehrtib7

https://harrisbarra.medium.com/ue5-mvvm-36907bdb34d9

https://dev.epicgames.com/community/learning/talks-and-demos/pw3Y/unreal-engine-umg-viewmodels-building-more-robust-and-testable-uis-using-mvvm-unreal-fest-2023?locale=ko-kr

https://miltoncandelero.github.io/unreal-viewmodel

WorkFlow

Programmer

• View Model 자체를 생성, Build
  • View Model은 UI에서 사용할 수 있는 변수들을 포함 함.
• Application의 코드와 결합

Designer

• View Binding 패널을 사용해 UI에서 ViewModel의 변수에 Bind
• UMG Widget에 ViewModel 추가 시 다음 기능들을 이용할 수 있다.
  • Access
  • 함수 호출
  • 변수 업데이트
  • 변수 업데이트에 대한 Push 이벤트 Delegate
    • 이는 변수 값이 수정 될 때 등록된 Widget만 업데이트 하기 때문에 Attribute Bind보다 훨씬 효과적이다.
    • 동시에 시간 설정을 수동으로 구현 할 필요도 없어 Event Driven UI Framework의 이점을 살리기 좋다.

Config

View Model

역할

• UI에 필요한 변수의 Manifest 관리
• UI와 Application의 기타 요소간 Communication을 위한 매개체

UI가 변수를 인지해야 하는 경우

• ViewModel에 변수 추가
• Widget에 ViewModel 추가
• Widget의 Field를 ViewModel에 Bind

변수를 업데이트 해야 하는 경우

• ViewModel의 Reference를 가지고 있다면 언제든 직접 접근하여 수정
• 변경 된 변수에 Bind된 Widget을 Notify하고 업데이트

ViewModel in BP

Creation

• Content Borwser를 우클릭하여 New Blueprint를 통해 ViewMode BP 생성
  • ViewModel은 Widget이 아니기 때문에 User Interface에 없고 일반 BP 생성 방식을 통해야 한다.

FieldNotify Variable

• BP의 변수 옆에 종 모양 UI가 FieldNotify 활성화 여부이다.

• FieldNotify가 활성화 된 변수의 Set은 BP 라벨의 이름이 Set w/ Broadcast로 지정된다.
  • 위와 같이 설정 된 변수들은 값이 변경될 때마다 Bind된 Widget에 Update 메시지를 전송한다.

FieldNotify Function

• Function 역시 FieldNotify로 취급 될 수 있으나 변수에 비해 몇 가지 조건을 요구한다.
  • Pure Function일 것
  • Const 마킹이 되어 있을 것
  • 하나의 값만 반환할 것
  • Input Parameter가 없을 것
• FieldNotify를 사용한다면 가급적 값을 반환하는 목적만 있는 Getter 생성은 지양해야 한다.
  • 차후에 Widget을 Bind하려 할 때 추가되는 Getter 함수와 햇갈릴 수 있다.

Bind FieldNotify to Another FieldNotify

• 만약 FieldNotify 변수가 변경 되는 경우, 그 변수에 FieldNotify Function을 Bind 해줘야 한다.
  • 이는 비단 Function 뿐 아니라 FieldNotify 변수에 다른 FieldNotify 변수를 Bind할 수도 있다.
  • FieldNotify에 다른 FieldNotify 변수나 함수가 Bind되어 있다면,
    변수가 수정될 때 Bind 된 함수의 실행은 물론 Bind된 변수에 Bind 된 Widget에까지 Update가 된다.

ViewModel in C++

Creation

#pragma once

#include "CoreMinimal.h"
#include "MVVMViewModelBase.h"
#include "MyMVVMViewModelBase.generated.h"

UCLASS()
class MYTEST_API UMyMVVMViewModelBase : public UMVVMViewModelBase
{
	GENERATED_BODY()
	
};

• 기본적인 ViewModel은 UMVVMViewModelBase를 상속 받아 생성할 수 있다.

class INotifyFieldValueChanged : public IInterface
{
	GENERATED_BODY()

public:
	// using "not checked" user policy (means race detection is disabled) because this delegate is stored in a container and causes its reallocation
	// from inside delegate's execution. This is incompatible with race detection that needs to access the delegate instance after its execution
	using FFieldValueChangedDelegate = TDelegate<void(UObject*, UE::FieldNotification::FFieldId), FNotThreadSafeNotCheckedDelegateUserPolicy>;

public:
	/** Add a delegate that will be notified when the FieldId is value changed. */
	virtual FDelegateHandle AddFieldValueChangedDelegate(UE::FieldNotification::FFieldId InFieldId, FFieldValueChangedDelegate InNewDelegate) = 0;

	/** Remove a delegate that was added. */
	virtual bool RemoveFieldValueChangedDelegate(UE::FieldNotification::FFieldId InFieldId, FDelegateHandle InHandle) = 0;

	/** Remove all the delegate that are bound to the specified UserObject. */
	virtual int32 RemoveAllFieldValueChangedDelegates(const void* InUserObject) = 0;

	/** Remove all the delegate that are bound to the specified Field and UserObject. */
	virtual int32 RemoveAllFieldValueChangedDelegates(UE::FieldNotification::FFieldId InFieldId, const void* InUserObject) = 0;

	/** @returns the list of all the field that can notify when their value changes. */
	virtual const UE::FieldNotification::IClassDescriptor& GetFieldNotificationDescriptor() const = 0;

	/** Broadcast to the registered delegate that the FieldId value changed. */
	virtual void BroadcastFieldValueChanged(UE::FieldNotification::FFieldId InFieldId) = 0;
};

• 하지만 이보다 더 근본적으로, INotifyFieldValueChanged만을 Implement 하여 생성할 수도 있다.

/** Base class for MVVM viewmodel. */
UCLASS(Blueprintable, Abstract, DisplayName="MVVM Base Viewmodel")
class MODELVIEWVIEWMODEL_API UMVVMViewModelBase : public UObject, public INotifyFieldValueChanged
{
	GENERATED_BODY()

public:
	//~ Begin INotifyFieldValueChanged Interface
	virtual FDelegateHandle AddFieldValueChangedDelegate(UE::FieldNotification::FFieldId InFieldId, FFieldValueChangedDelegate InNewDelegate) override final;
	virtual bool RemoveFieldValueChangedDelegate(UE::FieldNotification::FFieldId InFieldId, FDelegateHandle InHandle) override final;
	virtual int32 RemoveAllFieldValueChangedDelegates(const void* InUserObject) override final;
	virtual int32 RemoveAllFieldValueChangedDelegates(UE::FieldNotification::FFieldId InFieldId, const void* InUserObject) override final;
	virtual const UE::FieldNotification::IClassDescriptor& GetFieldNotificationDescriptor() const override;
	virtual void BroadcastFieldValueChanged(UE::FieldNotification::FFieldId InFieldId) override;
	//~ End INotifyFieldValueChanged Interface

/*etc*/
};

Sum of Code

• C++에서 ViewModel을 구성하는 방법은 대략 다음과 같다.

UCLASS(BlueprintType)
class UVMCharacterHealth : public UMVVMViewModelBase
{
GENERATED_BODY()

private:
UPROPERTY(BlueprintReadWrite, FieldNotify, Setter, Getter, meta=(AllowPrivateAccess))
    int32 CurrentHealth;

    UPROPERTY(BlueprintReadWrite, FieldNotify, Setter, Getter, meta=(AllowPrivateAccess))
    int32 MaxHealth;

public:
    void SetCurrentHealth(int32 NewCurrentHealth)
    {
        if (UE_MVVM_SET_PROPERTY_VALUE(CurrentHealth, NewCurrentHealth))
        {
            UE_MVVM_BROADCAST_FIELD_VALUE_CHANGED(GetHealthPercent);
        }
    }

    void SetMaxHealth(int32 NewMaxHealth)
    {
        if (UE_MVVM_SET_PROPERTY_VALUE(MaxHealth, NewMaxHealth))
        {
            UE_MVVM_BROADCAST_FIELD_VALUE_CHANGED(GetHealthPercent);
        }

    }

    int32 GetCurrentHealth() const
    {
        return CurrentHealth;
    }

    int32 GetMaxHealth() const
    {
        return MaxHealth;
    }

public:

    UFUNCTION(BlueprintPure, FieldNotify)

    float GetHealthPercent() const
    {
        if (MaxHealth != 0)
        {
            return (float) CurrentHealth / (float) MaxHealth;
        }
        else
            return 0;
    }

};

FieldNotify Variable

• FieldNotify 변수를 선언하려면 UPROPERTY에서 다음 지정자들을 지정해야 한다.

• FieldNotify를 선언하지 않은 경우 Onetime,
  즉 변수가 최초로 변경될 때에만 Notify가 발생하고 그 이후에는 발생하지 않는다.
• Setter와 Getter는 필요에 따라 추가한다.
  • 단, 추가하지 않으면 해당 동작에 대한 연산은 해당 Class는 물론 하위 Class에서도 수행할 수 없다.
  • Getter/Setter은 Bind 된 Function 실행이나 FieldNotify Update 외에 변수값을 얻기 전에 연산을 해야 하는 경우에도 적절하다.
• Getter/Setter함수는 UFUNCTION으로 생성할 경우 BP에서 상당히 많은 목록을 생성하기에 이를 지양하는 것이 좋다.
  
  • UPROPERTY에서 이미 FieldNotify의 Get/Set에 연결을 해준 상태다.
• Unreal Engine은 FiendNotify 변수에 대한 Getter/Setter 함수 호출을 강제하지 않는다.
  • 사용자 귀책 실수를 줄이고 싶다면 접근제어자를 조절하는 것이 필요하다.
• BP에서는 FieldNotify 변수가 변경될 때 Bind된 FieldNotify 변수나 함수가 자동으로 Update되지만.
  C++로 작업한다면 이들을 직접 호출해줘야 한다.

FieldNotify Function

• FieldNotify Function은 다음 조건을 만족해야 한다.
  • UFUNCTION에서 BlueprintPure, FieldNotify 지정자 선언
  • Parameter가 없어야 함
  • const 선언이 되어 있어야 함
  • out 인자 없이 단일 값을 반환해야 함.
• Widget이 특정 변수에 Bind 되어 있으면서 동시에 값을 직접 사용하지 않고 연산을 거쳐야 하는 경우에 유용하다.
  • 일종의 임시 변수 생성

FieldNotify Macro

/** After a field value changed. Broadcast the event. */
#define UE_MVVM_BROADCAST_FIELD_VALUE_CHANGED(MemberName) \
	BroadcastFieldValueChanged(ThisClass::FFieldNotificationClassDescriptor::MemberName)

/** If the property value changed then set the new value and notify. */
#define UE_MVVM_SET_PROPERTY_VALUE(MemberName, NewValue) \
	SetPropertyValue(MemberName, NewValue, ThisClass::FFieldNotificationClassDescriptor::MemberName)

/** Use this version to set property values that can't be captured as a function arguments (i.e. bitfields). */
#define UE_MVVM_SET_PROPERTY_VALUE_INLINE(MemberName, NewValue) \
	[this, InNewValue = (NewValue)]() { if (MemberName == InNewValue) { return false; } MemberName = InNewValue; BroadcastFieldValueChanged(ThisClass::FFieldNotificationClassDescriptor::MemberName); return true; }()

Add ViewModel to Widget

• Widget을 생성하고 Window->Viewmodels항목을 선택하면 다음 창이 뜬다.

• 해당 창에서 미리 만든 ViewModel을 선택하면 된다.
• ViewModel은 여러 개 등록 할 수 있다.
  • 그 말은 Widget과 ViewModel의 관계는 1:1이 아니라 다:다라는 의미이다.

Initialize ViewModel

• ViewModel을 처음 추가하면 위와 같은 Noti를 볼 수 있다.
  • 이는 현재 Widget에서 등록된 ViewModel에 Bind가 없기에 굳이 Initialize를 하지 않겠다는 의미이다.
  • View Binding에서 Bind를 추가해주면 관계가 생성되며 자동으로 Instance가 생성된다.

Create Instance

• Widget Instance 별로 각각 새로운 ViewModel Instance를 자동 생성
  • 동일한 Widget이 Viewport 상 여러 개 존재하더라도
    하나의 변수를 수정하면 그 ViewModel에 해당하는 Widget만 Update 된다.
  • 이와 동일하게, 여러 개의 서로 다른 Widget을 생성할 때에도 다른 Widget의 정보 변경을 인지하지 못한다.
• C++의 Call-back 초기화 다음, 혹은 BP의 Call-back 초기화 도중에 ViewModel을 할당할 수 있다.
  • ViewModel이 설정되지 않으면 새 Instance만 생성한다.
  • ViewModel은 PreConstruct와 Construct 사이에 생성된다.

Manual

• 코드 상 특정 위치에서 Instance를 생성하고 Widget에 할당하는 방식
  • Widget은 Reference를 가지지만, 할당되기 전까지는 Null 값을 갖는다.

• Create Widget 노드에서 생성 시 ViewModel을 할당할 수도 있다.
• ViewModel을 할당하면 Widget에 대한 Reference를 구하지 않고 UI를 Update 할 수 있다.
  • 이 방법을 통해 UI가 하나의 Actor Class로부터
    서로 다른 다수의 Widget에 동일한 ViewModel을 할당할 수 있게 된다.

Global Viewmodel Collection

• MVVMSubsystem에서 Global로 Access 할 수 있는 ViewModel 목록

UCLASS(DisplayName="Viewmodel Engine Subsytem")
class MODELVIEWVIEWMODEL_API UMVVMSubsystem : public UEngineSubsystem
{
	GENERATED_BODY()

public:
	//~ Begin UEngineSubsystem interface
	virtual void Initialize(FSubsystemCollectionBase& Collection) override;
	virtual void Deinitialize() override;
	//~ End UEngineSubsystem interface

	UFUNCTION(BlueprintCallable, Category = "Viewmodel", meta = (DisplayName = "Get View From User Widget"))
	UMVVMView* K2_GetViewFromUserWidget(const UUserWidget* UserWidget) const;

	static UMVVMView* GetViewFromUserWidget(const UUserWidget* UserWidget);

	UFUNCTION(BlueprintCallable, Category = "Viewmodel")
	bool DoesWidgetTreeContainedWidget(const UWidgetTree* WidgetTree, const UWidget* ViewWidget) const;

	/** @return The list of all the AvailableBindings that are available for the Class. */
	UFUNCTION(BlueprintCallable, Category = "Viewmodel", meta = (DisplayName = "Get Available Bindings"))
	TArray<FMVVMAvailableBinding> K2_GetAvailableBindings(const UClass* Class, const UClass* Accessor) const;

	static TArray<FMVVMAvailableBinding> GetAvailableBindings(const UClass* Class, const UClass* Accessor);

	/**
	 * @return The list of all the AvailableBindings that are available from the SriptStuct.
	 * @note When FMVVMAvailableBinding::HasNotify is false, a notification can still be triggered by the owner of the struct. The struct changed but which property of the struct changed is unknown.
	 */
	static TArray<FMVVMAvailableBinding> GetAvailableBindingsForStruct(const UScriptStruct* Struct);

	static TArray<FMVVMAvailableBinding> GetAvailableBindingsForEvent(const UClass* Class, const UClass* Accessor);

	/** @return The AvailableBinding from a BindingName. */
	UFUNCTION(BlueprintCallable, Category = "Viewmodel", meta = (DisplayName = "Get Available Binding"))
	FMVVMAvailableBinding K2_GetAvailableBinding(const UClass* Class, FMVVMBindingName BindingName, const UClass* Accessor) const;

	static FMVVMAvailableBinding GetAvailableBinding(const UClass* Class, FMVVMBindingName BindingName, const UClass* Accessor);

	/** @return The AvailableBinding from a field. */
	static FMVVMAvailableBinding GetAvailableBindingForField(UE::MVVM::FMVVMConstFieldVariant Variant, const UClass* Accessor);

	static FMVVMAvailableBinding GetAvailableBindingForEvent(UE::MVVM::FMVVMConstFieldVariant FieldVariant, const UClass* Accessor);

	static FMVVMAvailableBinding GetAvailableBindingForEvent(const UClass* Class, FMVVMBindingName BindingName, const UClass* Accessor);
};

• Option과 같이 UI를 통해 Access되어야 하는 변수 처리에 이상적이다.

Property Path

Access ViewModel Variable

• Widget 에 ViewModel을 할당하면 BP에서 Widget의 Property를 통해 거꾸로 변수에 Access 할 수 있다.
  • 물론 이는 Viewmodel 옵션에 따라 다르긴 하다.

Work with Array

• 일반적으로 Array는 ViewModel에서 Access 할 수 없다.
  • 이를 위해서는 ViewModel 자체적으로 배열을 직접 추가/삭제/탐색 할 수 있는 FieldNoitfy 함수를 만들어야 한다.
• 다만 ListView, TreeView, TileView 등과는 함께 Array를 사용할 수 있다.
  • 이 경우, Element가 Array에 추가/제거/이동 될 경우에 Notify를 해줘야 한다.

View Binding

Add to Widget

Drag and Drop

• ViewModel에서 Widget에 Bind할 변수나 함수를 클릭하고 Bind 할 영역의 Bind 드롭다운을 드래그

Detail Panel

• Accessibility -> Override Accessibility 항목 오른쪽의 Bind 드롭다운을 눌러 필요한 FieldNotify Bind

• 이 방식은 기존의 Property Binding과 혼동할 수 있는데, 이를 막아주는 옵션이 존재한다.
  • Project Settings -> Editor -> Widget Designer(Team) -> Property Binding Rule을 Prevent로 설정
  • 이 설정을 해주면 기존 Property를 Widget의 Parameter에 Binding하는 옵션이 제거된다.

• Plugin -> Model View ViewModel -> Allow Binding from Detail View를 비활성화 하면
  ViewModel에 대한 Detail 패널 Binding도 비활성화 할 수 있다.
  • 이 설정을 쓰더라도 View Binding Menu를 통해 여전히 Bind를 할 수 있다.

View Binding Menu

• UMG Designer -> Window -> View Binding 선택

• Add Widget을 통해 View Binding 목록에 추가하고 Bind 진행

Configure

Select Target Widget

• View Binding을 추가 할 Widget 선택

Create View Binding Entry

• Target Widget 하위에 있는 개별 Property마다 별도의 Bind를 걸 수 있다.
  • 물론 하나의 Property에 여러 Bind를 걸 수도 있다.

Select Widget Property

• Target Widget의 변수 및 함수 목록이 표시된다.
  • 이 항목에는 C++로 정의된 UFUNCTION(), UPROPERTY()도 포함된다.
  • BP에서 정의한 변수나 함수는 자동으로 사용 가능하다.

Select ViewModel Property

• Target ViewModel과 Target Property를 선택한다.

Set Bind Direction

• Bind Direction을 선택해 Widget과 ViewModel간의 정보가 흐르는 방식을 결정한다.

• 기본적으로 모든 ViewModel은 PreConstruct와 Construct 사이에 한 번 실행된다.
  • Bind Direction이 Two Way인 경우에는 One Way Bind만 실행된다.
  • ViewModel 값이 SetViewModel을 이용해 변경되면 모든 Bind가 실행된다.

Set Execution Mode

• Bind 된 Widget 등의 실행 방식을 지정

UENUM()
enum class EMVVMExecutionMode : uint8
{
	/** Execute the binding as soon as the source value changes. */
	Immediate = 0,
	/** Execute the binding at the end of the frame before drawing when the source value changes. */
	Delayed = 1,
	/** Always execute the binding at the end of the frame. */
	Tick = 2,
	/** When the binding can be triggered from multiple fields, use Delayed. Else, uses Immediate. */
	DelayedWhenSharedElseImmediate = 3 UMETA(DisplayName="Auto"),
};

Use Conversion Function

• 변수에 대한 직접 Bind 대신 Conversion Function을 채택할 수 있다.
  • Conversion Function은 ViewModel의 변수를 다른 타입의 Data로 Convert하기 위한 Interface를 제공한다.

• Convert 함수를 선택하면 설정할 수 있는 창이 드롭다운 아래 나타난다.
  • 만약 이미 드롭다운 데이터가 있다면 이 기능이 비정상 동작한다.
  • 이 때에는 Clear를 해서 한번 날려주고 하면 잘 된다.
• 새로운 Conversion Function은 Global 단위 혹은 UserWIdget에 추가될 수 있다.
  • 단, 이 함수는 Event, Network, Deprecated, EditorOnly로 선언되면 안된다.
  • BP에 표시되어야 하고, 하나의 Parameter와 하나의 Return Value를 가지고 있어야 한다.
  • Global로 정의되는 경우에는 static으로 선언되어야 한다.
  • UserWidget에서 정의되는 경우에는 pure 및 const여야 한다.

ViewModel 작업 팁

• 거대한 하나의 ViewModel 대신 작고 간결한 ViewModel을 권장한다.
  • 이는 UI 디버깅을 하기 훨씬 용이하다.
• 예를 들어 Ability,Inventory 등으로 구성된 Array를 사용해 RPG에서 Character를 나타내는 ViewModel을 상상하자.
  • 이 ViewModel에 Bind 된 Widget 중 일부를 디버깅 하기 위해서는
    전체 Character를 Spawn해 ViewModel의 데이터를 채워줘야 한다.
  • 이 때, 서로 다른 Component로 분할하면 Debug 할 때 Test Data로 더 쉽게 채울 수 있다.
• 또한 ViewModel은 다른 ViewModel 내부에 중첩하면, 복잡한 데이터 작업에서 유연성을 높일 수 있다.
  • 예를 들어, HP ViewModel과 Attribute ViewModel을 각각 생성하고 이를 Character ViewModel에 중첩할 수 있다.
  • 이 경우, Test에서 개별 Widget은 각자 연관 된 ViewModel에서 Data를 취할 수 있다.
    • 체력 표시줄이 Character의 HP를 REference 한다던가.
  • 동시에 최종 결과물에서는 중첩된 ViewModel에서 전체 Set를 사용할 수 있다.

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/optimization-guidelines-for-umg-in-unreal-engine

https://coding-hell.tistory.com/78

https://topic.alibabacloud.com/a/ui-optimization-tips-in-unreal-engine-4_8_8_10274886.html

https://blog.nullbus.net/94

Slate Render Process

Game Thread

• Game Thread에서 Slate Tick은 Frame당 2번 WidgetTree를 순회한다.
  • 한 번은 Paint할 Widget의 크기를 계산하기 위해 PrePass 과정에서.
  • 다른 한 번은 Paint 과정에서 Draw Elements를 계산하기 위해 OnPaint 과정에서.
• 조금 더 풀어 설명하면 다음과 같다.
  • Common Widget의 Type과 Parameter에 해당하는 Vertex Buffer 생성
  • Widget의 Render Transform이 Vertex Buffer로 계산 되어 Layer ID 및 Material 정보에 따라 Batch Merge 수행
  • 마지막 User Widget이 하나 이상의 Draw Elements 생성
  • 각 Draw Element가 Draw call에 해당하는 Render Thread에 Draw Element를 전달

Render Thread

• Render Thread에서의 Slate Rendering 작업은 다음 순서를 거친다.

Widget Render

• UI의 RTT(Render to Texture) 수행
• Retainer Box를 사용하면 Draw Elements가 Retainer Box의 Retain Target으로 Rendering 된다.

Slate Render

• Draw Elements를 Back Buffer에 Render
• Retainer Box를 사용하는 경우, Retainer Box의 Texture Resource가 Back Buffer에 Rendering 된다.

Invalidation

https://dev.epicgames.com/documentation/en-us/unreal-engine/invalidation-in-slate-and-umg-for-unreal-engine

• Slate Widget을 캐싱하고 Paint, Layout, 계층 정보 등의 변경점을 관리하는 기능.
  • Widget의 위와 같은 정보가 변경되지 않으면, 매 Frame마다 Widget을 다시 그리는 대신 Cache를 출력한다.
  • 위 정보들에 유효한 변경사항이 발생하면 Slate가 이를 재 계산하여 다시 그려준다.

Invalidation Box

• Child Widget의 Geometry를 Cache 하고 관리하는 UI
  • 해당 Widget의 Geometry가 바뀌지 않는 한 Cache 된 Geometry로 대체되어 CPU 사용량을 크게 줄여준다.
• Invalidation Box는 감싸진 UI 뿐 아니라 그 하위 계층의 모든 UI에 대해 Geometry Cache를 진행합니다.

Global Invalidation

• SWindow의 Invalidation을 이용해 효과적으로 모든 UI를 Invalidation Box로 Wrapping하는 기능.
  • 이 SWindow에 포함 된 모든 Invalidation Box는 무효화 되고, SWindow의 Invalidation Box만 동작하게 된다.
• Slate.EnableGlobalInvalidation을 true로 트리거하여 활성화

void SWidget::Invalidate(EInvalidateWidgetReason InvalidateReason)
{
	SLATE_CROSS_THREAD_CHECK();

	if (InvalidateReason == EInvalidateWidgetReason::None || !IsConstructed())
	{
		return;
	}

	SCOPED_NAMED_EVENT_TEXT("SWidget::Invalidate", FColor::Orange);

	// Backwards compatibility fix:  Its no longer valid to just invalidate volatility since we need to repaint to cache elements if a widget becomes non-volatile. So after volatility changes force repaint
	if (EnumHasAnyFlags(InvalidateReason, EInvalidateWidgetReason::Volatility))
	{
		InvalidateReason |= EInvalidateWidgetReason::PaintAndVolatility;
	}

	if (EnumHasAnyFlags(InvalidateReason, EInvalidateWidgetReason::Prepass))
	{
		MarkPrepassAsDirty();
		InvalidateReason |= EInvalidateWidgetReason::Layout;
	}

	if (EnumHasAnyFlags(InvalidateReason, EInvalidateWidgetReason::ChildOrder) || !PrepassLayoutScaleMultiplier.IsSet())
	{
		MarkPrepassAsDirty();
		InvalidateReason |= EInvalidateWidgetReason::Prepass;
		InvalidateReason |= EInvalidateWidgetReason::Layout;
	}

	const bool bVolatilityChanged = EnumHasAnyFlags(InvalidateReason, EInvalidateWidgetReason::Volatility) ? Advanced_InvalidateVolatility() : false;

	if(FastPathProxyHandle.IsValid(this))
	{
		// Current thinking is that visibility and volatility should be updated right away, not during fast path invalidation processing next frame
		if (EnumHasAnyFlags(InvalidateReason, EInvalidateWidgetReason::Visibility))
		{
			SCOPED_NAMED_EVENT(SWidget_UpdateFastPathVisibility, FColor::Red);
			UpdateFastPathVisibility(FastPathProxyHandle.GetProxy().Visibility.MimicAsParent(), FastPathProxyHandle.GetInvalidationRoot_NoCheck()->GetHittestGrid());
		}

		if (bVolatilityChanged)
		{
			SCOPED_NAMED_EVENT(SWidget_UpdateFastPathVolatility, FColor::Red);

			TSharedPtr<SWidget> ParentWidget = GetParentWidget();

			UpdateFastPathVolatility(ParentWidget.IsValid() ? ParentWidget->IsVolatile() || ParentWidget->IsVolatileIndirectly() : false);

			ensure(!IsVolatile() || IsVolatileIndirectly() || EnumHasAnyFlags(UpdateFlags, EWidgetUpdateFlags::NeedsVolatilePaint));
		}

		FastPathProxyHandle.MarkWidgetDirty_NoCheck(InvalidateReason);
	}
	else
	{
#if WITH_SLATE_DEBUGGING
		FSlateDebugging::BroadcastWidgetInvalidate(this, nullptr, InvalidateReason);
#endif
		UE_TRACE_SLATE_WIDGET_INVALIDATED(this, nullptr, InvalidateReason);
	}
}

Retainer Panel

• Child Widgets을 유저의 화면에 Render 하기 전에 하나의 Texture로 병합

• 여기서 Phase는 Render를 시작하는 Frame, Phase Count는 Render가 되는 Frame 주기이다.
  • 예를 들어 위의 경우 0 Frame에서 시작하여 3 Frame 단위로 Retainer Panel의 Child Widgets이 Render 된다.
• 이러한 기능들은 매 Frame마다 호출되는 UI의 Draw call을 줄여주는 기능을 제공한다.
• 하지만 Retainer Panel은 다시 그려질 때 큰 overhead를 가지면서,
  Widget 개개인이 점유하는 Memory가 Invalidation Box보다 크다.
  • 이는 Retainer Panel이 각 Widget의 Invalidation Data 뿐 아니라 고유한 Render Target도 가지기 때문이다.
• 때문에 UI의 CPU 점유율을 낮추려 한다면 우선 Invalidation Box부터 써야 한다.
  • 그럼에도 Draw Call을 줄이고 싶다면, Retainer Panel을 이용함으로 CPU 사용량을 더 압축할 수 있다.
• 이는 성능 제약이 빡빡한 저성능 모바일에서 유용다.

How Invalidation works

• Widget이 화면에 그려질 때 다음 작업들이 순차적으로 발생한다.
  • 계층 구조 - Slate가 root widget과 그들의 child를 모두 포함한 계층에 따라 widget tree를 생성한다.
  • Layout - Slate가 Render Transform을 기반으로 Widget의 크기와 스크린 상 위치를 계산한다.
  • Paint - Slate가 각 Widget의 Geometry를 계산한다.
• 각 작업들은 수행 할 때 뒤이은 작업을 반드시 수행해야 한다.
  • 예를 들어 계층 구조 작업이 수행되면 반드시 Layout, Paint 작업이 수행되어야 한다.
• Invalidation System은 위 과정에서 발생하는 모든 데이터를 Memory에 Cache한다.
  • Widget이 Invalidation Box를 사용하든, SWidget의 Global Invalidation을 사용하든.
• Memory에 Cache된 Widget들은 변경사항이 발생하지 않는 한 재연산을 하지 않는다.
  • 만약 변경사항이 발생하게 되면 Dirty List에 추가되고,
    이 List의 Widget들은 다음 Frame에서 재연산이 이루어진다.
• Invalidation에서 Cache된 Data를 갱신하게 되는 타입은 대략 다음과 같다.

/**
 * The different types of invalidation that are possible for a widget.
 */
enum class EInvalidateWidgetReason : uint8
{
	None = 0,

	/**
	 * Use Layout invalidation if your widget needs to change desired size.  This is an expensive invalidation so do not use if all you need to do is redraw a widget
	 */
	Layout = 1 << 0,

	/**
	 * Use when the painting of widget has been altered, but nothing affecting sizing.
	 */
	Paint = 1 << 1,

	/**
	 * Use if just the volatility of the widget has been adjusted.
	 */
	Volatility = 1 << 2,

	/**
	 * A child was added or removed.   (this implies prepass and layout)
	 */
	ChildOrder = 1 << 3,

	/**
	 * A Widgets render transform changed
	 */
	RenderTransform = 1 << 4,

	/**
	 * Changing visibility (this implies layout)
	 */
	Visibility = 1 << 5,

	/**
	 * Attributes got bound or unbound (it's used by the SlateAttributeMetaData)
	 */
	AttributeRegistration = 1 << 6,

	/**
	 * Re-cache desired size of all of this widget's children recursively (this implies layout)
	 */
	Prepass = 1 << 7,

	/**
	 * Use Paint invalidation if you're changing a normal property involving painting or sizing.
	 * Additionally if the property that was changed affects Volatility in anyway, it's important
	 * that you invalidate volatility so that it can be recalculated and cached.
	 */
	PaintAndVolatility = Paint | Volatility,
	/**
	 * Use Layout invalidation if you're changing a normal property involving painting or sizing.
	 * Additionally if the property that was changed affects Volatility in anyway, it's important
	 * that you invalidate volatility so that it can be recalculated and cached.
	 */
	LayoutAndVolatility = Layout | Volatility,


	/**
	 * Do not use this ever unless you know what you are doing
	 */
	All UE_DEPRECATED(4.22, "EInvalidateWidget::All has been deprecated.  You probably wanted EInvalidateWidget::Layout but if you need more than that then use bitwise or to combine them") = 0xff
};

• Invalidation은 자주 변경되지 않은 UI에서 최적화된 기능이다.
  • Widget이 오랫동안 변경되지 않을수록 Slate가 Cache Data를 오래 들고 있고, 그 만큼 CPU 부하를 줄여준다.
• 이는 특히 MMORPG나 라이브 서비스 게임의 Depth가 있는 메뉴와 같이 규모가 크고 복잡한 UI 작업에서 중요하다.

Volatile Widget

• 간혹 특정 Widget은 가능한 매 Frame마다 업데이트가 되어야 하는 경우가 있다.
  • 이 경우 Widget은 변경사항이 있을 때마다 매 tick이 Invalidate 된다.
  • 하지만 CPU 부하는 Invalidation을 사용할 때와 동일하게 발생한다.
  • 더불어 Hiearchy를 Cache하기 위해 Memory도 점유하게 된다.
• 이를 해결하기 위해 자주 사용하는 Widget에 Volatile 선언을 해주는 것이 좋다.
  • Volatile 선언이 된 Widget과 그 Child Widget들은 Paint Data가 Cache되지 않는다.
• 비록 Geometry는 매 Frame마다 재계산되어 다시 그려지겠지만,
  Slate는 직접적인 변경사항이 없는 이상 Layout 계산은 계속해서 Skip한다.
• 이는 UI를 전반적으로 Invalidation 하고 싶지만,
  자주 갱신되는 소수의 Widget으로 인해 이득을 보지 못할 때 유용하다.

개발자가 주의해야 할 점

OnTick/OnPaint 사용 지양

• OnTick이나 OnPaint에서 작업을 하게 되면 그 작업이 매 Frame마다 호출하게 됨.
• 가급적 Event Dispatch나 Delegate를 이용할 것을 권장

Attribute Bind 대신 Event-driven Update 사용

• Unreal Engine에서 제공하는 Attribute Bind 역시 매 Frame마다 할당 됨.
• 이 역시 Event와 Delegate를 이용해 변경사항이 있을 때에만 Widget에 적용 되도록 작업할 것을 권장 함.

Widget Construction

Reduce unused widgets

• Widget의 모든 child는 시각화 여부와 무관하게 항상 construct 됨.
  • 이는 Render가 되지 않더라도 Loading time, Construction time, Memory를 점유한다는 의미.
• 때문에 당장 사용되지 않는 Widget들은 Hierarchy에서 제거하는 것이 옳다.

Break complex widgets

• 특히 Main System에서 사용되는 Widget의 경우 실제로 표시되는 것은 몇 없지만 Cild가 수 천개씩 있는 경우가 있다.
  • 이러한 Widget을 한꺼번에 Load하게 되면 불필요한 Child로 인해 Loading이 지연되고 Memory를 점유하게 된다.
• 때문에 일정 규모 이상의 Widget은 어느정도 Child Widget을 세분화 하는 것이 좋다. 
• 예를 들어, 다음과 같이 Widget을 구분하여 작업 방향성을 정할 수 있다. 
  • 항상 표시되는 Widget
    • BaseWidget과 같이 Load하면서 화면에 바로 출력
  • 가능한 빨리 표시되어야 하는 Widget
    • 당장 사용하지 않을 수도 있지만 반응성이 높아야 함.
    • BaseWidget과 같이 Load 하되, 화면에는 출력하지 않고 Visibility로 컨트롤.
  • 조금 늦게 표시되어도 괜찮은 Widget
    
    • 가끔 사용되거나 아얘 사용되지 않는 경우도 있음.
    • BaseWidget과 별개로 필요할 때마다 Async Load.
• 이러한 방식은 Memory를 크게 절약할 뿐 아니라 Load 할 때의 CPU 영향도 줄일 수 있다.

Layout

CanvasPanel 사용 지양

• CanvasPanel은 좌표 평면과 Widget 별 Anchor를 이용해 다른 Widget의 위치를 지정할 수 있는 강력한 Widget이다.
  • 이는 Widget을 원하는 위치에 정확하게 지정하면서,
    동시에 Screen의 외각을 기준으로 Widget의 위치를 유지할 수 있다.
• 하지만 그와 동시에 높은 성능을 요구하는 Widget이기도 하다.
  • Slate의 Draw call은 Widget의 Layer ID별로 발생한다.
  • VerticalBox나 HorizontalBox등의 다른 Container Widget들은 Child Widget의 Layer ID를 통합한다.
  • 하지만 CanvalsPanel은 Child Widget이 필요할 때 다른 Widget 위에 Render 될 수 있도록 ID를 증가시킨다.
• 결과적으로 CanvasPanel은 단기로 여러 개의 Draw call을 발생시켜 높은 CPU 사용량을 요구하게 된다.
  
  • 비록 CanvasPanel보다 용처가 제한적이지만, OverlayPanel 역시 Draw call을 증가시킨다.
  • GridPanel은 Slot마다 Layer를 직접 지정할 수 있지만, 보통은 Child를 Iterate하며 LayerID를 새로 부여한다.
  • ScrollBox는 Scroll Bar가 Layer ID를 증가시킨다.
  • Border 역시 Layer ID를 증가시킨다.
• HUD나 Menu System의 Root Widget으로 CanvasPanel을 사용하는 것은 크게 문제가 되지 않는다.
  • 이 경우에는 상세한 위치 조정이나 복잡한 Z-Order 배치가 필요할 가능성이 높기 때문이다.
• 다만 Template 속성이 있는 Widget은 CanvasPanel 위에서 작업하는 것을 지양해야 한다.
  • TextBox, Custom Button과 같이 다른 Widget의 구성요소로 사용되는 Custom Widget들
• 또는 CanvasPanel을 다수의 Layer에서 과도하게 사용하면, 최종 Layer를 혼돈하기 쉽다.
• 일반적으로 하나의 요소로 구성된 Widget은 Canvas Panel로 감쌀 필요가 전혀 없다.
• 또한 HUD나 Menu 같은 경우에도,
  Overlay나 SizeBox를 HorizontalBox, VerticalBox, GridBox와 같이 사용하여 CanvasPanel 사용을 대체할 수 있다.

SizeBox 대신 가능한 Spacer 사용

• SizeBox는 자신의 크기를 계산하고 Render하는데 다양한 값을 사용한다.
• 만약 Widget이 특정 Width와 Height를 고정적으로 가진다면, Spacer가 훨씬 가볍다.

ScaleBox와 SizeBox를 같이 사용하지 않기

• ScaleBox와 SizeBox를 같이 사용하면 매 Frame마다 각자 서로의 Size를 오가며 Update하는 Loop에 빠지게 된다.
• 이 둘에 의존하기 보다는 Layout이 Content의 Native Size에 따라 동작하도록 만드는 것이 적절하다.

RichTextWidget 사용 지양

• RichTextWidget은 강력한 Format 지정 기능을 제공하는 만큼 표준 TextBox보다 훨씬 무겁다.
• 만약 RichTextWidget의 모든 기능이 필요한게 아니라 디자인적인 표현만이 필요하다면,
  원하는 외형을 표현할 수 있는 Font를 제작하여 TextWidget에서 사용하는 것이 훨씬 가볍다.

Visibility

• 화면 출력되어야 하는 Widget이 Visible인 경우, 클릭 시 Click 반응이 동작해 오버헤드가 발생 함.
  • visible 대신 HitTestInvisible, SelfHitTestInvisible을 사용할 것을 권장
• Hidden의 경우 화면에 보이지 않더라도 영역을 차지하기 위해 Layout Space를 사용 함.
  • Layout Space를 사용하면 Prepass 계산이 매 Frame마다 수행 됨.
  • 완전히 화면에서 숨기면서 영역을 차지할 필요가 없다면 Collapse를 사용하는 것을 권장.

Texture

Merged Texture

• Widget에서 여러 개의 Texture를 사용하는 경우, Texture의 갯수만큼 Draw call이 발생한다.
  • 때문에 가능하면 Merge Texture 1개를 사용하는 것이 좋다.
• Widget의 Sprite를 사용하면 Merged Texture를 사용하거나 편집할 수 있다.

Atlas Group

https://velog.io/@devkcy/ue5-textureatlas

• Atlas를 효율적으로 사용하는 방안
  • 위 Merged Texture를 Sprite로 사용하는 것도 Atlas를 거친다.
• 보통 Texture는 2의 지수로 저장이 된다.
  • 300 * 300인 경우 실제 크기는 512 * 512가 된다.
  • 이 때 필요한 영역 외의 Pixel 너비 만큼 메모리를 낭비하게 된다.
• Atlas Group은 이런 Texture를 하나의 Texture로 묶는 방식이다.
  • 이는 같은 Widget에서 사용되는 Image들에게 주로 사용되며, Context Switching을 줄이는 효과가 있다.
  • 반대로 다른 Widget의 Image를 묶어주면 Context Switch가 증가한다.
• 일반적인 Atlas Group은 2048 * 2048 크기를 가진다.

Animation Cost

Material만 있는 Animation

• GPU로 처리되기 때문에 CPU 비용이 발생하지 않는다.
• 발광 이펙트, 배경 Scroll, Material 변화로만 표현 가능한 Effect들이 포이에 포함된다.
• Animation을 Material에 포함시킬 수 있다면, 가장 우선적으로 사용하는 것을 권장한다.

Blueprint로 작업 되었지만 Sequencer가 필요 없는 Animation

• 실행 비용은 거의 같지만,
  Sequencer Animation은 실행 전 Animation Object Initialize와 담당 Property Path 해석이 요구된다.
  • 즉, Sequencer Animation이 BP Animation보다 CPU 비용이 조금 더 높다.
• 비교적 짧고 자주 사용되는 Animation의 경우 Sequencer를 지양하고 BP Script로 작업할 것을 권장.

UMG의 Animation Editor로 만들어진 Sequencer Animation

• UMG의 Animation Editor은 Sequencer 구현체이다.
  • Color 같이 Attribute를 변경하는 경우에는 Widget을 다시 그리게 하지만 Layout을 Invalidate 하지 않는다.
  • 반대로 Render Transform의 변화를 가져오는 모든 Animation은 Layout을 Invalidate한다.
• 가급적 이러한 작업은 피하거나, Volatile 선언을 해줘야 한다.

Layout 변경을 유발하는 Animation

• CPU 비용이 가장 높음

기타 최적화 방안

Switch Material

• 성능이 낮은 Machine에서 Material Effect의 부하를 줄이거나 제거하는 방안
• DYNAMIC_MULTICAST Framework를 사용

Manager Class

• 모든 USerWidget과 Brush, Font등 UI Resource를 관리하는 Manager Class를 만드는 것을 권장.

Free Texture Memory

• Texture를 미리 Setting 하는 것이 아니라 코드를 통해 수동으로 Load/Set/Destroy 하는 것을 전제
  • Editor에서는 Texture를 설정하지 않으면 CDO에서 이 Texture 객체를 참조하는 것을 피할 수 있다.
  • CDO Reference는 ShardPtr의 Reference Count를 최소 1로 만들어 앱이 종료될 때까지 제거되지 않는다.
• Editor에서 Image Property가 설정되어 있고 Texture를 삭제하는 경우,
  CookStage에서 UImage와 UTexture 사이 Reference를 제거하여 UserWidget의 CDO가
  UTexture를 Reference 하지 않아야 한다.

void UWeakRefImage::Serialize(FArchive& Ar)
{
    Super::Serialize(Ar);
    
    if (Ar.IsCooking() && Ar.IsSaving())
    {
        // Let's suppose user always intend to set a valid resource texture here.
        UObject* ImageRes Brush.GetResourceObject();
        if (ImageRes != nullptr)
        {
            ImageWeakRef = ImageRes;
            Brush.SetResourceObject(nullptr);
            SetBrush(Brush);
        }
    }
    Ar << ImageWeakRef;
}

• 이 외에 Texture를 Load하는 코드는 다음과 같다.

void UWeakRefImage::LoadTextureResource(bool bAsync/*= true*/)
{
    if (ImageWeakRef.ResolveObject() || (!bAsync && ImageWeakRef.TryLoad()))
    {
    	Brush.SetResourceObject(ImageWeakRef.ResolveObject()); 
        SetBrush(Brush);
    }
    else
    {
        if (StreamableMgr == nullptr)
        {
        	StreamableMgr = new FStreamableManager();
        }
        StreamableMgr->RequestAsyncLoad(ImageWeakRef,
        	FStreamableDelegate::CreateUObject(this, &UWeakRefImage:: LoadTextureDeferred));
    }
}

void UWeakRefImage::LoadTextureDeferred()
{
    if (ImageWeakRef.ResolveObject())
    {
    	Brush.SetResourceObject(ImageWeakRef.ResolveObject()); 
        SetBrush (Brush);
    }
}

• Texture Unload하는 코드는 다음과 같다.

void UWeakRefImage::UnloadTextureResource()
{
    TSharedPtr<FSlateRenderer> Renderer = FSlateApplicationBase::Get().GetRenderer(); 
    if (Renderer.IsValid())
    {
        FSlateApplicationBase::Get().GetRenderer()->ReleaseDynamicResource(Brush);
        FSlateApplicationBase::Get().GetRenderer()->ReleaseAccessedResources(true);
    }
    Brush.SetResourceObject(nullptr);
    SetBrush (Brush);
}

3D RTT 최적화

• SceneCaptureComponent2D는 매 Frame에서 tick이 호출된다.
  • 매 Frame마다 Image Update가 발생하는 것을 취소할 수는 있다.
• 이 때 Animation의 Update 빈도는 30 fps 정도로 충분하므로 BP에서 Tick 간격을 설정할 수 있다.
  • 이 경우 BP에서 Capture을 수동으로 호출해야 한다.
• 이와 별개로, SceneCapturecomponent2D는 Render Target이 크면 그 자체만으로 성능이 악화된다.

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/replicated-object-execution-order-in-unreal-engine?application_version=5.3

Actor Property

• 기본적으로 Unreliable하고 Single Bunch로 전송된다.
  • Single Bunch에 Unreliable하기 때문에 다른 RPC보다는 나중에 전송된다.
  • 하지만 ForceQueue RPC보다는 먼저 전송된다.

Replicated Using Order

• 서로 다른 Replicated Property에 대한 RepNotify의 순서는 명확하게 정해진 것이 없다.
  • 클라이언트 상에서 Property의 Dirty 마킹 순서나 메모리상 위치와 아무런 연관이 없다.
• 때문에 몇몇 Property가 동시에 Replicated 되어야 한다면 Struct로 묶어서 관리하는 것을 권장한다.
• 만약 Gameplay에 중요한 Replicated Property가 있다면,
  RepNotify를 구현해 Property의 변경사항을 프레임 단위로 대응 하는 것이 좋다.
  • Replication을 통해 변경된 값을 전달받고 RepNotify가 호출된 후에,
    UObject::PostRepNotifies 함수에서 변경사항을 처리할 수 있다.
  • 이 때, 변경된 값이 사용될 준비가 될 때까지 각각의 RepNotify에 저장하는 것이 좋다.

RPC

• RPC에 대한 대전제는 다음과 같다.
  • Reliable이 Unreliable보다 먼저 전송된다.
  • Unicast는 Reliability와 무관하게 가장 먼저 전송된다.

Order Accross Actors

• Replicated Actor에 대한 RPC 호출에 대해서는 명확한 법칙이 없다.
• 때문에 RPC 함수 호출 순서와 실제 RPC 전달 순서는 일치하지 않는다.

Order Inside an Actor

• Replication System은 동일한 Actor에 대한 reliable RPC 호출의 순서는 보장해준다.
  • 이는 Actor의 Subobject에도 적용된다.
• 이는 reliable RPC의 경우, 함수를 호출한 순서와 실제 RPC의 전달 순서가 일치한다.

Unreliable VS Reliable

• Unreliable RPC와 Reliable RPC가 섞여 있을 때에는 순서가 보장되는 것처럼 보이지만, 실상은 보장되지 않는다.
• Packet 손실이나 재배치가 일어나지 않는다면, Unreliable RPC와 Reliable RPC의 전달 순서는 호출 순서와 일치한다.
  • 하지만 손실/재배치가 일어나면 순서가 달라지게 된다.
  • 정확히는 Reliable RPC끼리는 호출 순서와 전달 순서가 일치한다.

Multicast VS Unicast

• Multicast RPC와 Unicast RPC가 섞여 있을 때에는 항상 호출 순서와 전송 순서가 일치하지는 않아 더욱 복잡하다.

Reliable Multicast

• Reliable Multicast의 경우 Reliable Unicast와 섞여 있을 경우 호출 순서와 전송 순서가 일치한다.

Unreliable Multicast

• Unreliable Multicast의 경우는 절대로 다른 Reliable/Unreliable Multicast와의 순서를 보장해주지 않는다.

RPC Send Policy

• ERemoteFunctionSendPolicy를 정의하여 Send Policy를 명시해 RPC의 전송 순서에 영향을 줄 수 있다.

https://redchiken.tistory.com/389

Force Send

• Unreliable Multicast RPC의 순서를 바꾸고 이들이 Queue되는 것을 방지한다.
  • 여기서 Queue 되지 않는다는 것은 대기하지 않고 바로 전송이 된다는 의미이다.

Force Queue

• 다른 Force Queue RPC와 Unreliable Multicast를 제외한 RPC와의 순서를 보장하지 않는다.
• 이 말은 ForceQueue, Unreliable Multicast와는 절대적인 순서가 보장된다는 의미이다.

Order Between RPCs and Actor Properties

• RPC와 Property Replicate 사이에는 대략 다음과 같은 규칙이 적용된다.
  • RPC가 먼저 실행된다.
  • 그리고 Property가 나중에 update된다.
    • Property Replicate는 단일의 Unreliable 데이터 단위로 전송된다.
• Bunch Payload는 다음 규칙을 따라 생성된다.
  • Queue 되지 않은 PRC 직렬화
  • Replicated Property 직렬화
  • Queue 된 RPC 직렬화
• 이로 인해 한가지 주의해야 할 점이 있다.
  • RPC 내부에서 변경된 Replicated Property의 값이 뒤이어 발생할 Property Replicate에 의해 손실 될 수 있다.

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/remote-procedure-calls-in-unreal-engine?application_version=5.3

RPC

• Local 단위에서 호출하여 Remote로 연결된 1개 이상의 Machinge에서 실행되는 함수
• Return이 없는 단방향 함수 호출이 특징
• RPC는 주로 일시적이거나, 외형적으로 드러나는 Unreliable Gameplay Event에 사용된다.
  • 사운드 재생
  • Particle 생성
  • Animation 재생
• RPC는 Replicated/ReplicatedUsing 선언이 된 Property의 Replication을 보완하는 중요한 기능이다.
• RPC를 호출하려면 다음 2가지 조건이 성립되어야 한다.
  • Actor나 Actor Component일 것.
  • RPC를 호출하는 Object가 Replicate되어 있을 것.
• 마지막으로 RPC를 잘 사용하기 위해서는 Ownership을 잘 이해하는 편이 좋다.

Type

Client

• 이 Actor에 대해 Client Connection을 소유한 Client에서 실행되는 Unicast RPC

#pragma once

#include "DerivedActor.generated.h"

UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()

public:

    // Client RPC Function
    UFUNCTION(Client)
    void ClientRPC();
}

#include "DerivedActor.h"

ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
    bReplicates = true;
}

void ADerivedActor::ClientRPC_Implementation()
{
    // This log will print on every machine that executes this function.
    UE_LOG(LogTemp, Log, TEXT("ClientRPC executed."))
}

// Call from client to run on server
ADerivedClientActor* MyDerivedClientActor;
MyDerivedClientActor->ClientRPC();

Execution Matrix

Server

• 해당 Actor를 소유하는 Client에서 호출하여 Server에서 실행되는 Unicast RPC

#pragma once

#include "DerivedActor.generated.h"

UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()

public:
    // Server RPC Function
    UFUNCTION(Server)
    void ServerRPC();
}

#include "DerivedActor.h"
ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
    bReplicates = true;
}

void ADerivedActor::ServerRPC_Implementation()
{	
    // This function only executes if ServerRPC_Validate returns true.
    // This log will print on every machine that executes this function.
    UE_LOG(LogTemp, Log, TEXT("ServerRPC executed."))
}

// Call from client to run on server
ADerivedClientActor* MyDerivedClientActor;
MyDerivedClientActor->ServerRPC();

Execution Matrix

WithValidation

• Server RPC에서만 사용할 수 있는 Specifier
  • Server RPC의 신뢰성과 Network Policy를 구현할 수 있다.

#pragma once
#include "DerivedActor.generated.h"

UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()

public:

    UPROPERTY(Replicated)
    int32 Health;
    int32 MAXHEALTH = 100;

    // Server Unreliable RPC Function
    UFUNCTION(Server, Unreliable, WithValidation)
    void ServerUnreliableRPC(int32 RecoverHealth); 
}

• Validate 함수는 내부 로직을 통해 RPC 함수를 Server에서 실행할지 여부를 판단한다.
  • 그렇기에 Validate Specifier가 선언된 Server RPC가 실행될 때 Validate 함수가 가장 먼저 호출된다.

#include "DerivedActor.h"

// RPC Validation Implementation
bool ServerUnreliableRPC_Validate(int32 RecoverHealth)
{
    if (Health + RecoverHealth > MAXHEALTH)
    {
        return false;
    }
return true;
}

// RPC Implementation
void ServerUnreliableRPC_Implementation(int32 RecoverHealth)
{
    Health += RecoverHealth;
}

• 만약 Validate 함수에서 false를 반환하면, 해당 Server RPC를 전송한 Client는 Server로부터 연결이 끊긴다.

NetMulticast

• Server에서 호출
• 호출한 Actor와 Relevant한 모든 Client에서 실행되는 Multicast RPC
• Client에서도 호출할 수 있으나 Local에서만 동작한다.

#pragma once

#include "DerivedActor.generated.h"

UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()

public:
    // Multicast RPC Function
    UFUNCTION(NetMulticast)
    void MulticastRPC();
}

#include "DerivedActor.h"

ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
    bReplicates = true;
}

void ADerivedActor::MulticastRPC_Implementation()
{
    // This log will print on every machine that executes this function.
    UE_LOG(LogTemp, Log, TEXT("MulticastRPC executed."))	
}

// Call from server to run on server and all relevant clients
ADerviedServerActor* MyDerivedServerActor;
MyDerievedServerActor->MulticastRPC();

Execution Matrix

Reliability

• Client/Server/NetMulticast와 같이 사용되는 Specifier

Reliable

• RPC 수신자로부터 ACK를 받지 못하면 RPC를 재전송한다.
  • 다음 RPC 호출은 앞선 RPC의 ACK를 수신할 때 실행된다.
• 순서대로 도착하는 것을 보장해준다.

Unreliable

• RPC Packet이 Drop되면 실행되지 않는다.
• 도착 순서를 보장하지 않는다.

Send Policy

• ERemoteFunctionSendPolicy를 지정하여 RPC의 전송 순서를 명시적으로 조정할 수 있다.

enum class ERemoteFunctionSendPolicy
{		
	/** Unreliable multicast are queued. Everything else is send immediately */
	Default, 

	/** Bunch is send immediately no matter what */
	ForceSend,

	/** Bunch is queued until next actor replication, no matter what */
	ForceQueue,
};

• Send Policy 조절은 NetDriver::ProcessRemoteFunctionForChannel을 통해 가능하다.

/** Process a remote function on given actor channel. This is called by ::ProcessRemoteFunction.*/
ENGINE_API void ProcessRemoteFunctionForChannel(
	UActorChannel* Ch,
	const class FClassNetCache* ClassCache,
	const FFieldNetCache* FieldCache,
	UObject* TargetObj,
	UNetConnection* Connection,
	UFunction* Function,
	void* Parms,
	FOutParmRec* OutParms,
	FFrame* Stack,
	const bool IsServer,
	const ERemoteFunctionSendPolicy SendPolicy = ERemoteFunctionSendPolicy::Default);

void UNetDriver::ProcessRemoteFunctionForChannel(
	UActorChannel* Ch,
	const FClassNetCache* ClassCache,
	const FFieldNetCache* FieldCache,
	UObject* TargetObj,
	UNetConnection* Connection,
	UFunction* Function,
	void* Parms,
	FOutParmRec* OutParms,
	FFrame* Stack,
	const bool bIsServer,
	const ERemoteFunctionSendPolicy SendPolicy)
{
	EProcessRemoteFunctionFlags UnusedFlags = EProcessRemoteFunctionFlags::None;
	ProcessRemoteFunctionForChannelPrivate(Ch, ClassCache, FieldCache, TargetObj, Connection, Function, Parms, OutParms, Stack, bIsServer, SendPolicy, UnusedFlags);
}

Default

• RPC가 bunch에 직렬화 된다.
• Bunch는 다음 Frame 마지막에 NetUpdate에서 전송된다.

ForceSend

• RPC가 NetDriver::PostTickDispatch에서 trigger되면 bunch에 즉시 직렬화 되고 Network에 전송된다.
  • tick의 나머지 부분이 동작하는 도중에 trigger 되면, Default로 동작한다.
• 이 특별한 RPC 최적화 기법은 아래 조건 하에서 동작한다.
  • Replication Graph나 Iris를 사용할 때에만 동작한다.
  • NetWroldTickTime에서 호출된 RPC에서 동작.
    • 수신한 패킷되고 수신한 RPC가 실행된다.

ForceQueue

• Network Update이 마무리 될 때 Bandwidth가 남아 있다면 Bunch에 직렬화된다.

참고 링크

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/replicate-actor-properties-in-unreal-engine?application_version=5.3

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/replicated-subobjects-in-unreal-engine?application_version=5.3

Actor

Replicated

• Actor 내에서 Replicate 할 Property에 UPROPERTY() 선언
• UPROPERTY() 내에 'Replicated' Specifier를 입력

#pragma once 
 
#include "DerivedActor.generated.h"
 
UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()
 
public:
    // Property to replicate
    UPROPERTY(Replicated)
    uint32 Health;
 
    // Derived Actor constructor
    ADerivedActor(const class FPostConstructInitializeProperties & PCIP);
 
    // Override Replicate Properties function
    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
};

• 해당 Actor의 bReplicates 옵션을 활성화
  • 생성자나 BP 옵션에서 제어
• GetLifetimeReplicatedProps() 함수를 override하여 DOREPLIFETIME 매크로를 선언

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"
 
ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
    bReplicates = true;
}
 
void ADerivedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    // Call the Super
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
 
    // Add properties to replicated for the derived class
    DOREPLIFETIME(ADerivedActor, Health);
}

• 위와 같은 방식으로 Object 또한 Replicate를 할 수 있다.
• Network를 거쳐서 참조되는 Object는 반드시 Network 기능이 지원되어야 한다.
  • 이를 확인하려면 UObject::IsSupportedForNetworking() 함수를 이용한다.

Network Replicated Reference

• Replicated Actor
• Replicated Component
• Stably-named 하지만 Replicated 하지 않은 Actor나 Component
• Package로부터 Load 된 UObject(Actor, Component도 아닌)

Stably-named Object

•  Server와 Client 양쪽에 같은 이름으로 존재하는 Object를 지칭한다.
  • Actor가 Gameplay 중 Spawn되지 않고 Package로부터 직접 Load 되면 Stably-named하다.
• Actor Component는 다음 케이스일 경우 Stably-named 하다.
  • Pacakge로부터 직접 load 된 경우
  • 간단한 생성자 호출로 추가 된 경우
  • UActorComponent::SetNetAddressable로 마킹 된 경우
    • Component의 이름을 Server와 Client가 모두 명확하게 알고 있는 경우
    • AActor C++ 생성자에서 추가되는 Component들이 그 대표적인 예시이다.

ReplicatedUsing

• "OnRep_"으로 시작하는 함수를 지정해 Replicate 될 때마다 특정 행동을 부여할 수 있는 Specifier

#pragma once 
 
#include "DerivedActor.generated.h"
 
UCLASS()
class ADerivedActor : public AActor
{
	GENERATED_BODY()
 
public:
 
	// Replicated Property using OnRep_Value
	UPROPERTY(ReplicatedUsing=OnRep_Value)
	int32 HealthValue1;
 
	// Replicated Property using OnRep_ConstRef
	UPROPERTY(ReplicatedUsing=OnRep_ConstRef)
	int32 HealthValue2;
 
	// Replicated Property using OnRep_NoParam
	UPROPERTY(ReplicatedUsing=OnRep_NoParam)
	int32 HealthValue3;
 
	// Signature to pass copy of the last value
	UFUNCTION()
	void OnRep_Value(int32 LastHealthValue);
 
	// Signature to pass const reference
	UFUNCTION()
	void OnRep_ConstRef(const int32& LastHealthValue);
 
	// Signature to pass no parameter
	UFUNCTION()
	void OnRep_NoParam();
 
	// Derived Actor constructor
	ADerivedActor(const class FPostConstructInitializeProperties & PCIP);
};

• ReplicatedUsing에 연결 될 함수들은 UFUNCTION()으로 선언되어 있어야 한다.
• 또한 경우에 따라서 Parameter를 받을 수도 있다.
  • Parameter에 전달되는 값은 Replicated Property가 변경되기 이전의 값이다.
  • 변경된 이후의 값은 Property가 직접 들고 있다.

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"
 
ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
	bReplicates = true;
}
 
void ADerivedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	// Call the Super
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);
 
	// Add properties to replicated for the derived class
	DOREPLIFETIME(ADerivedActor, HealthValue1);
	DOREPLIFETIME(ADerivedActor, HealthValue2);
	DOREPLIFETIME(ADerivedActor, HealthValue3);
}
 
void ADerivedActor::OnRep_Value(int32 LastHealthValue)
{
	UE_LOG(LogTemp, Log, TEXT("OnRep_Value with value. Last value: %d"), LastHealthValue)
	// Add custom OnRep logic
}
 
void ADerivedActor::OnRep_ConstRef(const int32& LastHealthValue)
{
	UE_LOG(LogTemp, Log, TEXT("OnRep_ConstRef with const ref. Last value: %d"), *LastHealthValue)
	// Add custom OnRep logic
}
 
void ADerivedActor::OnRep_NoParam()
{
	UE_LOG(LogTemp, Log, TEXT("OnRep_NoParam with no parameter."))
	// Add custom OnRep logic
}

• RepNotify는 C++과 BP에서 조금 다르게 동작한다.
  • BP로 RepNotify가 선언되어 있다면, Replicated Property에 대해 Set 함수가 호출될 때 RepNotify도 호출된다.
  • 하지만 기본적으로 Replicated Property의 Reference를 갖는 Function, Macro에서는
    값이 변경되더라도 RepNotify가 호출되지 않는다.

NotReplicated

• Replicated 되는 Actor나 Struct 내에서 특정 Property를 Replicate 되지 않도록 한다.

#pragma once 
 
#include "DerivedActor.generated.h"
 
USTRUCT()
struct FMyStruct
{
	GENERATED_BODY()
 
	UPROPERTY()
	int32 ReplicatedProperty;
 
	// Not Replicated even though encompassing struct is Replicated
	UPROPERTY(NotReplicated)
	int32 NotReplicatedProperty;
};
 
UCLASS()
class ADerivedActor : public AActor
{
	GENERATED_BODY()
 
public:
	UPROPERTY(Replicated)
	FMyStruct ReplicatedStruct;
 
	// Derived Actor constructor
	ADerivedActor(const class FPostConstructInitializeProperties & PCIP);
};

• 5.4버전 엔진 코드 기준으로는 NotReplicated Property는 GetLifetimeReplicatedProps() 내에서 DISABLE_REPLICATED_PROPERTY 선언을 해주어야 한다.
• 다만 이는 Warning이 발생할 뿐이고 Error가 발생하지는 않는다.

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"
 
ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
	bReplicates = true;
}
 
void ADerivedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);
 
	DOREPLIFETIME(ADerivedActor, ReplicatedStruct);
}

Conditional Replication

• Replicated Property는 한번 등록되면 Lifetime 동안 해제할 수 없다.
• 기본적으로 Replicated Property는 값이 바뀔 때에 Replicate 된다.
  • 그 즉슨, 값이 바뀌지 않으면 Replicate 되지 않고 Bandwidth를 점유하지 않는다.
  • 때문에 Replicate 조건을 부여하여 불필요한 Replicate를 줄이면 이는 성능 향상으로 이어진다.

Replication Condition

• GetLifetimeReplicatedProps() 함수에서 DOREPLIFETIME() 매크로 대신
  DOREPTIME_CONDITION() 매크로를 사용한다.

#define DOREPLIFETIME_CONDITION(c,v,cond) \
{ \
	static_assert(cond != COND_NetGroup, "COND_NetGroup cannot be used on replicated properties. Only when registering subobjects"); \
	FDoRepLifetimeParams LocalDoRepParams; \
	LocalDoRepParams.Condition = cond; \
	DOREPLIFETIME_WITH_PARAMS(c,v,LocalDoRepParams); \
}

• 이는 Replicated 뿐 아니라 ReplicatedUsing Specifier도 적용된다.

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"
 
void ADerivedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	// Call the Super
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);
 
	// Add property replication with a condition
	DOREPLIFETIME_CONDITION(ADerivedActor, Health, COND_OwnerOnly);
}

RepNotify Condition

• Replication System은 Replicate 뿐 아니라 RepNotify 호출에 대해서도 조건을 부여할 수 있다.
  • 이를 위해서는 DOREPLIFETIME_CONDITION_NOTIFY가 필요하다.

/** Allows gamecode to specify RepNotify condition: REPNOTIFY_OnChanged (default) or REPNOTIFY_Always for when repnotify function is called  */
#define DOREPLIFETIME_CONDITION_NOTIFY(c,v,cond,rncond) \
{ \
	static_assert(cond != COND_NetGroup, "COND_NetGroup cannot be used on replicated properties. Only when registering subobjects"); \
	FDoRepLifetimeParams LocalDoRepParams; \
	LocalDoRepParams.Condition = cond; \
	LocalDoRepParams.RepNotifyCondition = rncond; \
	DOREPLIFETIME_WITH_PARAMS(c,v,LocalDoRepParams); \
}

• 코드를 보면 알 수 있듯이,
  DOREPLIFETIME_CONDITION_NOTIFY에서는 RepNotify 조건 외에 Replicate 조건도 지정할 수 있다.

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"
 
void ADerivedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	// Call the Super
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);
 
	// Add property replication with a condition
	/** 	Use this to always execute RepNotify
	*	Associated OnRep called on client every time property replicates
	*/
	DOREPLIFETIME_CONDITION_NOTIFY(ADerivedActor, Health, COND_OwnerOnly, REPNOTIFY_Always);
 
	/** 	Use this to only execute RepNotify when property changes
	*	Associated OnRep called on client only when property changes
	*/
	DOREPLIFETIME_CONDITION_NOTIFY(ADerivedActor, Health, COND_OwnerOnly, REPNOTIFY_OnChanged);
}

Custom Condition

• 다음 작업을 통해 엔진에서 제공하는 조건 외의 조건으로 Replicate를 조절할 수 있다.
  
  • Replication Condition을 COND_Custom으로 지정
  • bool 타입 혹은 이를 반환하는 함수를 PreReplication에 등록

#pragma once 
 
#include "DerivedActor.generated.h"
 
UCLASS()
class ADerivedActor : public AActor
{
    GENERATED_BODY()
 
public:
    UPROPERTY(Replicated)
    int32 Health;
 
    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
 
    // Derived Actor constructor
    ADerivedActor(const class FPostConstructInitializeProperties & PCIP);
 
    virtual void PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker) override;
 
    // Custom Replication Condition override function
    bool IsInvincible();
};

• PreReplication에 Custom Condition을 지정할 때에는 DOREPLIFETIME_ACTIVE_OVERRIDE 매크로를 사용한다.

// Built on Compile time and Disable to work with Array
#define DOREPLIFETIME_ACTIVE_OVERRIDE_FAST(c,v,active) \
{ \
	static_assert(ValidateReplicatedClassInheritance<c, ThisClass>(), #c "." #v " is not accessible from this class."); \
	UE::Net::Private::FNetPropertyConditionManager::SetPropertyActiveOverride(ChangedPropertyTracker, this, (int32)c::ENetFields_Private::v, active); \
}

// Built on Compile time and Enable to Work with Array
#define DOREPLIFETIME_ACTIVE_OVERRIDE_FAST_STATIC_ARRAY(c,v,active) \
{ \
	static_assert(ValidateReplicatedClassInheritance<c, ThisClass>(), #c "." #v " is not accessible from this class."); \
	for (int32 i = 0; i < (int32)c::EArrayDims_Private::v; ++i) \
	{ \
		UE::Net::Private::FNetPropertyConditionManager::SetPropertyActiveOverride(ChangedPropertyTracker, this, (int32)c::ENetFields_Private::v##_STATIC_ARRAY + i, active); \
	} \
}

// Built on Runtime and Enable to Work with Array
#define DOREPLIFETIME_ACTIVE_OVERRIDE(c,v,active) \
{ \
	static_assert(ValidateReplicatedClassInheritance<c, ThisClass>(), #c "." #v " is not accessible from this class."); \
	static FProperty* sp##v = GetReplicatedProperty(StaticClass(), c::StaticClass(),GET_MEMBER_NAME_CHECKED(c,v)); \
	for (int32 i = 0; i < sp##v->ArrayDim; i++) \
	{ \
		UE::Net::Private::FNetPropertyConditionManager::SetPropertyActiveOverride(ChangedPropertyTracker, this, sp##v->RepIndex + i, active); \
	} \
}

• 이제 Health는 IsInvincible()이 false일 때에만 Replicate된다.

#include "DerivedActor.h"
#include "Net/UnrealNetwork.h"

ADerivedActor::ADerivedActor(const class FPostConstructInitializeProperties & PCIP) : Super(PCIP)
{
	bReplicates = true;
}

void ADerivedActor::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const 
{
	// Call the Super 
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

	// Add properties to replicated for the derived class
    DOREPLIFETIME_CONDITION(ADerivedActor, Health, COND_Custom);
}

/* Function where the Custom condition is registered. */ 
void ADerivedActor::PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker)
{
	// Call the Super
    Super::PreReplication(ChangedPropertyTracker);

	/* Use a custom property replication condition In this case, a function IsInvincible() If the actor is invincible, don't replicate Health */
    DOREPLIFETIME_ACTIVE_OVERRIDE(ADerivedActor, Health, !IsInvincible());
}

bool IsInvincible()
{
	bool bIsInvincible = false;

	// Custom logic to determine invincibility...
	return bIsInvincible;
}

• Custom Condition은 매우 편리해 보이지만 2가지 큰 이유로 자주 사용하지 않는다.
  • 첫째, 작업 시간과 소모 리소스가 크다
  • 둘째, Connection 기준을 변경할 수 없다.

ELifetimeCondition

• DOREPLIFETIME_CONDITION(_NOTIFY) 매크로의 3번째 parameter로 전달하는 값들.

/** Secondary condition to check before considering the replication of a lifetime property. */
UENUM(BlueprintType)
enum ELifetimeCondition : int
{
	COND_None = 0							UMETA(DisplayName = "None"),							// This property has no condition, and will send anytime it changes
	COND_InitialOnly = 1					UMETA(DisplayName = "Initial Only"),					// This property will only attempt to send on the initial bunch
	COND_OwnerOnly = 2						UMETA(DisplayName = "Owner Only"),						// This property will only send to the actor's owner
	COND_SkipOwner = 3						UMETA(DisplayName = "Skip Owner"),						// This property send to every connection EXCEPT the owner
	COND_SimulatedOnly = 4					UMETA(DisplayName = "Simulated Only"),					// This property will only send to simulated actors
	COND_AutonomousOnly = 5					UMETA(DisplayName = "Autonomous Only"),					// This property will only send to autonomous actors
	COND_SimulatedOrPhysics = 6				UMETA(DisplayName = "Simulated Or Physics"),			// This property will send to simulated OR bRepPhysics actors
	COND_InitialOrOwner = 7					UMETA(DisplayName = "Initial Or Owner"),				// This property will send on the initial packet, or to the actors owner
	COND_Custom = 8							UMETA(DisplayName = "Custom"),							// This property has no particular condition, but wants the ability to toggle on/off via SetCustomIsActiveOverride
	COND_ReplayOrOwner = 9					UMETA(DisplayName = "Replay Or Owner"),					// This property will only send to the replay connection, or to the actors owner
	COND_ReplayOnly = 10					UMETA(DisplayName = "Replay Only"),						// This property will only send to the replay connection
	COND_SimulatedOnlyNoReplay = 11			UMETA(DisplayName = "Simulated Only No Replay"),		// This property will send to actors only, but not to replay connections
	COND_SimulatedOrPhysicsNoReplay = 12	UMETA(DisplayName = "Simulated Or Physics No Replay"),	// This property will send to simulated Or bRepPhysics actors, but not to replay connections
	COND_SkipReplay = 13					UMETA(DisplayName = "Skip Replay"),						// This property will not send to the replay connection
	COND_Dynamic = 14						UMETA(Hidden),											// This property wants to override the condition at runtime. Defaults to always replicate until you override it to a new condition.
	COND_Never = 15							UMETA(Hidden),											// This property will never be replicated
	COND_NetGroup = 16						UMETA(Hidden),											// This subobject will replicate to connections that are part of the same group the subobject is registered to. Not usable on properties.
	COND_Max = 17							UMETA(Hidden)
};

ELifetimeRepnotifyCondition

• DOREPLIFETIME_CONDITION_NOTIFY 매크로의 4번째 parameter로 전달되는 값들

enum ELifetimeRepNotifyCondition
{
	REPNOTIFY_OnChanged = 0,		// Only call the property's RepNotify function if it changes from the local value
	REPNOTIFY_Always = 1,		// Always Call the property's RepNotify function when it is received from the server
};

SubObject

ReplicateSubobjects

class AMyActor : public AActor
{
    UPROPERTY(Replicated)
    UMySubObjectClass* MySubObject;
}

class UMySubObjectClass : public UObject
{
    UPROPERTY(Replicated)
    int32 Counter = 0;
}

void AMyActor::CreateMyClass()
{
    MySubObject = NewObject<UMySubObjectClass>();
    MySubObject->Counter = 10;
}

void AMyActor::ReplicateSubobjects(...)
{
    Super::ReplicateSubobjects(...);
    Channel->ReplicateSubobject(MySubObject); // Becomes a subobject here
}

• Channel에 Subobject를 등록하지 않는다면, Client에서 해당 Subobject는 항상 null일 것이다.
• Subobject를 Replicate 하더라도 그 안의 Property를 Replicate하려면 Specifier 선언을 따로 해줘야 한다.

Registered Subobject

• Subobject를 Owning Actor/ActorComponent List에 등록
  • List에 등록 된 Object들은 Actor Channel에 의해 자동으로 replicate 된다.
  • 등록하 때 ELifetimeCondition을 통해 Replicate condition을 부여할 수 있다.
• 이 방식은 ReplicateSubObjects 함수 사용에 대한 업무 부담을 줄여줍니다.

AMyActor::AMyActor()
{
    bReplicateUsingRegisteredSubObjectList = true;
}

void AMyActor::CleanupSubobject()
{
    if (MySubobject)
    {
        RemoveReplicatedSubobject(MySubObject);
    }
}

void AMyActor::CreateMyClass()
{
    CleanupSubobject();

    MySubObject= NewObject<UMySubObjectClass>();
    MySubObject->Counter = 10;
    AddReplicatedSubObject(MySubObject);
}

void AMyActor::CreateMyDerivedClass()
{
    CleanupSubobject();

    MySubObject = NewObject<UMyDerivedSubObjectClass>();
    AddReplicatedSubObject(MySubObject);
}

void AMyActor::ReplicateSubobjects(...)
{
    //deprecated and not called anymore
}

• AddReplicatedSubObject 함수는 ReadyForReplication이나 BeginPlay, 또는 Subobject를 생성할 때 호출한다.
• 이 중 ReadyForReplication에서 함수 호출 시 주의할 점이 있따.
  • ActorComponent에서 ReadyForReplication 함수는 InitComponent와 BeginPlay 사이에 호출된다.
  • 즉슨, Component를 이 함수 안에서 등록하게 되면 BeginPlay에서는 RPC를 수행할 수 있다는 의미이다.
• Subobject를 수정하거나 삭제 할 때에는 반드시 RemoveReplicateSubObject 함수를 호출해야 한다.
  • 해당 함수를 호출하지 않고 수정/삭제 시, Object의 Destruction 과정에서 한번 더 Destroy가 Mark된다.
  • 이는 GC가 동작할 때 Crash를 유발할 가능성이 있다.
• 이 부분의 코드를 수정 할 때, net.SubObjects.CompareWithLegacy를 Console Command로 설정하면
  Runtime에서 Registered SubObjectList와 이전 함수를 비교할 수 있다.
  • 차이점이 감지되면 ensure가 발생한다.

Components

• Replicated Component도 기본적으로 Subobject와 동일하다.
  • Component의 경우에는 AllowActorComponentToReplicate 함수를 override 한다.
  • 이 때 각 Component의 Replicate Condition은 내부 조건문에 맞춰 판정, 반환해야 한다.
• 만약 BeginPlay가 호출 된 이후에 Component의 ReplicateCondition을 바꾸고 싶다면,
  SetReplicatedComponentNetCondition 함수를 이용한다.
• Owning Component List는 Condition이 확인되기 전에 각 Connection에 Replicate 되어야 한다.
  • 예를 들어 Componenet가 SkipOwner인 경우,
    SubObject가 OwnerOnly이더라도 Owner에게 Replicate 되지 않는다.

ELifetimeCondition AMyWeaponClass::AllowActorComponentToReplicate(const UActorComponent* ComponentToReplicate) const
{
    // Do not replicate some components while the object is on the ground.
    if (!bIsInInventory)
    {
        if (IsA<UDamageComponent>(ComponentToReplicate))
        {
            return COND_Never;
        }
    }
    Super::AllowActorComponentToReplicate(ComponentToReplicate);
}

void AMyWeaponClass::OnPickup()
{
    // Now replicate the component to all
    SetReplicatedComponentNetCondition(UDamageComponent, COND_None);
    bIsInInventory = true;
}

Complex Replication Condition

• NetConditionGroupManager와 COND_NetGroup을 이용해 Replicate Condition을 새로 만들 수 있다.
• 이는 Subobject와 PlayerController가 여러 Group에 동시에 속해 있을 때,
  이 중 하나의 Group에만 속해 있어도 Replicate된다.

FName NetGroupAlpha(TEXT("NetGroup_Alpha"))

• 원하는 Subobject를 위에서 추가한 NetGroupAlpha Group에 추가한다.

FNetConditionGroupManager::RegisterSubObjectInGroup(MyAlphaSubObject, NetGroupAlpha)

• Subobject를 Replicate 할 Client의 PlayerController를 이용해 같은 Group에 추가한다.

PlayerControllerAlphaOwner->IncludeInNetConditionGroup(NetGroupAlpha)

• 이제 PlayerControllerAlphaOwner의 Client는 Owner Actor가 해당 Client의 Connection에 Replicate 될 때마다
  등록된 MyAlphaSubobject를 Replicate 받는다.

Client Subobject List

• Server가 Replicated Subobject List를 관리하는 것처럼, Client도 자체적으로 Subobject List를 관리해야 한다.
  • 이는 특히 Client에서 Replay를 녹화할 때 중요하다.
  • 이 경우, Client의 Actor는 Replay에 기록할 때 일시적으로 Local Authority Role로 전환된다.
  • 그렇기에 Replay에 기록된 Actor은 Local Role에 상관 없이
    Client에서 자체적으로 Subobject List를 유지해야 한다.
• 만약 Subobject가 Replicated Property라면, RepNotify를 사용함으로 더 쉽게 관리할 수 있따.
  • Client는 RepNotify를 통해 SubObject가 변경되었음을 확인하여,
    이전 포인터를 제거하고 새로운 것을 추가할 수 있다.
• Server의 Subobject List에서 Replicated Subobject를 제거하면
  해당 Object의 Replicated Property가 Client에 Replicate 되지는 않는다.
  • 하지만 SubObject의 포인터는 UObject가 스스로를 Grabage라고 마크 하기 전까지 Net-Referencable하다.
  • Server가 UObject가 Invalid하다 탐지하게 되면,
    다음 Reflection 업데이트에서 Client로 하여금 자체적으로 해당 Subobject를 지우도록 알린다.