Controlling Objects in Unity with AMQP

This tutorial demonstrates how to use the library to control the Position, Rotation, and Scale of an object in the scene using AMQP messages.

Prerequisites

Unity

First you will need to install the Unity3D.Amqp asset package into your project. For more instructions on how to get the asset package and import it into a new project please see the Quick Start tutorial.

RabbitMQ Server

You will need access to a RabbitMQ server for this tutorial. This tutorial assumes a local install of RabbitMQ server, but you could also use a hosted version such as CloudAMQP (who offer a free tier). If you are going to use a hosted service like CloudAMQP then please refer to the README as it explains some of the differences in port configuration and SSL usage that will differ from this tutorial.

Getting Started

Once you have imported the package into your project, locate the example scene ObjectControlDemo:

Configuring AMQP Connections

Before you can use the AMQP library you will need to ensure at least one connection has been written to your project.

From Unity's file menu, select: AMQP → Configuration

This tutorial will assume you have the default install of RabbitMQ server installed on your localhost with the default guest/guest admin user installed.

The first time opening the AMQP Configuration window should create the AmqpConfiguration.json file in the /Assets/Resources folder of your project. To be safe you can press the Save button.

Now in the scene locate the AmqpClient object and script and select it in the Hierarchy window in the scene:

Make sure that in the Connection drop down in Unity's inspector that the AMQP connection that you would like to use is selected.

Configuring the Object for Control

Locate the Cube in the scene and select it. Locate the AmqpObjectController script. This script is an example script that shows how to listen for incoming messages on a particular AMQP exchange and to apply the Position, Rotation, and Scale values received in the messages to the Cube's transform.

Here is a brief explanation of the script's inspector properties:

• Id Filter - An optional ID filter that can be used to make sure this object instance only responds to message with a matching ID. Keep in mind this object will still receive messages, but ignore them if its own ID does not match the ID in the received message. For more efficient message routing strategies consider using routing keys instead.
• Exchange Name - The name of the exchange to subscribe to that messages will be received from; the default is 'amq.topic' which all RabbitMQ servers have by default
• Exchange Type - The type of the exchange being subscribed to; keep in mind it is critical to get the correct exchange type as the RabbitMQ client will drop the connection when the incorrect type is passed (for example 'fanout' when the expected was 'topic')
• Routing Key - The optional routing key to use; by default since this demo uses the default topic exchange 'amq.topic' a routing key is added so that this script will only receive messages intended for the demo and not other messages being published to the 'amq.topic' exchange on the server - this also means published messages will have to include the matching routing key
• Update Position - Whether or not the script will update the object's position based on incoming position data; when disabled, position data is ignored
• Update Rotation - Whether or not the script will update the object's rotation based on incoming rotation data; when disabled, rotation data is ignored
• Update Scale - Whether or not the script will update the object's scale based on incoming rotation data; when disabled, scale data is ignored
• Update In World Space - When enabled, position and rotation will be updated in world space; when disabled, position and rotation will be updated in local space
• Debug Log Messages - When enabled, received messages will be logged to Unity's debug console

You should open up the AmqpObjectController.cs script and familiarize yourself with how it works to see how you can expand upon this technique.

Understanding the Message Format

In this example we will be using a custom JSON message structure that is expected by the AmqpObjectController script.

JSON Message Structure

{ "id":"optional ID filter", "posX": 0, "posY":0, "posZ": 0, "rotX":0, "rotY":0, "rotZ":0, "sclX":1, "sclY":1, "sclZ":1 }

Note: Since AMQP does not specify anything about the message's body/content itself, you could use whatever message format you would like (binary, ASCII, etc.), however you will need to implement a custom parser in the Unity script that will be receiving and making use of the message.