Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Cluster Events are a way for you to make all the nodes in your nDisplay cluster respond to events simultaneously.

1. You generate a Cluster Event either from a node in the cluster or by sending it to the primary node from an external application. See Emitting Cluster Events from Blueprints or Emitting Cluster Events from External Applications .
   When you have an nDisplay cluster up and running, you can also use the nDisplay Launcher application to send new Cluster Events for your cluster nodes to respond to. See Emitting Cluster Events from the nDisplay Launcher .
   

2. When the primary node of your cluster receives a Cluster Event, it propagates that event to each node in the cluster so that the event happens on each node in exactly the same frame.

3. Within the Blueprint or C++ logic of your Unreal Engine application, you set up listeners to detect these Cluster Events and respond to them with whatever gameplay logic you need for your Project. See Responding to Cluster Events in Blueprints .

Cluster Event Format

There are two types of formats supported by nDisplay for Cluster Events: JSON and binary. The JSON format is human-readable; it uses ASCII, with some characters forbidden by the JSON standard, and requires a specific schema for structuring data. With the binary format, you can use any kind of binary data, and serialization and deserialization is up to you. Using the binary format for Cluster Events has better performance than the JSON format for data throughput and latency.

JSON Cluster Event Structure

Each JSON nDisplay Cluster Event can contain several properties:

It's up to you to decide in your Project what data you want to send in each of these properties, and how you want your listeners to interpret that data.

When you interact with a JSON Cluster Event in Blueprint, you'll use the Make DisplayClusterClusterEventJson and Break DisplayClusterClusterEventJson nodes to construct and deconstruct JSON Cluster Events. For example:

In C++, or when emitting JSON Cluster Events from your own applications, you'll use the FDisplayClusterClusterEventJson struct to express the same structure.

Binary Cluster Event Structure

Each Binary Cluster Event can contain several properties.

It's up to you to decide in your Project what data you want to send in each of these properties, and how you want your listeners to interpret that data.

When you interact with a Binary Cluster Event in Blueprint, you'll use the Make DisplayClusterClusterEventBinary and Break DisplayClusterClusterEventBinary nodes to construct and deconstruct Binary Cluster Events. For example:

In C++, or when emitting Binary Cluster Events from your own applications, you'll use the FDisplayClusterClusterEventBinary struct to express the same structure.

Emitting Cluster Events from Blueprints

The following example shows how to emit JSON Cluster Events from a Blueprint class. You can use these same steps, with some modification, for emitting Binary Cluster Events from a Blueprint class.

To emit a JSON Cluster Event from a Blueprint class in your Project:

1. Get the DisplayCluster Module API (see Blueprint API ), and call its Cluster > Emit JSON cluster event (Interface Call) function. This node fires the Cluster Event out to the primary node, labeled the master node in the API, which propagates it back to all the nodes in the cluster.
   

2. By default, every instance of your Unreal Engine application that evaluates this Blueprint node in its gameplay logic will fire this Cluster Event. If this Blueprint graph gets evaluated on many different nodes in your cluster, this can cause multiple copies of the event to happen.
   To avoid triggering multiple copies of the Cluster Event, you can set the Master Only Boolean value on the Emit JSON cluster event node. If you check this box, only the primary node will emit this Cluster Event. If any other non-primary cluster node evaluates the same Blueprint graph, those nodes will not emit the event.
   

3. Drag left from the Event port on the Emit JSON cluster event node, and choose Make DisplayClusterClusterEventJson .
   

4. Use the settings in the Make DisplayClusterClusterEventJson node to set set up your Cluster Event with string values for its Name , Type , and Category . If you need to pass arbitrary key-value data along with your cluster event, you can also pass a map of those keys and values to the Parameters input.
   

5. Compile and Save your Blueprint.

The next time you repackage your Project and relaunch your nDisplay cluster, this Blueprint code will fire the JSON Cluster Event you've set up. To respond to this event elsewhere in your Blueprint code, see Responding to Cluster Events in Blueprints .

Emitting Cluster Events from External Applications

When you start up your nDisplay cluster, the primary node begins listening for incoming Cluster Events on a specific local port. You can emit new Cluster Events to your nDisplay system from another application running on any other computer in your network by connecting to that port and sending messages. Both JSON and Binary port listeners use TCP, so you can keep the connection open until the cluster session has ended.

For each Cluster Node you want to emit, your message must follow this convention:

• The first four bytes must give the total length of the rest of the message.

• The rest of the message should be the content of your Cluster Event, expressed as either a JSON object or binary data.

  • For JSON event messages:

    • JSON object with the mandatory fields Name , Type , Category , SystemEvent , and ShouldDiscardOnRepeat , and the optional field Parameters .

  • For binary event messages:

    • 4 bytes for the event ID.

    • 1 byte for the System Event boolean.

    • 1 byte for the Should Discard on Repeat boolean.

    • N bytes for the binary data, where there is no limit for N.

For example, to emit a JSON Cluster Event with the name "quit" and the type "command", you would need to:

1. Construct a JSON string that contains the values for your Cluster Node. In this case:

   {"Name":"quit","Type":"command","Category":"","Parameters":{}}

   The Name , Type , and Category fields are mandatory, but you may omit the Parameters field. Although some of the fields are mandatory, you can assign empty values to any of the fields because the events with empty fields will be grouped together. It's recommended to provide names and IDs for readability.

2. Get the length of the JSON string — in this case, 62 characters — and send that length to the nDisplay primary node in binary format with 4 bytes. In this example, it would be 0x00111110 .

3. Send the JSON string itself to the nDisplay primary node.

Emitting Cluster Events from the nDisplay Launcher

While your nDisplay cluster is running, you can use the nDisplayLauncher application to send Cluster Events in to your primary node at any time.

1. Start up your nDisplay cluster as usual.

2. Switch to the Cluster events tab. You'll use this tab to set up Cluster Events and send them to your cluster on demand.

3. Click New to add a new Cluster Event to the list on this tab.
   

4. Use the Cluster event editor window to set up the Name , Type , and Category values for the Cluster Event.
   

5. You can also add key-value pairs to the Cluster Event's list or parameters. Set the key in the Argument field, set the value in the Value field, then click the Add (+) button.
   

   If you need to modify a parameter after you create it, select it in the list on the right and click - to delete it. Then recreate a new parameter with the settings you need.

6. Click Apply to save your new Cluster Event.

7. Back in the Cluster events tab, select your Cluster Event in the list and click Send .
   

   You can also click Modify to reopen the selected Cluster Event to edit its values.

Responding to Cluster Events in Blueprints

Once you've set up one of the methods described above to emit Cluster Events into your nDisplay network, you'll want to set up your Blueprint (or C++) gameplay logic to detect those Cluster Events and respond to them in some way. To do this, you need to create and register a listener: a class that implements the DisplayClusterClusterEventListener interface. You register the listener by calling the Add Cluster Event Listener function from the nDisplay API, then use the Event On Cluster Event node to detect Cluster Events and respond to them.

For example, to create a new Blueprint class and register it as a listener:

1. In the Content Browser , right-click and choose Create Basic Asset > Blueprint Class .
   

2. Choose Actor as the parent class.
   

3. Type a name for your new listener class in the Content Browser .
   

4. Drag your class into the Level Viewport and drop it into your Level.
   

5. Double-click your new Blueprint class to edit it.

6. In the Toolbar, click Class Settings .
   

7. In the Details panel, find the Interfaces > Implemented Interfaces setting and click Add .
   

8. Find and select the DisplayClusterClusterEventListener interface in the list.
   

9. Click Compile in the Toolbar to compile your class.

10. On the Event Graph tab, set up the following graph to register your listener:

    
    Click for full image.

    To set this up:
    

    1. Drag right from the output of the Begin Play Event node and choose N Display > DisplayCluster Module API .

    2. Drag right from the Out API port of that node and choose Display Cluster > Cluster > Add cluster event listener (Interface Call) .

    3. Finally, drag left from the Listener port of the Add cluster event listener node, and choose Variables > Get a reference to self .

11. It's a good idea to also destroy each listener you create when you know you won't need it anymore. For example, you can do it when your Blueprint Actor is destroyed:

    
    Click for full image.

    To set this up:
    

    1. Right-click in the Event Graph and choose the Add Event > Event Destroyed node.

    2. Drag right from the output of the Event Destroyed node and choose N Display > DisplayCluster Module API .

    3. Drag right from the Out API port of that node and choose Display Cluster > Cluster > Remove cluster event listener (Interface Call) .

    4. Finally, drag left from the Listener port of the Remove cluster event listener node, and choose Variables > Get a reference to self .

12. In another area of the Event Graph , add the Add Event > N Display > Event On Cluster Event Json node. Every time a JSON Cluster Event happens in your nDisplay cluster, this event will trigger.
    You will probably want to read the settings and parameters assigned to this event, so that you can use them to determine what action your Blueprint needs to take. To do this, drag right from the Event port of the Event On Cluster Event Json node, and choose Break DisplayClusterClusterEventJson .
    For example, this graph simply prints out the Name value of each JSON Cluster Event to the screen:

    
    Click for full image.

13. Compile and Save your Blueprint class.

The next time any JSON Cluster Event is emitted in the cluster, from any source, the name of that JSON Cluster Event gets printed to the screen.