Azure Mobile Services for Unity 3D

Contents

Before You Start

The Azure Mobile Services plugin for Unity 3D is available open source at github.  That’s the place to go if you want to contribute or look at the source.  It’s on github here: https://github.com/bitrave/azure-mobile-services-for-unity3d .  However, if you don’t care about the source, and just use it, head to github as there is an example project with built binaries in it so you can just grab it and use it.

The below is a guide to using the Azure Mobile Services plugin for Unity 3D.

Overview

A suite of Azure Mobile Services plugins for Unity3D, cross platform with common interfaces, with examples.

The goal is simple. “Just hit build”. That means 1 API, no platform dependent code. The plugin should hide platform intracacies, not surface them.

Runs across:

  • UnityEditor – Lightweight support in Unity so you don’t need to build to test your app. No more stubbing data locally.
  • Windows 8 Store – Uses the underlying native DLL for consistent and robust integration
  • Windows Phone 8 – Uses the underlying native DLL for consistent and robust integration

Coming soon:

  • iOS
  • Android

5 Second Guide

Put the plugin binaries in your Assets/Plugins folder.  These get built into an Output folder in the root of the solution in the right folder structure.  And it’s as simple as…

var data = new LevelSaveData() { SaveData = “some data here“, Id = 1 };

var azure = new AzureMobileServices(_azureEndPoint, _applicationKey);

azure.Update<LevelSaveData>(data);

or

var azure = new AzureMobileServices(_azureEndPoint, _applicationKey);

azure.Lookup<LevelSaveData>(1, azureResponse =>

{

if (azureResponse.Status == AzureResponseStatus.Success)

{

var ourObject = azureReponse.ResponseData;

}

}

Data comes back via callbacks and response objects.  Unity doesn’t support await/async, but when it does it will move to that model.

API

Initialise

Initialisation is just as simple as you’d expect.

var service = new AzureMobileServices(“url”, “token”);

Insert

Insert an item into your Azure database in a single line of code from Unity.

service.Insert<ToDoItem>(myItem);

Update

Update items in the Azure databsae with just one line of code from Unity.

service.Update<ToDoItem>(myItem);

Delete

Remove items from the Azure database in 1 line of code from Unity.

service.Delete<ToDoItem>(myItem);

Query

Query items in your Azure Mobile Services from Unity.

service.Where<ToDoItem>(p => p.Category == “Exercise”, azureResponse =>

{

List<ToDoItem> exerciseItems = azureRepsonse.ResponseData;

NOTE: await / async will be available when supported by Unity.  Until then we are using callbacks.

Lookup

Lookup items in your Azure Mobile Services from Unity.

service.Lookup<ToDoItem>(myItem, azureResponse =>

{

ToDoItem myToDoItem = azureResponse.ResponseData;

NOTE: await / async will be available when supported by Unity.  Until then we are using callbacks.

Login

On supported platforms, LoginAsync can be called for authenticated services.

azure.LoginAsync(AuthenticationProvider.Facebook, loginResponse =>

{

var token = loginResponse.ResponseData.MobileServiceAuthenticationToken;

});

NOTE: await / async will be available when supported by Unity.  Until then we are using callbacks.

Visual Studio Solution

The Projects

There are multiple projects in the solution.

  • Bitrave.Azure.Editor – This provides Azure support directly from within the Unity Editor, it’s not currently fully featured, but offers a way to test against real data in the cloud rather than stubbed local data.
  • Bitrave.Azure.Stub – This is a stub class for assisting with building projects out of Unity.  It assists with hiding complex dependencies that cause issues with Unity.
  • Bitrave.Azure.Windows8 – The Windows 8 Azure Mobile Services plugin for Unity 3D.
  • Bitrave.Azure.Windows8.TestApp – A test app to help debug the plugin behaviours since the plugins can’t be debugged in Unity 3D.
  • Bitrave.Azure.WindowsPhone8 - The Windows 8 Azure Mobile Services plugin for Unity 3D.
  • Bitrave.Azure.WindowsPhone8.TestApp - A test app to help debug the plugin behaviours since the plugins can’t be debugged in Unity 3D.
  • RestSharp.Stub - This is a stub class that assists with building out of Unity for the specific platforms.

Building

Make sure you have the latest version of Nuget, then get the dependencies such as RestSharp, JSON.NET, and Azure Mobile Services.  You will need to also add a reference to the UnityEngine.dll for the respective platform.  If you can’t find these UnityEngine DLLs, just build out of Unity a blank WP8 project or a blank W8 project, and the respective DLLs will end up in the generated project.  If you want to use the PM command line for Azure, here it is:

Install-Package WindowsAzure.MobileServices

Once you have the DLLs all configured, hit build.

Once built your solution directory should have an output folder.  Within this is a Plugins folder structure with DLLs that you copy directly into your Unity project’s Assets folder.  It should look something like this:

c:\Projects\MyGame\Assets\Plugins\

c:\Projects\MyGame\Assets\Plugins\Metro\

c:\Projects\MyGame\Assets\Plugins\WP8\

When you build for a specific platform, the plugins from the root Plugins folder get replaced by DLLs with identical names in the platform folder.  This is why the RestSharp.Stub gets copied into WP8 and Metro since it’s only used for the Unity editor.  Metro and WP8 leverage the Azure Mobile Services SDK DLLs for their specific platform.

The Windows8 DLL gets copied into the Plugins/Metro folder since Windows 8 projects build nicely out of Unity.

The WindowsPhone8 DLL does not get copied into Plugins/WP8.  The Bitrave.Azure.Stub DLL gets copied due to dependency issues when building.  WP8 builds are still in early beta so this need may go away.

Next step, make sure you copy the right versions of Newtonsoft.Json DLL into the Plugins, Plugins\Metro, and Plugins\WP8 folders.  Also copy RestSharp into the Plugins folder.   It should look something like this:

pllugin_folders

And that’s how you get everything into Unity, and you should be good to start using it.  How to build for each platform is below.

Building For Platforms

Windows 8 Store Apps

  1. From Unity
  2. Select File->Build Settings (Ctrl-Shift-B)
  3. Select “Windows Store Apps”
  4. Select “Build”
  5. Pick a folder to build into
  6. Wait for it to build
  7. Open the generated solution in Visual Studio
  8. Check the references to the project, we’ll need to update some references.
  9. Remove RestSharp from the references
  10. Remove Boo.Lang.dll if it is there, it won’t pass WACK
  11. Make sure that Newtonsoft.Json.dll is the right version for Windows 8
  12. Open up Package.appxmanifest.  Ensure Capabilities->Internet Client is enabled
  13. Manage Nuget packages for the project, add the Windows Azure Mobile Services SDK
  14. You should be good to go!
  15. Build and Run

Windows Phone 8 Apps

  1. From Unity
  2. Select File->Build Settings (Ctrl-Shift-B)
  3. Select “Windows Phone 8″
  4. Select “Build”
  5. Pick a folder to build into
  6. Wait for it to build
  7. Open the generated solution in Visual Studio
  8. Check the references to the project, we’ll need to update some references
  9. Remove Bitrave.Azure and add a reference to the Bitrave.Azure.WindowsPhone8 project’s Bitrave.Azure.dll in it’s bin/Release folder.
  10. Remove RestSharp.dll, it’s not needed
  11. Manage Nuget packages for the project, add the Windows Azure Mobile Services SDK
  12. You should be good to go!
  13. Build and Run
  14. PS – You need to deploy to a WP8 phone