언리얼 엔진에서 nDisplay와 함께 클러스터 이벤트 사용하기 | 언리얼 엔진 5.4 문서

클러스터 이벤트를 사용하면 nDisplay 클러스터의 모든 노드가 여러 이벤트에 동시에 응답하게 할 수 있습니다.

클러스터 이벤트는 클러스터의 노드에서 또는 이 노드를 외부 애플리케이션에서 프라이머리 노드로 전송하여 생성할 수 있습니다. 자세한 내용은 블루프린트에서 클러스터 이벤트 방출하기 또는 외부 애플리케이션에서 클러스터 이벤트 방출하기를 참고하세요.
클러스터의 프라이머리 노드는 클러스터 이벤트를 수신할 때 해당 이벤트가 동일한 프레임의 각 노드에서 정확하게 발생하도록 클러스터의 각 노드로 이벤트를 전파합니다.
언리얼 엔진 애플리케이션의 블루프린트 또는 C++ 로직 내에서는 프로젝트에 필요한 게임플레이 로직이 무엇인지에 관계없이 이러한 클러스터 이벤트를 탐지하고 응답할 수 있도록 리스너를 구성할 수 있습니다. 블루프린트에서 클러스터 이벤트에 응답하기를 참고하세요.

클러스터 이벤트 포맷

nDisplay가 클러스터 이벤트에 대해 지원하는 포맷은 JSON과 바이너리 두 타입으로 나뉩니다. JSON 포맷은 사람이 읽을 수 있는 포맷입니다. 이 포맷은 JSON 표준에 의해 일부 문자의 사용이 금지된 상태에서 ASCII를 사용하며, 데이터를 구조화하기 위한 특수한 스키마를 필요로 합니다. 바이너리 포맷에서는 그 종류에 관계없이 바이너리 데이터를 사용할 수 있고, 사용자가 시리얼라이제이션과 디시리얼라이제이션의 수행 여부를 결정합니다. 클러스터 이벤트에서는 JSON 포맷보다 바이너리 포맷을 사용하는 것이 데이터 처리량 및 지연시간 측면에서 퍼포먼스가 더 뛰어납니다.

JSON 클러스터 이벤트 구조

각 JSON nDisplay 클러스터 이벤트에는 다음과 같은 다양한 프로퍼티가 포함될 수 있습니다.

세팅	타입
이름(Name)	스트링
타입(Type)	스트링
카테고리(Category)	스트링
시스템 이벤트(System Event)	이 이벤트가 시스템인지 또는 사용자 이벤트인지를 지정하는 부울입니다. 이 플래그는 직접 설정할 필요가 없습니다.
반복 시 폐기 여부(Should Discard on Repeat)	이름, 타입 및 카테고리 가 동일하고 현재 프레임 내에서 이미 수신된 적 있는 이벤트를 페기할지 여부를 지정하는 부울입니다.
파라미터(Parameters)	키와 값 모두 스트링인 키-값 쌍의 선택적 맵입니다.

프로젝트의 프로퍼티 각각에서 어떤 데이터를 전송할지와 리스너가 해당 데이터를 해석하는 방식을 결정하는 것은 사용자의 몫입니다.

블루프린트에서 JSON 클러스터 이벤트와 인터랙션할 경우 Make DisplayClusterClusterEventJson 노드와 Break DisplayClusterClusterEventJson 노드를 사용하여 JSON 클러스터 이벤트를 구성 및 분해할 수 있습니다. 예를 들면 다음과 같습니다.

C++인 경우 또는 자신의 애플리케이션에서 JSON 클러스터 이벤트를 방출하는 경우 FDisplayClusterClusterEventJson 구조체를 사용하여 동일한 구조를 표현할 수 있습니다.

바이너리 클러스터 이벤트 구조

각 바이너리 클러스터 이벤트에는 다양한 프로퍼티가 포함될 수 있습니다.

세팅	타입
이벤트 ID(Event Id)	32비트 인티저
시스템 이벤트	이 이벤트가 시스템인지 또는 사용자 이벤트인지를 지정하는 부울입니다. 이 플래그는 직접 설정할 필요가 없습니다.
반복 시 폐기 여부	이벤트 ID 가 동일하고 현재 프레임 내에서 이미 수신된 적 있는 이벤트를 폐기할지 여부를 지정하는 부울입니다.
이벤트 데이터(Event Data)	바이트 배열

프로젝트의 프로퍼티 각각에서 어떤 데이터를 전송할지와 리스너가 해당 데이터를 해석하는 방식을 결정하는 것은 사용자의 몫입니다.

블루프린트에서 바이너리 클러스터 이벤트와 인터랙션할 경우 Make DisplayClusterClusterEventBinary 노드와 Break DisplayClusterClusterEventBinary 노드를 사용하여 바이너리 클러스터 이벤트를 구성 및 분해할 수 있습니다. 예를 들면 다음과 같습니다.

C++인 경우 또는 자신의 애플리케이션에서 바이너리 클러스터 이벤트를 방출하는 경우 FDisplayClusterClusterEventBinary 구조체를 사용하여 동일한 구조를 표현할 수 있습니다.

블루프린트에서 클러스터 이벤트 방출하기

다음 예시는 블루프린트 클래스에서 JSON 클러스터 이벤트를 방출하는 방법을 보여줍니다. 이러한 동일한 단계들을 일부만 수정하여 사용하면 블루프린트 클래스에서 바이너리 클러스터 이벤트를 방출할 수 있습니다.

프로젝트의 블루프린트 클래스에서 JSON 클러스터 이벤트를 방출하려면 다음 단계를 따릅니다.

DisplayCluster Module API(블루프린트 API 참고)를 찾아 클러스터(Cluster) > Emit JSON cluster event 함수를 호출합니다. 이 노드는 클러스터 이벤트를 API에서 마스터 노드로 명명된 프라이머리 노드로 실행하고, 프라이머리 노드는 해당 이벤트를 클러스터의 모든 노드로 다시 전파합니다.

Click image to expand.
기본적으로 언리얼 엔진 애플리케이션의 모든 인스턴스는 게임플레이 로직에서 이 블루프린트 노드를 평가하며 이 클러스터 이벤트를 실행합니다. 이 블루프린트 그래프가 클러스터의 여러 노드에서 평가를 거치는 경우, 이로 인해 여러 개의 이벤트 사본이 발생할 수 있습니다. 클러스터 이벤트 사본 여러 개가 트리거되지 않게 하려면 Emit JSON cluster event 노드에서 프라이머리만(Primary Only) 부울 값을 설정하면 됩니다. 이 박스를 체크하면 프라이머리 노드만 이 클러스터 이벤트를 방출합니다. 이외의 프라이머리가 아닌 클러스터 노드에서 동일한 블루프린트 그래프를 평가하면 해당 노드가 이벤트를 방출하지 않습니다.
Emit JSON cluster event 노드의 이벤트(Event) 포트에서 왼쪽으로 드래그한 후 Make DisplayClusterClusterEventJson 을 선택합니다.

Click image to expand.
Make DisplayClusterClusterEventJson 노드의 세팅을 사용하여 이름, 타입 및 카테고리 의 스트링 값으로 클러스터 이벤트를 구성합니다. 클러스터 이벤트를 따라 임의의 키-값 데이터를 전달해야 하는 경우, 해당 키 및 값의 맵을 파라미터 입력으로 전달할 수도 있습니다.

Click image to expand.
블루프린트를 컴파일 하고 저장 합니다.

다음 번에 프로젝트를 다시 패키징하고 nDisplay 클러스터를 재실행하면 이 블루프린트 코드가 이전에 구성한 JSON 클러스터 이벤트를 호출합니다. 블루프린트 코드의 다른 영역에서 이 이벤트에 응답하는 방법에 대한 자세한 내용은 블루프린트에서 클러스터 이벤트에 응답하기를 참고하세요.

외부 애플리케이션에서 클러스터 이벤트 방출하기

nDisplay 클러스터를 시작하면 프라이머리 노드가 특정 로컬 포트에서 들어오는 클러스터 이벤트를 수신하기 시작합니다. 해당 포트로 연결하여 메시지를 전송하면 네트워크의 다른 컴퓨터에서 실행되는 다른 애플리케이션에서 nDisplay 시스템으로 클러스터 이벤트를 방출할 수 있습니다. JSON 포트 리스너와 바이너리 포트 리스너 모두 TCP를 사용하므로 클러스터 세션이 끝날 때까지 연결을 열린 상태로 유지할 수 있습니다.

방출할 각각의 클러스터 노드에 대해 메시지는 다음과 같은 규칙을 따라야 합니다.

첫 4개 바이트는 나머지 메시지의 총 길이를 나타내야 합니다.
메시지의 나머지 내용은 클러스터 이벤트의 콘텐츠로, JSON 오브젝트 또는 바이너리 데이터 중 하나로 표현되어야 합니다.
- JSON 이벤트 메시지의 경우:
  - JSON 오브젝트는 필수 필드인 이름, 타입, 카테고리, 시스템 이벤트, 반복 시 폐기 여부 및 선택적 필드인 파라미터 와 함께 제공됩니다.
- 바이너리 이벤트 메시지의 경우:
  - 4개 바이트는 이벤트 ID에 해당합니다.
  - 1개 바이트는 '시스템 이벤트' 부울에 해당합니다.
  - 1개 바이트는 '반복 시 폐기 여부' 부울에 해당합니다.
  - N개 바이트는 바이너리 데이터에 해당하며, N에 들어갈 숫자의 범위에는 제한이 없습니다.

예를 들어 이름이 'quit'이고 타입이 'command'인 JSON 클러스터 이벤트를 방출하려면 다음 작업을 수행해야 합니다.

클러스터 노드의 값을 포함하는 JSON 스트링을 구성합니다. 이 경우에는 스트링 형태가 다음과 같습니다.
```
        {"Name":"quit","Type":"command","Category":"","Parameters":{}}
		
```
{"Name":"quit","Type":"command","Category":"","Parameters":{}}
이름, 타입 및 카테고리 필드는 필수 필드이지만 '파라미터' 필드는 생략할 수 있습니다. 일부 필드가 필수 필드이긴 하지만, 필드가 비어 있는 이벤트는 같이 그룹화할 수 있으므로 빈 값을 어떤 필드로도 할당할 수 있습니다. 가독성을 높이기 위해 이름과 ID를 입력하는 것이 좋습니다.
JSON 스트링의 길이(이 경우 62자)를 구한 후, 4개 바이트를 사용하여 해당 길이를 바이너리 포맷의 nDisplay 프라이머리 노드로 전송합니다. 이 예시에서는 0x00111110 입니다.
JSON 스트링 자체를 nDisplay 프라이머리 노드로 전송합니다.

기본적으로 프라이머리 노드는 포트 41003의 클러스터 이벤트와 포트 41004의 바이너리 클러스터 이벤트를 수신합니다. 이러한 디폴트는 nDisplay 환경설정 파일에서 변경할 수 있습니다. 자세한 내용은 nDisplay 커뮤니케이션 포트 변경하기 페이지를 참고하세요.

프로젝트의 블루프린트 코드에서 이러한 클러스터 이벤트에 응답하는 방법에 대한 자세한 내용은 블루프린트에서 클러스터 이벤트에 응답하기를 참고하세요.

블루프린트에서 클러스터 이벤트에 응답하기

앞에서 설명한 메서드 중 하나를 구성하여 클러스터 이벤트를 nDisplay 네트워크로 방출한 후에는 블루프린트 또는 C++ 게임플레이 로직을 구성하여 이러한 클러스터 이벤트를 탐지하고, 일정한 방법으로 해당 이벤트에 응답할 수 있습니다. 이를 실행하려면 리스너, 즉 DisplayClusterClusterEventListener 인터페이스를 구현하는 클래스를 생성 및 등록해야 합니다. nDisplay API에서 Add Cluster Event Listener 함수를 호출하여 리스너를 등록하고 Event On Cluster Event 노드를 사용하여 클러스터 이벤트를 탐지하고 응답합니다.

예를 들어 새 블루프린트 클래스를 생성하고 리스너로 등록하려면 다음 단계를 따릅니다.

콘텐츠 브라우저 에서 우클릭하고 기본 에셋 생성(Create Basic Asset) > 블루프린트 클래스(Blueprint Class) 를 선택합니다.

이미지를 클릭하면 확대됩니다.
액터(Actor) 를 부모 클래스로 선택합니다.
콘텐츠 브라우저 에서 새로운 리스너 클래스의 이름을 입력합니다.
클래스를 레벨 뷰포트로 드래그한 다음 레벨에 드롭합니다.

이미지를 클릭하면 확대됩니다.
새 블루프린트 클래스를 편집하려면 더블클릭합니다.
툴바에서 클래스 세팅(Class Settings) 을 클릭합니다.
디테일(Details) 패널에서 인터페이스(Interfaces) > 구현된 인터페이스(Implemented Interfaces) 세팅을 찾아 추가(Add) 를 클릭합니다.
목록에서 DisplayClusterClusterEventListener 인터페이스를 찾아 선택합니다.
툴바에서 컴파일(Compile) 을 클릭하여 클래스를 컴파일합니다.
이벤트 그래프(Event Graph) 탭에서 다음과 같이 그래프를 구성하여 리스너를 등록합니다.

이미지를 클릭하면 확대됩니다.

구성 방법은 다음과 같습니다.
1. Begin Play 이벤트 노드의 출력에서 오른쪽으로 드래그한 후 N Display > DisplayCluster Module API 를 선택합니다.
2. 해당 노드의 Out API 포트에서 오른쪽으로 드래그한 후 클러스터 표시(Display Cluster) > 클러스터 > Add cluster event listener 를 선택합니다.
3. 마지막으로, Add cluster event listener 노드의 리스너(Listener) 포트에서 왼쪽으로 드래그한 후 변수(Variables) > Get a reference to self 를 선택합니다.
리스너가 더는 필요 없는 경우에는 생성한 각 리스너를 소멸시키는 것도 좋은 방법입니다. 예를 들어 블루프린트 액터를 소멸시킬 때는 다음과 같이 하면 됩니다.

이미지를 클릭하면 확대됩니다.

구성 방법은 다음과 같습니다.
1. 이벤트 그래프에서 우클릭하고 이벤트 추가(Add Event) > Event Destroyed 노드를 선택합니다.
2. Event Destroyed 노드의 출력에서 오른쪽으로 드래그한 후 N Display > DisplayCluster Module API 를 선택합니다.
3. 해당 노드의 Out API 포트에서 오른쪽으로 드래그한 후 클러스터 표시 > 클러스터 > Remove cluster event listener (Interface Call) 를 선택합니다.
4. 마지막으로, Remove cluster event listener 노드의 리스너(Listener) 포트에서 왼쪽으로 드래그한 후 변수 > Get a reference to self 를 선택합니다.
이벤트 그래프 의 다른 영역에서 이벤트 추가 > N Display > Event On Cluster Event Json 노드를 추가합니다. nDisplay 클러스터에서 JSON 클러스터 이벤트가 발생할 때마다 이 이벤트가 트리거됩니다. 이 이벤트에 할당된 세팅과 파라미터를 읽을 수도 있습니다. 이렇게 하면 해당 세팅 및 파라미터를 사용하여 블루프린트에 대해 어떤 조치를 취할지 결정할 수 있습니다. 이렇게 하려면 Event On Cluster Event Json 노드의 이벤트 포트에서 오른쪽으로 드래그한 후 Break DisplayClusterClusterEventJson 을 선택합니다. 예를 들어 이 그래프는 각 JSON 클러스터 이벤트의 이름 값을 스크린에 출력하기만 합니다.

이미지를 클릭하면 확대됩니다.
블루프린트 클래스를 컴파일 하고 저장 합니다.

다음 번에 클러스터에서 어떤 소스에서든 JSON 클러스터 이벤트를 방출할 때는 해당 JSON 클러스터 이벤트의 이름이 스크린에 출력됩니다.