This document is part of Unreal® Engine Plugin: Integration Tool – Documentation
- Author: Copyright 2022 Roland Bruggmann aka brugr9
- Profile on UE Marketplace: https://www.unrealengine.com/marketplace/profile/brugr9
- Profile on Epic Developer Community: https://dev.epicgames.com/community/profile/PQBq/brugr9
Adds Blueprint Support for Asynchronous Messaging using NNG™ next generation of nanomsg™ Software
This plugin enables asynchronous, broker-less messaging using NNG™ next generation of nanomsg™ software from the Blueprint visual scripting system.
The delivered assets provide transporting messages over a network and can be used in games to enable direct machine-to-machine communication, internet of things integration, or interaction with an enterprise service bus or an event broker. Other use cases could be data streaming or instant messaging from or into a game.
Suits well for the use with, e.g., EMQ's NanoMQ™ – "MQTT Messaging Bus for Edge Computing".
Startup the Unreal® editor, and from the menu 'Edit > Plugins' access the 'Plugin Editor'. In the 'Plugin Editor', under category 'Messaging' find and enable the plugin.
Fig. 1.: Screenshot of Plugin Editor with Plugin 'Integration Tool'
Finally restart the editor. When the plugin has been loaded successfully, the output log displays a message with the custom log category LogNextGenMsg informing about the library version used:
LogNextGenMsg: Using NNG version 1.5.2
Publisher and subscriber as actor components are responsible for publishing messages and subscribing to topics and receiving messages. These components contain as a variable a topic to publish or subscribe to. As another variable they contain a reference to a PUB- or SUB-socket instance they work with.
- One or multiple Publisher Actor-Components can access the same PUB-Socket Actor to send messages to the same endpoint (
Publisher : PUB-Socket = n : 1
). - One or multiple Subscriber Actor-Components can access the same SUB-Socket Actor to subscribe to a topic and to receive messages from the same endpoint (
Subscriber : SUB-Socket = n : 1
).
The plugin provides with PUB-Sockets and SUB-Sockets which are Actors and may be found in the 'Place Actors' panel, category 'All Classes' and can be added to a map by drag'n'drop. The added actors then are listed in the world outliner. Please consider that in the viewport no sprites are shown for these sockets.
Fig. 2.3.: Screenshot of Editor Tab 'Place Actors' listing Socket Actors
A PUB-Socket Actor has:
- Variables, Group 'Endpoint':
- Transport Type (
Select
):tcp
(default),inproc
- Host (
String
), default127.0.0.1
- Port (
Integer
), default5555
- Transport Type (
Fig. 2.4.: Screenshot of PUB-Socket Actor instance 'Details' panel with variables from Endpoint
- Functions:
Open
,IsOpen
(returns aBoolean
)Bind
,IsBound
(returns aBoolean
)Connect
,IsConnected
(returns aBoolean
)IsLinked
(returns aBoolean
)Close
- Events (Delegates):
OnOpen
,OnOpenError
(returns an error message asString
)OnBound
,OnBindError
(returns an error message asString
)OnConnected
,OnConnectError
(returns an error message asString
)OnLinked
,OnLinkError
(returns an error message asString
)OnClosed
,OnCloseError
(returns an error message asString
)
Upon successful Open
or Close
, the OnOpen
or OnClosed
event is triggered. Upon successful Bind
or Connect
, the OnBound
or OnConnected
event is triggered, as well as event OnLinked
in both cases. If one the functions IsBound
or IsConnected
returns true
, also the function IsLinked
returns true
.
Fig. 2.5.: Screenshot of a Level Blueprint with function and event nodes of a PUB-Socket Actor
A SUB-Socket Actor has:
- Variables, Group 'Endpoint':
- Transport Type (
Select
):tcp
(default),inproc
- Host (
String
), default127.0.0.1
- Port (
Integer
), default5555
- Transport Type (
Fig. 2.6.: Screenshot of SUB-Socket Actor instance 'Details' panel with variables from Endpoint
- Functions:
Open
,IsOpen
(returns aBoolean
)Bind
,IsBound
(returns aBoolean
)Connect
,IsConnected
(returns aBoolean
)IsLinked
(returns aBoolean
)Close
- Events (Delegates):
OnOpen
,OnOpenError
(returns an error message asString
)OnBound
,OnBindError
(returns an error message asString
)OnConnected
,OnConnectError
(returns an error message asString
)OnLinked
,OnLinkError
(returns an error message asString
)OnClosed
,OnCloseError
(returns an error message asString
)
Upon successful Open
or Close
, the OnOpen
or OnClosed
event is triggered. Upon successful Bind
or Connect
, the OnBound
or OnConnected
event is triggered, as well as event OnLinked
in both cases. If one the functions IsBound
or IsConnected
returns true
, also the function IsLinked
returns true
. In addition a SUB-Socket Actor has a Blueprint-callable function Receive
to trigger a message pickup.
Fig. 2.7.: Screenshot of a Level Blueprint with function and event nodes of a SUB-Socket Actor
A Publisher Actor-Component or a Subscriber Actor-Component may be added to a Blueprints 'Components' tab by pressing the 'Add Components' button. The components are listed with category 'Messaging'.
Fig. 2.8.: Screenshot of Actor-Components listed in tab 'Components', category 'Messaging'
A Publisher Actor-Component has:
- Variables:
- Topic: The topic
String
with which is published - PUB-Socket: A PUB-Socket Actor instance which is used for publishing messages
- Topic: The topic
- Functions:
Publish
with in-parameter 'Message' asString
- Events (Delegates):
OnPublished
Fig. 2.9.: Screenshot of an Event Graph with Publisher Actor-Component function and event nodes
A Subscriber Actor-Component has:
- Variables:
- Topic: The topic
String
to subscribe to - Starts With (Check Box): If checked test whether received topic starts with the given topic – exact match otherwise (case sensitive string comparison in both cases)
- SUB-Socket: A SUB-Socket Actor instance which is used for receiving messages
- Topic: The topic
- Functions:
Subscribe
IsSubscribed
(returns aBoolean
)Unsubscribe
- Events (Delegates):
OnSubscribed
OnUnsubscribed
OnReceived
(returns the received 'Message' asString
)
Fig. 2.10.: Screenshot of an Event Graph with Subscriber Actor-Component function and event nodes
In the content browser enable the listing of plugin folders by checking Settings > Show Engine Content
. Find and navigate to folder 'Integration Tool Content'. The folder 'Demo' provides with three Blueprints BP_CubeCyan, BP_CubeYellow and BP_CubeGreen as well as with the level named Map_PubSub_Demo.
Fig. 3.1.: Screenshot of Content Browser with Integration Tool Content
Usually, the PUB-SUB pattern is used to connect several endpoints of distributed systems whose applications run on different machines. For the demo, we have endpoints in the same application for simplicity's sake – a PUB-Socket and a SUB-Socket are here in the level named Map_PubSub_Demo. The demo implements a PubSub-scheme as follows:
- A PUB-Socket Actor instance binds address
tcp://127.0.0.1:5555
- A SUB-Socket Actor instance connects address
tcp://127.0.0.1:5555
- Two Publisher Actor-Components (each in a cyan and a yellow cube) publish via the PUB-Socket Actor instance
- Two Subscriber Actor-Components (both in a green cube) subscribe via the SUB-Socket Actor instance
Please assure to have the corresponding firewall configured to allow traffic over localhost port 5555.
The cyan and the yellow cube each use a Publisher Actor-Component and loop publishing a message 'Hello from Cyan' with topic 'Cyan' or 'Hello from Yellow' with topic 'Yellow' respectively.
Fig. 3.3.: Screenshot of Blueprint BP_CubeCyan Event Graph
Fig. 3.4.: Screenshot of Blueprint BP_CubeYellow Event Graph
A third, green cube uses two Subscriber Actor-Components to subscribe to topics 'C' and 'Y'–both check-boxes 'Starts With' are checked–and appends the received messages to its TextRender
Scene-Component and prints the same to the Output Log.
Fig. 3.5.: Screenshot of Blueprint BP_CubeGreen Event Graph
The Map_PubSub_Demo has an instance each of PUB-Socket Actor and SUB-Socket Actor. The sockets link an endpoint with TCP on host 127.0.0.1 and port 5555 (default values).
Fig. 3.6.: Screenshot of Map_PubSub_Demo
In the Level Blueprint, with Event BeginPlay
the PUB-Socket Actor's function Open
is called. With event OnOpen (PUB-Socket)
the PUB-Socket Actor's function Bind
is called.
With event OnLinked (PUB-Socket)
the SUB-Socket Actor's function Open
is called. With event OnOpen (SUB-Socket)
the SUB-Socket Actor's function Connect
is called. With event OnLinked (SUB-Socket)
a timer based event starts a looped call of the SUB-Socket Actor's function Receive
every other centisecond.
With Event EndPlay
the Receive-Timer is cleard and invalidated, and the SUB-Socket Actor's as well as the PUB-Socket Actor's function Close
is called.
Fig. 3.7.: Screenshot of Map_PubSub_Demo Level-Blueprint
The demo map also has instances each of BP_CubeCyan, BP_CubeYellow, and BP_CubeGreen. In these cube instances, the Publisher and Subscriber Actor-Components were each assigned the PUB-Socket Actor instance or the SUB-Socket Actor instance, respectively.
Fig. 3.8.: Screenshot of BP_CubeCyan instances 'Details' panel, Publisher Actor-Component with assigned reference to a PUB-Socket Actor instance
Fig. 3.9.: Screenshot of BP_CubeYellow instances 'Details' panel, Publisher Actor-Component with assigned reference to a PUB-Socket Actor instance
Fig. 3.10.: Screenshot of BP_CubeGreen instance 'Details' panel, Subscriber Actor-Component 'Subscriber_C' with assigned reference to a SUB-Socket Actor instance
Fig. 3.11.: Screenshot of BP_CubeGreen instance 'Details' panel, Subscriber Actor-Component 'Subscriber_Y' with assigned reference to a SUB-Socket Actor instance
When the Map_PubSub_Demo level is open, click the Play button in the level editor to start Play-in-Editor PIE.
Fig. 3.12.: Animation Screenshot of Demo Map PIE
The plugin writes to the output log with the custom log category LogNextGenMsg.
Listing 3.1.: Output Log of Map_PubSub_Demo starting PIE
[...]
PIE: New page: PIE session: Map_PubSub_Demo ([...])
[...]
LogNextGenMsg: PubSocketActor1_2: Open socket ...
LogNextGenMsg: NngSocketObject_8: Socket successfully opened.
LogNextGenMsg: PubSocketActor1_2: Open socket done.
LogNextGenMsg: PubSocketActor1_2: Bind to tcp://127.0.0.1:5555 ...
LogNextGenMsg: NngSocketObject_8: Successfully listening to tcp://127.0.0.1:5555
LogNextGenMsg: PubSocketActor1_2: Bind done.
LogNextGenMsg: SubSocketActor1_2: Open socket ...
LogNextGenMsg: NngSocketObject_9: Socket successfully opened.
LogNextGenMsg: SubSocketActor1_2: Open socket done.
LogNextGenMsg: SubSocketActor1_2: Connect tcp://127.0.0.1:5555 ...
LogNextGenMsg: NngSocketObject_9: Successfully dialed tcp://127.0.0.1:5555
LogNextGenMsg: SubSocketActor1_2: Connect done.
LogNextGenMsg: BP_CubeGreen_2.Subscriber_C Subscribe topic C ...
LogNextGenMsg: SubSocketActor1_2 Subscribe topic 'C' ...
LogNextGenMsg: NngSocketObject_9: Topic successfully subscribed.
LogNextGenMsg: BP_CubeGreen_2.Subscriber_Y Subscribe topic Y ...
LogNextGenMsg: SubSocketActor1_2 Subscribe topic 'Y' ...
LogNextGenMsg: NngSocketObject_9: Topic successfully subscribed.
PIE: Server logged in
PIE: Play in editor total start time 0.182 seconds.
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Yellow #0
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Cyan #0
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Yellow #1
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Cyan #1
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Cyan #2
LogBlueprintUserMessages: [BP_CubeGreen_2] Hello from Yellow #2
[...]
Listing 3.2.: Output Log of Map_PubSub_Demo stopping PIE
[...]
LogWorld: BeginTearingDown for /IntegrationTool/Demo/Maps/UEDPIE_0_Map_PubSub_Demo
LogNextGenMsg: SubSocketActor1_2: Close socket ...
LogNextGenMsg: NngSocketObject_9: Topic 'C' successfully unsubscribed.
LogNextGenMsg: NngSocketObject_9: Topic 'Y' successfully unsubscribed.
LogNextGenMsg: NngSocketObject_9: Socket successfully closed.
LogNextGenMsg: SubSocketActor1_2: Close socket done.
LogNextGenMsg: PubSocketActor1_2: Close socket ...
LogNextGenMsg: NngSocketObject_8: Socket successfully closed.
LogNextGenMsg: PubSocketActor1_2: Close socket done.
[...]
Transport Protocol:
- ipc:// (Inter Process Communication, aka UNIX domain socket)
- ws:// and wss:// (WebSockets over TCP)
Communication Pattern:
- PAIR - simple one-to-one communication
- BUS - simple many-to-many communication
- REQREP - allows to build clusters of stateless services to process user requests
- PIPELINE - aggregates messages from multiple sources and load balances them among many destinations
- SURVEY - allows to query state of multiple applications in a single go
- The word mark Unreal® and its logo are Epic Games, Inc. trademarks or registered trademarks in the US and elsewhere (cp. Branding Guidelines and Trademark Usage, URL: https://www.unrealengine.com/en-US/branding)
- The word marks nanomsg™ and NNG™ and its logos are trademarks of Garrett D'Amore, used with permission (cp. Trademark Policy, URL: https://nanomsg.org/trademarks.html)
- The word marks EMQ™ and NanoMQ™ and its logos are trademarks of EMQ Technologies Co., Ltd.
- Unreal® Engine Plugin: Integration Tool by Roland Bruggmann aka brugr9 on Unreal® Marketplace: https://www.unrealengine.com/marketplace/en-US/product/integration-tool
To acknowledge "Unreal® Engine Plugin: Integration Tool" software, please cite
Bruggmann, Roland (2022). Unreal® Engine Plugin: Integration Tool, Version [#.#.#], UE [4.## or 5.#]. Unreal® Marketplace. URL: https://www.unrealengine.com/marketplace/en-US/product/integration-tool. Copyright 2022 Roland Bruggmann aka brugr9. All Rights Reserved.
To acknowledge "Unreal® Engine Plugin: Integration Tool — Documentation" (be it , e.g., the Readme or the Changelog), please cite
Bruggmann, Roland (2022). Unreal® Engine Plugin: Integration Tool — Documentation, [Readme, Changelog]. GitHub; accessed [Year Month Day]. URL: https://github.com/brugr9/UEPluginIntegrationTool. Licensed under Creative Commons Attribution-ShareAlike 4.0 International
"Unreal® Engine Plugin: Integration Tool – Documentation" © 2022 by Roland Bruggmann is licensed under Creative Commons Attribution-ShareAlike 4.0 International