Roland Bruggmann — Portfolio

Personal Pages

« Back to Main Page

Unreal Engine Plugin: Distributed Game Engine DGE

Version: v2.0.1
Author: Roland Bruggmann


Screenshot of Plugin Content

Screenshot of Plugin C++ Classes

A game plugin providing with Display Cluster rendering and Remote Control related assets. These are mainly Blueprints inheriting from plugin ‘ESB Messaging’ but customized to a distributed setup based on Unreal Display Cluster aka. nDisplay.



C++ Classes


The plugin was developed using Visual Studio 2019. It makes use of code and/or assets from other plugins which must also be installed (cp. package diagram):

With using this plugin also engine plugin nDisplay is enabled.

Screenshot of Package Diagram


Use the plugin as project plugin (folder MyProject/Plugins). Add the plugin by downloading and unpackaging an archive or using git clone:

git clone

Screenshot of Plugin

Table of Contents

1. Messaging Concept

The messaging concept is the same as in Plugin ESBMessaging, but extended by a nDisplay JSON Cluster Event, which distributes an ESB-Message within the display cluster.

1.1. Message Transport

The plugin implements the ZeroMQ PUB/SUB Pattern from Plugin ‘ZeroMQ’. E.g., the demo map uses a communication channel as follows:

Communication Diagram DGE ‘ESBEvent’, Display Cluster Main Node:

Communication Diagram DGE 'ESBEvent' Display Cluster Main Node 1/2 Communication Diagram DGE 'ESBEvent' Display Cluster Main Node 2/2

Communication Diagram DGE ‘ESBEvent’, Display Cluster Client Node:

Communication Diagram DGE 'ESBEvent' Display Cluster Client Node

1.2. Interfaces and JSON Message

The interfaces and the JSON Messages are taken from Plugin ESBMessaging. Before processing an ESB-Message it is distributed within the display cluster by a nDisplay JSON Cluster Event.

1.3. JSON Cluster Event

UE4 JSON Cluster Event defined by Epic Games translated to JSON schema, found in folder /Testing/Schemas: UE4 DisplayCluster ClusterEvent v1.0, Schema.

Example: UE4 DisplayCluster ClusterEvent v1.0, Example

    "Name": "activate",
    "Type": "command",
    "Category": "particles",
    "SystemEvent": "false",
    "ShouldDiscardOnRepeat": "false",
    "Parameters": {
        "rate": "200",
        "speed": "3"

UE4 JSON Cluster Event for ESBMessages declared as JSON schema, found in folder /Testing/Schemas: UE4 DisplayCluster ClusterEvent ESBMessage v1.0, Schema.

Example: UE4 DisplayCluster ClusterEvent ESBMessage v1.0, Example, Parameter ‘Message’ transports the ESB-Message as JSON-ObjectString

    "Name": "DGETextRender",
    "Type": "Sync",
    "Category": "ESBEvent",
    "SystemEvent": "false",
    "ShouldDiscardOnRepeat": "false",
    "Parameters": {
        "Message": "{\"ObjectName\":\"DGETextRender\",\"Function\":{\"FunctionName\":\"SetTransform\",\"Parameter\":{\"Location\":{\"X\":1,\"Y\":-3,\"Z\":2},\"Rotation\":{\"X\":0,\"Y\":0,\"Z\":0},\"Scale\":{\"X\":1,\"Y\":1,\"Z\":1}}}}"

1.4 DGE Cluster Event Handler Component

In the display cluster an ESBMessage is distributed by calling DGEClusterEventHandlerComponent BlueprintCallable function node EmitDGEClusterEvent. The Component DGE ClusterEvent field values are found in DGEClusterEventHandlerComponent > Details > DGE (Category, Type, Name, Parameter Key). The DGEClusterEventHandlerComponent has also a ClusterEventListener. When receiving a cluster event, the same gets filtered with the given fields an the Parameter ‘Message’ is returned with the event OnDgeClusterEvent (DGEClusterEventHandler).

Screenshot DGEClusterEventHandlerComponent:

Screenshot DGEClusterEventHandlerComponent BlueprintCallable Function Node 'EmitDGEClusterEvent'

1.5. DGE Message Handler Actor

A DGEMessageHandlerActor:

DGEMessageHandlerActor inheriting classes:

Screenshot Blueprint DGEMessageHandlerActor:

Screenshot Blueprint DGEMessageHandlerActor

Class Diagram DGEMessageHandlerActor:

Class Diagram DGEMessageHandlerActor

The event-dispatchers are implemented as dynamic multicast delegates which can be bound several times at the same time (multicast) and may be used in C++ as well as in Blueprints, both (dynamic) (cp. table ‘Overview Event-Dispatcher Macros’):

Overview Event-Dispatcher Macros

1.5.1. DGE TextRender Actor

A DGETextRenderActor: UE4 TextRender Alignment

Change of horizontal and/or vertical alignment results in a visually moving center of the text as the alignment is in relation to the TextRender pivot (cp. screenshots below).

Screenshots of TextRender: 1) horizontal alignment ‘left’ combined with vertical alignment ‘bottom’ (default); 2) horizontal alignment ‘center’ combined with vertical alignment ‘center’; 3) horizontal alignment ‘right’ combined with vertical alignment ‘top’:

Screenshot of TextRender horizontal alignment 'left' combined with vertical alignment 'bottom' Screenshot of TextRender horizontal alignment 'center' combined with vertical alignment 'center' Screenshot of TextRender horizontal alignment 'right' combined with vertical alignment 'top'

1.5.2. DGE MediaPlayer Actor

A DGEMediaPlayerActor: UE4 MediaPlayer State Machine

Behavior of UE4 MediaPlayer:

Transition table:

State Diagram ‘MediaPlayer’:

State Diagram 'MediaPlayer' UE4 MediaPlayer Playback Synchronisation

UE4 MediaPlayer does not synchronise video playback in the display cluster. Therefore the start of video playback may be synced by a workaround-sequence:

For short videos this may work - but after a couple of seconds the playback will be out of sync. Therefore video playback synchronisation by video streaming is recommended. VLCMedia Multicast and Netsync

VLC as Streaming Server and UE4-Plugin VlcMedia as stream consumer (replace <VlcStreamingServerIP> by IP of choice): Professional approach by Epic Games

See also:

Generator Locking (Genlock) is a common technique where the video output of one source or a specific reference signal from a signal generator is used to synchronize other picture sources together. The aim in video applications is to ensure the coincidence of signals in time at a combining or switching point. When video instruments are synchronized in this way, they are said to be generator-locked, or genlocked (cp. Ward14). For this purpose a SampleClock is used. Its TimeCode is distributed over network by SMPTE timecode protocol.

1.6. DGE Message Handler Child Actor

A DGEMessageHandlerChildActor:

DGEMessageHandlerChildActor inheriting classes:

Screenshot Blueprint DGEMessageHandlerChildActor:

Screenshot Blueprint DGEMessageHandlerChildActor

1.6.1. DGE Pupil Gaze Actor

A DGEPupilGazeActor:

Screenshot Blueprint DGEPupilGazeActor:

Screenshot Blueprint DGEPupilGazeActor

Class Diagram DGEPupilGazeActor:

Class Diagram DGEPupilGazeActor Trace for Hit Generation

On DGEPupilGazeActor calling function SetLocationAndRotation, SetTransformQuat, SetTransform, SetLocation, SetRotation or SetRotationQuat, the APupilGazeActor private function Trace is triggered which performs a ray-tracing trying to generate a hit (channel visibility) and updates following ChildActorComponent values:

In case of a hit the objects are updated using values from the hit-result. If no hit was obtained, the objects are updated with values from the trace end.

2. Blueprint Function-Library

The Blueprint Function-Library provides with two functions

Screenshot Blueprint Function-Library:

Screenshot DGE Blueprint Function-Library

3. Blueprints

3.1. BP DGE Watchdog

Screenshot Blueprint BP_DGE_Watchdog:

Screenshot Blueprint BP_DGE_Watchdog

3.2. BP DGE MediaPlayer2D

Please consider:

3.3. BP DGE MediaPlayer360

Please consider:

3.4. BP DGE TextRender

Please consider:

3.5. BP DGE BlackShieldBack

3.6. BP DGE BlackShieldFloor

3.7. BP DGE BlackShieldFront

3.8. BP DGE BlackShieldLeft

3.9. BP DGE BlackShieldRight

3.10. BP DGE ClearColor

Please consider:

3.11. BP DGE CollisionWarning

3.12. BP DGE Head

3.13. BP DGE PupilGaze0

Please consider:

3.14. BP DGE PupilGaze0Ray

Please consider:

3.15. BP DGE PupilGaze0Hit

Please consider:

3.16. BP DGE PupilGaze1

Please consider:

3.17. BP DGE PupilGaze1Ray

Please consider:

3.18. BP DGE PupilGaze1Hit

Please consider:

3.19. BP DGE PupilShapeTarget

Please consider:

4. Testing

4.1. Demo Actor and Demo Map

Blueprint ESBMessaging Demo Actor BP_DGE_DemoActor:

Screenshot of Blueprint BP_DGE_DemoActor

Screenshot of BP_DGE_DemoActor

Map Map_DGE_Demo, World Outliner:

Screenshot of Map_DGE_Demo:

Screenshot of Map_DGE_Demo

In the ESBMessaging demo map Map_DGE_Demo LevelBlueprint the ZeroMQ-Sockets of ZmqSubSocketActor and ZmqPubSocketActor are bound. Finally a timer triggered event starts to call ZmqSubSocketActor function Receive every millisecond.

Screenshot of Map_DGE_Demo LevelBlueprint:

Screenshot of Map_DGE_Demo LevelBlueprint

4.2. Packaging

Brief instruction: Packaging, e.g., a shipping build (cp. Packaging Projects):

  1. Project Settings > Project > Maps & Modes > Default Maps > Game Default Map: Map_DGE_Demo
  2. File > Package Project > Build Configuration > Shipping
  3. File > Package Project > Windows (64-bit)
  4. Point to a folder of your choice

In the folder of your choice a folder ‘WindowsNoEditor’ is created containing the executable file (*.exe).

4.3 nDisplay Launcher

The UE4 DisplayCluster aka nDisplay configuration files may be found in Folder MyProject/Content/ExampleConfigs. nDisplay config files *.cfg are edited using a text editor of choice (cp. Unreal Engine Documentation nDisplay Configuration File Reference).

Brief instruction to run a display cluster game unwrapped locally on your machine (cp. nDisplay Quick Start):

  1. Find and launch nDisplay Listener and nDisplay Launcher (folder ‘C: \Program Files \Epic Games \UE\ _4.26 \Engine \Binaries \DotNET’ or similar)
  2. In nDisplay Launcher, Tab ‘Launcher’, List of Applications > Click Button ‘Add’: Point to the shipping build executable ‘*.exe’ in folder ‘WindowsNoEditor’
  3. In nDisplay Launcher, Tab ‘Launcher’, Config Files Dropdown > Click Button ‘Add’: Point to a Display Config, e.g., MyProject \Content \ExampleConfigs \cave_5_sides_unwrap.cfg
  4. Click Button ‘Run’

Screenshot of nDisplay Listener:


Screenshot of nDisplay Launcher:


Screenshot of nDisplay Unwrap:


4.3.1 Load Non Default Map

To load a map other than the default one, e.g., map “My_Other_Map”, in nDisplay Launcher enter the following custom command line arguments (cp. Unreal Engine Documentation, Command Line Arguments):


4.4 Jupyter Notebook

For testing purpose plugin ESBMessaging provides with Jupyter Notebooks:

Please find instructions on how to install Anaconda and setup Jupyter Notebook in plugin ESBMessaging folder ‘Testing’.

Screenshot of Jupyter Notebook ESBMessaging ZeroMQ Publish:

Screenshot of Jupyter Notebook ESBMessaging ZeroMQ Publish

A. References

« Back to Main Page