MQTT Utilities for Unreal Engine 5.6

Unreal Engine MQTT Blueprint plugin based on the original Nineva Studios MqttUtilities-UnrealEngine project.

This repository is a community-maintained derivative work. It is not affiliated with, sponsored by, or endorsed by Nineva Studios, Eclipse Mosquitto, Eclipse Paho, Unreal Engine, or Epic Games.

What Changed

This fork updates the original plugin for Unreal Engine 5.6 and contains additional runtime and Blueprint fixes, including:

• UE 5.6-compatible plugin metadata and UnrealBuildTool rules.
• Win64 and Linux MQTT client updates.
• Safer MQTT worker-thread and UObject lifetime handling on Win64/Linux.
• Game-thread dispatch for MQTT callbacks.
• Connection-generation filtering to discard callbacks from an old connection.
• Worker-thread shutdown and queue cleanup improvements.
• Unexpected connection-loss Blueprint callback.
• Error callbacks for connection-loop failures and broker connection failures.
• Multiple message listeners on one MQTT Client.
• Add On Message Handler, Remove On Message Handler, and Clear On Message Handlers nodes.
• Allocation and task-memory safety fixes.
• Android Gradle dependency syntax updated from compile to implementation in the retained Android integration.

Supported Targets

The current maintained and tested target is:

• Windows x64 / Win64
  • Unreal Engine 5.6
  • Bundled Eclipse Mosquitto runtime

Linux source changes are retained, but this fork does not claim a completed UE 5.6 Linux build or runtime validation.

Android, iOS, and Mac source and third-party artifacts are retained from the upstream distribution for reference and legacy packaging. They are not covered by the current Win64 validation and should be reviewed and rebuilt with their respective toolchains before distribution.

Installation

1. Download or clone this repository.

2. Copy the plugin directory into your project:

   YourProject/
   Plugins/MqttUtilities/
   

3. Enable the plugin in Unreal Editor.

4. Regenerate project files if your project uses generated IDE files.

5. Build the project with Unreal Engine 5.6.

For Win64, keep these runtime files in the plugin's Binaries/Win64 directory:

Binaries/Win64/UnrealEditor-MqttUtilities.dll
Binaries/Win64/mosquitto.dll
Binaries/Win64/mosquittopp.dll

Do not mix the module DLL from one build with source files or third-party binaries from another build.

Basic Blueprint Usage

The normal flow is:

1. Call Create Mqtt Client.
2. Store the returned MQTT Client reference in a long-lived Blueprint object such as GameInstance, a persistent manager actor, or a subsystem.
3. Set the connect, message, subscribe, error, and connection-loss handlers.
4. Call Connect.
5. Call Subscribe after the connection succeeds.
6. Call Publish when needed.
7. Call Disconnect before deliberately shutting down the client.

Multiple Message Listeners

The same MQTT Client can be shared by multiple Blueprints. Each Blueprint may call:

Set On Message Handler

The current Win64/Linux implementation adds the listener instead of replacing existing listeners. Therefore multiple Blueprints can receive the same message.

Use these nodes when ownership changes:

• Add On Message Handler: add a listener explicitly.
• Remove On Message Handler: remove a previously registered listener.
• Clear On Message Handlers: remove all message listeners.

Keep the MQTT Client reference alive. A temporary or unreferenced object may be garbage-collected while its native worker is active.

Unexpected Connection Loss

Set On Connection Lost Handler is intended for an established MQTT session that later disconnects unexpectedly, for example because of a network or broker failure.

It is separate from the normal Disconnect callback:

• Disconnect callback: deliberate/clean disconnect.
• Connection Lost callback: an established session was lost unexpectedly.
• Error callback: connection, broker, transport, or operation error details.

The client may continue its existing reconnect behavior after an unexpected loss. Applications should decide whether to resubscribe after a successful reconnect, depending on broker/session configuration.

Build Verification

The Win64 plugin was built with Unreal Engine 5.6 using RunUAT BuildPlugin.

Verified targets:

• UnrealHeaderTool
• UnrealEditor Win64 Development
• UnrealGame Win64 Development

No claim is made here that Android, iOS, Mac, or Linux has been validated by this fork.

Project Status and Limitations

This is a source-level maintenance fork, not a claim that every platform artifact in the original distribution is current.

Known limitations include:

• Third-party mobile and Apple binaries are legacy artifacts and require independent architecture, signing, SDK, and license review.
• The bundled Win64/Mosquitto artifacts are old compared with current Mosquitto releases.
• Binary MQTT payload publishing should be reviewed if messages contain embedded NUL bytes or are not UTF-8 text.
• Use unique MQTT Client IDs for independent MQTT connections. A broker may disconnect an older session when a new session uses the same Client ID.
• Do not run MQTT Blueprint handler registration or mutation from worker threads; Blueprint calls belong on the GameThread.
• This project does not include an automated MQTT broker integration test.

License and Attribution

Original plugin and this fork

The original project includes LICENSE.txt under the Eclipse Public License 1.0 (EPL-1.0). Unless a source file or component states otherwise, original plugin code and modifications in this repository are distributed under the terms of EPL-1.0.

This fork must preserve:

• The original LICENSE.txt.
• Existing copyright and attribution notices.
• A clear description of modifications and the date/version of the fork.
• Information explaining where the modified source code can be obtained when distributing object code.

The fork's modifications are attributed to the fork maintainer in the repository history and release notes. Replace this statement with the maintainer's actual name or organization before publishing.

Eclipse Mosquitto

The bundled Mosquitto headers and binaries are third-party components. Their notices identify Eclipse Public License and Eclipse Distribution License terms; some Linux headers also identify EPL-2.0 or BSD-3-Clause alternatives.

Mosquitto copyright and license notices must remain available with any redistribution. Do not relicense Mosquitto binaries as if they were original project code. See the notices in Source/ThirdParty and the upstream Eclipse Mosquitto project.

Eclipse Paho Android dependencies

The Android integration obtains these artifacts from Maven:

• org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.1.0
• org.eclipse.paho:org.eclipse.paho.android.service:1.1.1

Their licenses and notices must be reviewed and included according to the artifacts actually redistributed in a release. Do not represent these dependencies as authored by this fork.

iOS frameworks

The repository contains legacy embedded archives for MQTTClient and SocketRocket. Their original license and attribution files were not found as standalone files in the repository root or archive listing during this audit. Before distributing an iOS release, identify the exact upstream versions and add the corresponding license and notice files, or remove/rebuild those artifacts from the release.

Unreal Engine and Epic Games

Unreal Engine is proprietary software distributed by Epic Games under Epic's applicable terms. This repository does not redistribute Unreal Engine itself. Unreal Engine and Epic Games trademarks belong to their respective owners.

Third-Party Notices Before Release

Before publishing a binary GitHub Release, verify that the release archive contains or links to:

• This repository's LICENSE.txt.
• Mosquitto EPL/EDL/BSD notices applicable to each bundled version.
• Paho notices for Android artifacts used by the release.
• Exact MQTTClient and SocketRocket notices for any iOS artifacts distributed.
• A THIRD_PARTY_NOTICES.md file listing versions, sources, licenses, and hashes for bundled binaries.

The absence of a notice in this repository is not permission to omit a third-party license. This README is a project documentation and attribution guide, not legal advice.

Original Project

Original upstream project:

• Repository: https://github.com/NinevaStudios/MqttUtilities-UnrealEngine
• Original documentation: https://github.com/NinevaStudios/MqttUtilities-UnrealEngine/wiki
• Original author: Nineva Studios

Please keep upstream attribution and do not use the original Marketplace URL or branding in a way that implies an official Marketplace release or endorsement of this fork.

Contributing

Issues and pull requests are welcome. Please include:

• Unreal Engine version.
• Target platform and architecture.
• Build configuration.
• Reproduction steps.
• Relevant Unreal log and crash information.
• Whether the issue occurs with a unique MQTT Client ID.

Do not upload private broker credentials, certificates, or production MQTT payloads.

Disclaimer

This software is provided on an "AS IS" basis under the applicable upstream licenses. Use it at your own risk and review all third-party licensing obligations before distributing source or binary releases.