Core Components

Queue

At the very core of SmoothMQTT there is a queue taking care of all configured subscriptions. All messages that arrive as result of a subscription are collected here for execution at the next possible time. With maxActionsPerFrame you can configure how many events shall be processed per frame. Lower number means higher framerate but potential delay of reaction to MQTT messages. Higher number means all messages are dealt with right away, but it might impact framerate.

Technical Background

The queue is necessary, because MQTT subscriptions run asynchronously, but changes to the Unity Scene or Gameobjects have to be made on the main thread.

Advanced Users

A way of improving performance is to keep the subscribe action small in scope or ideally only use it to start a Coroutine.

Settings

No matter whether you run the broker externally or right from Unity, the Settings component is where you configure the host (URL or IP address), port and if available username and password for login at the broker. The Settings component uses a Singleton pattern and thus is only allowed once in your scene. If you are using the internal broker (i.e. MqttManagerWithBroker prefab) you can also select whether the broker requires credentials.

Since in some projects it can be beneficial to not start the broker or subscribers right away when the scene starts, there is now a setting to Connect On Start. Similar Auto Reconnect deals with disconnects (for example due to flaky network connection)

For SSL options check Security certificates -> Settings

Publisher

Publisher component allows you to publish MQTT messages for any topic with any payload. Thus it is not necessary to have more than one in the scene. The MqttManager Prefab has a Publisher component attached. However, if you need to have two or more Publisher components with different client IDs registered with your broker, you can just add them to your scene and name them accordingly.

info

Client IDs may not be empty and may not be used twice on different components

Broker

This component provides you with an MQTT broker from within Unity. There is nothing to configure really, as it takes the same settings as all clients in your app. If this component is present, Unity will take care of receiving and distributing MQTT messages without the need of additional software. The broker uses a Singleton pattern and thus is only allowed once in your scene. As of now, if you use your Unity game as MQTT broker, there is no way to setup user-specific permission sets. This might be added in the future and has low priority for now.

caution

From Unity 2019 onwards the Broker does not fully work from within the editor (something to do with Networking rules). It will allow any MQTT activity on localhost through, but no connections from other devices on your network. It DOES, however, work just fine in builds. So for development the currently suggested workaround is to use an external broker like mosquitto during development and activate broker component just before deployment.

Credentials

If you run a broker directly from Unity, you might want to be able to restrict access to users with a valid password. As of version 1.0.6 you can create credential assets by using the Create menu in your Project view (see screenshot). In the asset you can choose a username and password (case-sensitive). Finally you need to add all valid users to the credentials list of the broker component in your scene. Check example scene 007_May_I_See_Your_Credentials.

caution

As of the current version this just restricts access by suppressing anonymous connections, but it is not secure by any means. Passwords are sent in Plaintext (if SSL encryption is not used) and users cannot be restricted to read/write only certain topics (We have yet to find a good way to integrate this without violating our claim: No Code! Just Connect!, but we're working on it.)

Subscriber Component

Listening to MQTT messages is as easy as giving any Gameobject a Subscriber component. It can be configured with a specific topic to listen on (or use “#” to listen for any message). Any Method accepting a string (the payload) as parameter can subsequently be added to the Action list below. Think for example SetText(string) method of TMP_Text fields or your own methods.

info

Client IDs may not be empty and may not be used twice on different components

For other data types see Subscriber Converter.