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.
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.
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.
Once you have imported the package into your project, locate the example scene ObjectControlDemo:
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.
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.
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.
All properties in the JSON message are optional; you can just include the ones you need. The id property is meant to match the AmqpObjectController.IdFilter property. By making the ID values match it is possible to have many instances of AmqpObjectController in the scene each only listening for their own messages. This would be more efficiently achieved using routing keys and avoiding the IdFilter property entirely, but for this example it is kept simple.
Once everything is configured play the scene in Unity. Watch the debug console for useful output about whether or not the AmqpClient has successfully connected to the AMQP server and subscribed to listen for messages.
Once you have successfully established a connection to the server you can now send messages to the exchange to control the object. There are many ways to publish messages to the AMQP server, but if you are using RabbitMQ, one simple way is to publish a message directly from RabbitMQ's management interface. If you have installed RabbitMQ locally and the management plugin is enabled then you can access it using: http://localhost:15672.
Assuming you are using the defaults of this tutorial then browse to the Exchanges section and select amq.topic. To publish a message using the management interface, scroll down to the Publish message section.
Note: If you are using a routing key in the Unity scene (default amqpdemo.objects), make sure you also include the same routing key when publishing messages.
In the Payload field, enter a JSON message to update the object. Let's start with just Y Rotation for now. The message is as follows:
{ "rotY":45 }Once you have entered the routing key and payload, press the Publish message button. If the message was successfully routed you will see a green confirmation. If it was not successfully routed you will see a different color.
If your message was successfully published then go back to the Unity scene and check to see that the Cube received the update.
The Cube in your scene should now have its Y rotation value set to 45. You may want to enable the Debug Log Messages option on the AmqpObjectController script to aid in verifying that messages are being received.
If everything has worked correctly, congratulations, you are now controlling Unity from AMQP messages!
If you would like to try a message that updates all properties, try using the following message:
{ "posX": -2, "posY":1, "posZ": -1, "rotX":15, "rotY":45, "rotZ":35, "sclX":0.5, "sclY":1.5, "sclZ":1.75 }You should see all of the matching properties of the Cube updated in Unity:
You can also try setting the Id Filter property and setting a matching id property in the JSON message:
{ "id":"myObject1", "posX": 2, "posY":-1, "posZ": 1 }In Unity, set the Id Filter property of the AmqpObjectController to myObject1 in the inspector. Messages that have the id property set to myObject1 should be received by the Cube. However messages that do not have the id property or a value different than myObject1 should not be received by the Cube.