Quick Start

The fastest way to get up and running with AMQP in your Unity project is to just import the asset package. You can find the asset package in this project here: /unity/CymaticLabsUnityAmqp.unitypackage.

Note: If you don't want to download the whole project and just want to work with the asset package you can download it from the releases section of the project.

Start a new project or open a project you'd like to import the library into. Once you've done that import CymaticLabsUnityAmqp.unitypacakge into your project:

Once the asset package has been imported, locate and load the AmqpDemo scene:

Before you can use the library you will need to do an initial setup of the AMQP configuration. To do this, open the AMQP configuration editor window:

The AMQP configuration editor window is where you will configure the AMQP connections that your Unity project will use. Opening the editor for the first time will create a text asset configuration file that will be used by the project. By default it contains a single connection which is configured for the default install of RabbitMQ server running on localhost which is useful for local development and testing.

Note: The this library pertains to RabbitMQ servers specifically. Your mileage may vary with other AMQP servers/brokers. The Web Port and exchange/queue descovery methods are specifically implemented for RabbitMQ servers and will probably fail with other hosts.

Ensure that you see the AMQP configuration file created by the editor. You can edit this file manually if that's easier for some reason, but it is recommended you use the AMQP configuration editor window instead. Connections must have a unique name so if you edit the file by hand keep that in mind. The configuration file should live in Assets/Resources in your project. The file provides a convenient way to transfer commonly used connections between multiple Unity projects by copying and pasting the file from one project to another.

Assuming you have installed RabbitMQ server locally with the default settings you can now play the demo scene and you should see a single connection in the Conneciton drop down to the left of the demo scene's UI. Press the Connect button to connect to your local RabbitMQ server.

To test a basic "echo" scenario to ensure messages are flowing between Unity and RabbitMQ server subscribe to an exchange in the Subscriptions section of the form. Select "amq.topic" and leave the routing key blank, then hit the Subscribe button.

After you have subscribed, select the same "amq.topic" in the Publish area drop down. Leave the routing key blank, type a text message to send in the Message text input, and then hit the Send button. You should see your message echoed back in the demo scene's console below.

To add or update connections open the AMQP configuration editor window again.

• To update a connection, leave its name the same but update its connection details and then hit the Save button
• To add a new connection, just ensure you give it a unique name in the connection details form, then hit the Save button; it should now appear in the Connection drop downs and in the configuration file
• To delete a connection, select it from the editor's drop down and press the Delete button

In the following example we add new connection to CloudAMQP who offer a free tier of hosted RabbitMQ server:

The following is an explaination of a connection's properties:

• Host - The host address of the AMQP server to connect to
• Amqp Port - The AMQP protocol port number on the host to connect to (5672 is default unencrypted, 5671 is default encrypted)
• Web Port - The web port number on the host to connect to that is used for exchange/queue discovery (for local RabbitMQ server 15672 is default, 80 is default for unencrypted, and 443 is default for encrypted)
• Virtual Host - The RabbitMQ virtual host to connect to
• Username - The client username to use when connecting to the AMQP server
• Password - The client password to use when connecting to the AMQP server
• Reconnect Interval - The number of seconds to wait inbetween connection retries when the connection to the server fails (1 second minimum)

Once you've added an additional connection it should show up in the demo scene's drop down when you play it and you should be able to connect to the new server instead of your localhost:

Note: If you are attempting to connect to a hosted RabbitMQ server like CloudAMQP keep in mind the AMQP Port and Web Port configuration will matter. For example CloudAMQP supports both 5672 (unencrypted) and 5671 (encrypted) for AMQP but only 443 (encrypted) for HTTP/web communication. If you need to use encrypted communication you should read about SSL support.

Finally, find the AmqpClient game object in the demo scene and familiarize yourself with the AmqpClient.cs script. This MonoBehaviour is the main way to interface with an AMQP broker from Unity. It exposes events and methods for connecting, disconnecting, subscribing, and publishing to an AMQP broker. If you only need a single broker connection it has convenient static methods or you can create multiple instances for multiple connections.

You can look for the AmqpClient prefab or just drag the script onto a GameObject in your scene. Here's what it looks like in the inspector:

Properties:

• Connection - The AMQP connection to use that was configured with the AMQP configuration editor
• Connect On Start - When enabled the script will attempt to establish a connection to the AMQP server on Start()
• Relaxed Ssl Validation - When enabled SSL certificate validation from the AMQP server will be relaxed (see details)
• Write To Console - When enabled important AMQP log details will be written to the included AmqpConsole class/prefab (optional)
• Exchange Subscriptions - (optional) A list of exchange subscriptions to apply upon connectiong to the host. You must supply the correct exchange type for your subscription. RabbitMQ client drops the connection when subscribing to an exchange and supplying the wrong exchange type (for example 'fanout' when it should be 'topic). This will cause a loop of connect → subscribe → error → disconnect → reconnect → repeat. There is a safety measure built in to this library that prevents an infinite loop but will essentially disable the connection when this loop is detected. If you are unsure of an exchange's type, either look in RabbitMQ server's administration panel or use the AmqpClient.GetExchanges() or AmqpClient.GetExchangesAsync() to return a list of available exchanges and their declared types.
• Queue Subscriptions - (optional) A list of direct queue subscriptions to apply upon connecting to the host

Events:

• On Connected - Occurs when the client successfully connects to the server
• On Disconnected - Occurs when the client disconnects from the server
• On Blocked - Occurs if the client is blocked by the server
• On Reconnecting - Occurs each reconnection attempt made by the client when a connection becomes unavailable
• On Connection Error - Occurs when the client experiences a connection error
• On Connection Aborted - Occurs when the client has its connection aborted; this means that the client has failed in a loop of reconnection attempts and will no longer be able to connect until AmqpClient.ResetConnection() is called manually
• On Subscribed To Exchange - Occurs when the client successfully subscribes to an exchange
• On Unsubscribed From Exchange - Occurs when the client successfully unsubscribes from an exchange
• On Subscribed To Queue - Occurs when the client successfully subscribes to a queue
• On Unsubscribed From Queue - Occurs when the client successfully unsubscribes from a queue
• On Exchange Subscribe Error - Occurs when there is an error subscribing to an exchange
• On Exchange Unsubscribe Error - Occurs when there is an error unsubscribing from an exchange
• On Queue Subscribe Error - Occurs when there is an error subscribing to a queue
• On Queue Unsubscribe Error - Occurs when there is an error unsubscribing from a queue