Using Cluster Events

Describes how to send events to your nDisplay cluster, and how to respond to those events in Blueprints.

Windows
MacOS
Linux

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 master 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 master 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 Structure

Each nDisplay Cluster Event can contain several properties:

Setting

Type

Name

string

Type

string

Category

string

Parameters

An optional map of key-value pairs, where the keys and values are both strings.

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 Cluster Event in Blueprint, you'll use the Make DisplayClusterClusterEvent and Break DisplayClusterClusterEvent nodes to construct and deconstruct Cluster Events. For example:

A Cluster Event in Blueprint

In C++, or when emitting Cluster Events from your own applications, you'll use JSON to express the same structure. For example, the equivalent JSON for the Cluster Event above is:

{"Name":"activate","Type":"command","Category":"particles","Parameters":{"rate":"200","speed":"3"}}

Emitting Cluster Events from Blueprints

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

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

  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 Emits cluster event node. If you check this box, only the master node will emit this Cluster Event. If any other non-master cluster node evaluates the same Blueprint graph, those nodes will not emit the event.
    Master Only

  3. Drag left from the Event port on the Emits cluster event node, and choose Make DisplayClusterClusterEvent.
    Make DisplayClusterClusterEvent

  4. Use the settings in the Make DisplayClusterClusterEvent 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.
    Creating and emitting a Cluster Event

  5. Compile and Save your Blueprint.

The next time you repackage your Project and relaunch your nDisplay cluster, this Blueprint code will fire the 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 master 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.

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

  • The first two 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 a JSON object.

For example, to emit a 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.

  2. Get the length of the JSON string — in this case, 62 characters — and send that length to the nDisplay master node.

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

If the master node is able to receive and process your message, it sends a response back to your application that follows the same convention:

  • The first two bytes tell you the length in bytes of the rest of the response message.

  • The rest of the message is a JSON object that typically contains one field: Error. The value of this field is an error code that indicates whether your message was handled correctly:

    Code

    Meaning

    0

    No error occurred. The message was processed successfully.

    2

    The Cluster Event you sent is missing one or more mandatory fields. Make sure it has fields for the Name, Category, and Type, even if their values are empty.

    255

    An unrecognized error occurred.

By default, the master node listens for Cluster Events on port 14003. You can change this default in your nDisplay configuration file. See Changing nDisplay Communication Ports.

To respond to these Cluster Events in your Project's Blueprint code, see Responding to Cluster Events in Blueprints.

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 master 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.
    Cluster events tab

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

  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 + button.
    Parameters in the Cluster event editor

    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.
    Send the Cluster Event

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

  8. Watch the log output panel at the bottom of the nDisplayLauncher to see the response from the master node.
    clusterevent-emit-launcher-response.png

To respond to these Cluster Events in your Project's Blueprint code, see Responding to Cluster Events in Blueprint.

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.
    Create Blueprint Class

  2. Choose Actor as the parent class.
    Actor

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

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

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

  6. In the Toolbar, click Class Settings.
    Class Settings

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

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

  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:

    To set this up:

    1. Drag right from the output of the Begin Play Event node and choose N Display > Get 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:

    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 > Get 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 node. Every time a 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 node, and choose Break DisplayClusterClusterEvent.
    For example, this graph simply prints out the Name value of each Cluster Event to the screen:

  13. Compile and Save your Blueprint class.

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

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback