README.md

Unreal® Engine Plugin: Integration Tool — Readme

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

Description

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 event broker. Other use cases could be data streaming or instant messaging from or into a game.

---

Table of Contents

• 1. Installation
• 2. Usage
  • 2.1. Concept
  • 2.2. Actors
    • 2.2.1. PUB-Socket Actor
    • 2.2.2. SUB-Socket Actor
  • 2.3. Actor-Components
    • 2.3.1. Publisher Actor-Component
    • 2.3.2. Subscriber Actor-Component
• 3. Demo
• 4. Unsupported
• A. Attribution
• B. References
• C. Citation

1. Installation

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

2. Usage

2.1. Concept

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).

2.2. Actors

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

2.2.1. PUB-Socket Actor

A PUB-Socket Actor has:

• Variables, Group 'Endpoint':
  • Transport Type (Select): tcp (default), inproc
  • Host (String), default 127.0.0.1
  • Port (Integer), default 5555

Fig. 2.4.: Screenshot of PUB-Socket Actor instance 'Details' panel with variables from Endpoint

• Functions:
  • Open, IsOpen (returns a Boolean)
  • Bind via NNG listen, IsBound (returns a Boolean)
  • Connect via NNG dial, IsConnected (returns a Boolean)
  • IsLinked (returns a Boolean)
  • Close
• Events (Delegates):
  • OnOpen, OnOpenError (returns an error message as String)
  • OnBound, OnBindError (returns an error message as String)
  • OnConnected, OnConnectError (returns an error message as String)
  • OnLinked, OnLinkError (returns an error message as String)
  • OnClosed, OnCloseError (returns an error message as String)

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

2.2.2. SUB-Socket Actor

A SUB-Socket Actor has:

• Variables, Group 'Endpoint':
  • Transport Type (Select): tcp (default), inproc
  • Host (String), default 127.0.0.1
  • Port (Integer), default 5555

Fig. 2.6.: Screenshot of SUB-Socket Actor instance 'Details' panel with variables from Endpoint

• Functions:
  • Open, IsOpen (returns a Boolean)
  • Bind via NNG listen, IsBound (returns a Boolean)
  • Connect via NNG dial, IsConnected (returns a Boolean)
  • IsLinked (returns a Boolean)
  • Close
• Events (Delegates):
  • OnOpen, OnOpenError (returns an error message as String)
  • OnBound, OnBindError (returns an error message as String)
  • OnConnected, OnConnectError (returns an error message as String)
  • OnLinked, OnLinkError (returns an error message as String)
  • OnClosed, OnCloseError (returns an error message as String)

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

2.3. Actor-Components

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'

2.3.1. Publisher Actor-Component

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
• Functions:
  • Publish with in-parameter 'Message' as String
• Events (Delegates):
  • OnPublished

Fig. 2.9.: Screenshot of an Event Graph with Publisher Actor-Component function and event nodes

2.3.2. Subscriber Actor-Component

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
• Functions:
  • Subscribe
  • IsSubscribed (returns a Boolean)
  • Unsubscribe
• Events (Delegates):
  • OnSubscribed
  • OnUnsubscribed
  • OnReceived (returns the received 'Message' as String)

Fig. 2.10.: Screenshot of an Event Graph with Subscriber Actor-Component function and event nodes

3. Demo

In the content browser enable the listing of plugin folders by checking Settings > Show Engine Content and Settings > Show Plugin 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 or nodes repectively. 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 (NNG: listen)
• A SUB-Socket Actor instance connects address tcp://127.0.0.1:5555 (NNG: dial)
• 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 TCP traffic over localhost port 5555.

Fig. 3.2.: Demo PubSub-Scheme

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 (Time: 0.01).

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.
[...]

4. Unsupported

Transport Protocol:

• ipc:// – Inter Process Communication, aka UNIX domain socket
• ws:// and wss:// – WebSockets over TCP
• tls:// – Transport Layer Security
• zt:// – Communication over a ZeroTier™ network
• mqtt:// – MQ Telemetry Transport (NNG™ does not provide with the MQTT transport protocol yet, neither does the plugin)

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

A. Attribution

• 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)

B. References

• Unreal® Engine Plugin: Integration Tool by Roland Bruggmann aka brugr9 on Unreal® Marketplace: https://www.unrealengine.com/marketplace/en-US/product/integration-tool

C. Citation

To acknowledge "Unreal® Engine Plugin: Integration Tool" software, please cite

Bruggmann, R. (2022, April). Unreal® Engine Plugin: Integration Tool, Version 1.0.1 for UE 5.0. Unreal Engine Marketplace. computer software, Epic Games. Retrieved from URL: https://www.unrealengine.com/marketplace/en-US/product/integration-tool

@software{IntegrationTool,
  title={Unreal Engine Plugin: Integration Tool},
  url={https://www.unrealengine.com/marketplace/en-US/product/integration-tool},
  journal={Unreal Engine Marketplace},
  publisher={Epic Games},
  author={Bruggmann, Roland},
  version={v1.0.1, UE 5.0},
  year={2022},
  month={4}
}

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

@misc{Bruggmann2022,
  author = {Bruggmann, Roland},
  title = {Unreal Engine Plugin: Integration Tool — Documentation, Readme},
  version = {v1.0.1},
  url = {https://github.com/brugr9/UEPluginIntegrationTool},
  year = {2022},
  month = {5}
}

---

"Unreal® Engine Plugin: Integration Tool – Documentation" © 2022 by Roland Bruggmann is licensed under Creative Commons Attribution-ShareAlike 4.0 International