코히런트 GT라는 UI 솔루션을 UE4에 통합하는 방법과 간단한 사용법 정리한 것을 공유 합니다. 이 문서를 제공하는데 있어 구진수씨가 고생 많이 했습니다. 이 자리를 빌어 수고했다고 말씀드리고 싶습니다.

1. 2016-01-14
Jinsu Gu, Kiyoung Moon

2.  HTML5 기술을 사용한 UI Solution
 http://coherent-labs.com/

4.  http://coherent-labs.com/download-coherent-
gt/ 에 접속하면 위와 같은 화면이 나오며,
양식에 맞게 내용을 입력한 후에 기다리면
입력한 메일로 평가판을 다운로드 받을 수
있는 링크가 전달된다. 해당 파일을 다운로
드 받도록 한다.

5.  다운로드가 완료된 파일을 실행하여 설치
를 진행한다.

8.  클린 설치가 필요하다면 선택한다.

9.  언리얼 엔진 4용 Coherent GT 플러그인
 기존 프로젝트에 Coherent GT 추가
 샘플 게임
 프로젝트 파일 생성
 GTPlayer (특정 페이지를 빠르게 볼 수 있는 단
독 프로그램)
데모 버전 기준으로 비주얼 C++ 2015 런타임
이 필요하며, 다음 링크에서 받을 수 있다.
https://www.microsoft.com/ko-
KR/download/details.aspx?id=48145

10.  플러그인을 설치할 언리얼을 선
택하는 화면이다. 현재 환경에서
는 직접 소스파일을 받아서 사용
하고 있기 때문에, 아래의 Source
build at : (경로) 중에서 테스트를
원하는 엔진 경로를 선택하면 된
다.

11.  예제 FPS 게임을 생성할
경로를 선택한다.

12.  GTPlayer를 설치할 경
로를 선택한다.

13.  설치 완료

14.  다운로드 받은 예제 프로젝트를 실행하여
테스트 플레이를 해볼 수 있다. 처음부터 시
작하기 원한다면 아래의 내용을 따라해보
도록 하자.

15.  우선 UI로 출력할 HTML 파일을 준비한다.
이 파일을 프로젝트 내부에 넣는다. 예제 프
로젝트 기준에서 기본으로 출력되는 파일
의 위치는 (프로젝트 폴
더)ContentuiresourcessosMainUI.html 이
다.
 언리얼 에디터에서 플러그인 형식으로 인
식이 되고 있어야 한다.

18.  테스트한 환경에서는 엔진에 직접 넣었기 때
문에 Built-In 내부에 출력되며, 프로젝트에 플
러그인 형식으로 설치된 경우 약간 위치가 다
를 수 있다.
 User Interface 항목에서 Coherent GT가 보이는
지, Enabled 항목이 활성화되었는지 확인한다.
해당 항목이 없다면 엔진을 다시 빌드 해본 뒤
에 재확인해보도록 하자.
Enabled가 체크되어 있지 않다면 체크 후에 에
디터를 재 시작하도록 하자.

20.  페이지를 출력하는 방법은 두 가지 방법이
있다. 블루 프린트를 이용한 방법과 C++에
서 직접 페이지를 로드 해서 출력한다.

21.  출력하기 원하는 페이지를 html 파일로 작성한다.
포토샵에서 html 출력을 지원하므로 만약 포토샵이
있다면 편하게 결과물을 만들 수 있다.
 새로운 맵을 생성한 뒤에, 새로운 게임모드 블루프
린트를 생성한다.
 게임모드 블루프린트에서 HUD 항목으로 사용할
블루프린트를 생성한다. 이 블루프린트는
CoherentUIGTGameHUD.h를 상속받도록 한다.
 이 예제에서는 레벨 블루프린트에서 모든 작업을
진행할 것이므로 새로 만든 맵의 레벨 블루프린트
를 열도록 하자. 그 뒤에 아래 그림을 참고하여 블루
프린트를 생성하도록 하자. (자세히 보려면 문서를
확대하거나 외부 이미지를 참고하자)

22.  위 블루프린트에서 수정할 부분은 Setup
UIGTView 항목의 Page URL이다. 작성한
HTML 파일의 경로를 설정 하도록 하자.

24.  CoherentUIGTGameHUD 클래스를 상속받
은 클래스를 생성한 뒤에 생성자에서 다음
구문을 사용한다.
 출력할 HTML의 경로에 맞게 주소를 작성
해주면 된다. 이후 에디터에서 게임 모드의
HUD Class를 방금 만든 클래스로 설정하도
록 하자.
SetupUIGTView("coui://UIResources/hud.html", true, 0, 0);

25.  이때 TestCoHUD와 CoherentUIGTGameHUD의 관계는 다음과 같다.
TestCoHUD
CoherentUIGTGameHUD

26.  블루 프린트로 페이지를 표시할 때와 똑같이 화면이 나타난다.

27.  Coherent HUD 자체는 포커스를 가지고 있
지 않다. Coherent UI로의 입력은
SCoherentUIGTInputForward 라는 빈 화면
을 가진 위젯을 통해서 이루어진다. 위젯을
직접 생성해도 되고,
ACoherentUIGTInputActor가 이 위젯을 가
지고 있으므로 이 액터를 생성해도 된다. 액
터를 사용하려고 할 때에는 Initialize 함수를
호출하여야만 위젯이 생성되므로 참고하자.

28.  SpawnActor 노드를 사용하여 액터를 소환
한 뒤에 Initialize 노드로 초기화를 수행한다.

29. if (GEngine->IsValidLowLevel())
{
AActor* inputActor = GetWorld()->SpawnActor(ACoherentUIGTInputActor::StaticClass());
ACoherentUIGTInputActor* coInputActor = Cast<ACoherentUIGTInputActor>(inputActor);
coInputActor->Initialize();
}
Initialize()를 수행하지 않으면 위젯이 생성되지 않아 UI 입력이 되지 않는다.

30. TSharedPtr<class SCoherentUIGTInputForward> CoherentUIGTInputForwardWidget
= SNew(SCoherentUIGTInputForward).Owner(this);
if (GEngine->IsValidLowLevel())
{
GEngine->GameViewport->AddViewportWidgetContent(
SNew(SWeakWidget).PossiblyNullContent(
CoherentUIGTInputForwardWidget.ToSharedRef()));
}
if (CoherentUIGTInputForwardWidget.IsValid())
{
CoherentUIGTInputForwardWidget->SetVisibility(EVisibility::Visible);
}

31.  이후 위젯에 포커스를 입력하고 싶을 때에
는 이 함수를 사용한다.
FSlateApplication::Get().SetKeyboardFocus(CoherentUIGTInputForwardWidget);
포커스를 게임으로 되돌리려면 다음 함수를
사용한다.
FSlateApplication::Get().SetFocusToGameViewport();

32.  자바 스크립트 설정
 UE4 -> JS로 함수를 호출하기 위해서는 JS에서 다
음과 같이 스크립트 설정을 해주어야 한다.
 HUD로 사용할 html 파일에는 coherent.js가 포함되
어야만 한다. 해당 자바스크립트는 Coherent UI의
코어 파일로, Coherent UI의 주요 기능을 사용하기
위해서는 필수적으로 포함되어 있어야 한다.
 또한 스크립트 영역에서는 아래와 같은 구문이 꼭
들어가 있어야 한다.

33.  engine.call("UIGTScriptingReady");
 이 함수를 JS선두에서 호출해 주어 이후
UE4에서 JS함수를 호출할 때 해당 페이지
가 UE4와 상호작용 할 것임을 알린다.

34.  Trigger Javascript Event 노드를 사용하여 JS의 함수를 호출할 수 있다.
다음 예시는 특정 키(스페이스)를 입력했을 때 HUD로 자바스크립트
함수를 호출하는 블루프린트 예제이다.
<Trigger JavaScript Event 노드를 사용해 CallOnUnrealJS함수를 호출한다. 파라메터로 Unreal Engine 4를 전달>

35. 이때 JS파일에서 호출될 CallOnUnrealJS함수가 준비 되어 있어야 하는데
이것은 다음과 같다.
engine.on(‘CallOnUnrealJS’, CallOnUnreal);
첫 번째 인자인 ‘CallOnUnrealJs’는 언리얼에서 함수를 호출할 때 사용할
문자열이며, 두 번째 인자인 CallOnUnreal은 실제 사용할 JS 함수명이다.
위와 같이 설정한 뒤에 언리얼에서 CallOnUnrealJS로 함수를 호출하면 자
바스크립트의 CallOnUnreal 함수가 실행된다.

36.  View->TriggerEvent("CallOnUnrealJS", "Unreal Engine 4");
 TriggerEvent의 첫 번째 인자는 JS에서 호출될 함수의 이름이며 두 번째는 전
달될 값이다. 이때 View 객체는 CoherentUIGTHUD 클래스에서 얻어야 하며,
다음과 같은 함수를 사용하여 얻을 수 있다.
<예제의 HUD는 CoherentUIGTHUD 클래스를 상속받은 클래스 객체 HUD이다>

37.  초기화를 수행한 뒤에 몇몇 이벤트를 바인딩 해주어야 한다. 제공되는 기본
예제 기준으로 바인딩이 필요한 이벤트는 두 가지로, 각각 ReadyForBindings,
JavaScriptEvent이다. 아래는 블루프린트 예제 화면이다.

38. <ReadyForBindings과 JavaScriptEvent노드>

39. 이벤트 바인딩을 할 때 타켓은 형변환된
CoherentUIGTGameHUD를 곧바로 쓰는 것이 아니라, Get
CoherentUIGTHUD 노드를 사용하여 그 결과 값을 사용해
야 한다.
자바스크립트에서 이벤트를 호출하면 JavaScriptEvent와
바인딩한 이벤트 (예제 화면에서는 JavaScriptEvent_이벤
트_0 노드에 해당된다) 가 실행된다. 이벤트명이 문자열로
넘어오므로 문자열을 확인한 뒤에 그에 맞는 수행을 설정
해주어야 한다.
노트 : 즉, 특정 함수명를 호출하는 것이 아니라 오직 하나
의 함수가 호출되며 전달된 값으로 분기하여 함수를 호출
하는 형태.

40.  C++에서 호출될 함수 GetEventFromJS를 등록해 주고 JS에서 ToUnreal이라는 함수를 호출하면 GetEventFromJS가 호
출된다. 예를 들어 ToUnreal이라는 함수가 JS에 있고 내부에서 C++함수를 호출하고 싶다면 engine.call(“함수명”)과
같이 호출하여 C++함수를 호출할 수 있다. 앞서 GetEventFromJS를 ToUnreal과 바인드 해주었는데
engine.call(“ToUnreal”);을 호출하면 GetEventFromJS가 호출된다.

41.  Coherent 플러그인 설치 시 언리얼 내장으로 설치되는 툴
이 3개, 외부 툴이 하나 있다.

42.  메뉴의 Cohernet GT - Launch Editor 항목을
선택하면 실행된다
기본적인 배치를 할 수 있다.
몇몇 이벤트를 넣을 수는 있으나, 애
니메이션을 작성하기에는 조금 부족
하다

43.  메뉴의 Cohernet GT - Launch Inspector 항목
을 선택하면 실행된다. 이 항목은 PIE로 테
스트플레이 중일 때에만 활성화된다.
 크로미엄 (구글 크롬의 오픈소스 버전)의
디버깅 툴과 거의 흡사하다
 각 요소의 위치 등을 확인하거나 자바스크
립트 디버깅을 할 때 등에 활용할 수 있다.
 로딩 속도는 좀 많이 느리다

44.  메뉴의 Cohernet GT - Launch Performance
Auditor 항목을 선택하면 실행된다. 이 항목
은 PIE로 테스트플레이 중일 때에만 활성화
된다.
 현재 사용중인 html 페이지에서 성능상으
로 문제가 될 수 있는 부분을 체크해서 대화
상자로 보여준다.

45.  프로젝트 작업 없이 페이지만 미리 보고 싶을 때 사용할 수 있다
 모든 옵션을 옵션으로 넣어야 하며, 이 때문에 바로가기 옵션으로 설정하거나 커맨드창에서 실행할 필요가 있다
 현재 데모 기준으로 VS 2015 C++ 패키지가 필요하다

46.  애니메이션 제작
 HTML5에서는 자바스크립트 혹은 CSS를 사용해서 애니메이션을 만들 수 있다. 현재
Coherent에서는 자바스크립트를 활용한 애니메이션을 지원한다.
 HTML5 애니메이션 제작 툴은 어도비 엣지, 어도비 플래시가 있다. 엣지는 지원중단이 예
정되어 있고, 차후 플래시에 기능이 집중될 것이라고 한다.
 차후 버전(Coherent UI 2.4)에서 자체 UI 애니메이션 프레임워크를 지원할 예정이라고 한
다.
 화면 비율 문제
 Coherent에서는 출력만 담당할 뿐, 자동적으로 화면에 따른 리사이징 처리 등을 하지는
않는다
 화면 크기에 따른 유동적인 UI 변경을 위해서는 스타일 작성을 신경쓰거나 리사이징할
때마다 사용할 자바스크립트를 작성해두어야 한다
 비동기 모드 (Async Mode)
 동기 모드에서 생길 수 있는 성능상의 문제를 해결하기 위해서 비동기 모드를 사용할 수
도 있다.
 비동기 모드를 사용 시에는 몇가지 추가 설정이 필요하다.
 자세한 내용은 공식 홈페이지의 매뉴얼을 참고하자 (영문)
https://www.coherent-labs.com/Documentation/UnrealEngine4-
GT/d2/df6/_coherent__g_t_for__unreal__engine_4_plugin.html#Async_mode

47. 끝