As part of the #UnityportingUK http://www.unityportinguk.com one of the most common question we get is how can I take advantage of Azure Cloud Services

image
Setting up Azure and Mobile Services

If you do not have an Azure account, then you should sign up for one.

image

The Azure Mobile Services have a free tier that includes up to 500 devices as well as 500k API calls and you can also use the free tier for up to 10 services.  This means that you can test out a few things without having to pay for it.

Azure Mobile Services

Azure Mobile Services is a part of Azure that allows access to a database and has connection and sample code to talk to any mobile system that is out there.  This will provide you with the code or library to do the connection to Android, iOS, Windows 8, Windows Phone, HTML5/JavaScript, or even the Xamarin libraries. To get started, if you do not have any Mobile Services defined yet you can click on the Mobile Services tab on the left and then the Create a New Mobile Service link next to it.  You can also click on the New option on the bottom the of the screen and select Compute -> Mobile Service -> Create.

mobile1

mobile2

From here, you will get a popup to fill in to finish up the creation.  The first field is the name of the Mobile Service.  This name will also be the address for the service.  It must be unique. For this example, I named mine “unityleaderboard”.  The next field is the database to use as a back end for the service.  You can choice from “Use an existing SQL database“, “Create a free 20 MB SQL database“, or “Create a new SQL database instance“. 

createmobile

The database will now need to be configured.  You need to setup the username and password and also the region for making the database.

mobiledbsettings

mobiledbsetup

Now For Some Data

So up to now we have the Mobile Service setup, but there is no data yet.  Go into your new Mobile Service and then click on the Data link at the top.  You can now add a new Table to the database that was setup earlier.

mobiletablesetup

mobilecreatetable

The next step is to add the data fields to the new leaderboard table.  This will allow us to save the data for the UserName and the Score that is saved.  This is going to be a basic sample and not an optimized database, so I will be adding the UserName as just a string field to the table.  If this was a bigger system supporting multiple games, I would probably make a Player table with all of the players info there and then a leaderboard table that cross referenced that player table.  Since this is just a quick and simple leaderboard for a single game, keeping the raw text in the table is not that bad.  The Score field is going to be added as a Number so that we do not have to change the numbers of the score into a text field back and forth.  After clicking on the table name, you will see and can click on the Columns link to get to add new columns.  To add a new column, use the Add Column link at the bottom of the page.

mobilecolumnlistmobileAddScore

mobileallfields

At this point the new leaderboard service is up and running.

unity
Unity GameDev

Unity Plugin for Azure by BitRave provides a Mobile Services plugin for Unity 3D. Their GitHub repo includes cross-platform APIs (currently supporting Windows Store and Windows Phone) and example code. 

bitrave

Plugin Instructions

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

Creating a simply 2D Unity Game

When Unity is launched, a dialog pops up with two tabs Open Project and Create New Project.  Select the Create New Project tab and enter in a name for the project.  In the bottom left of the dialog, there is a dropdown for selecting 3D or 2D for the project.  Select 2D and then hit the Create button to make the project.

unitysetup

unitydefault

In the project pane, there is a folder names Assets. Create three folders, Plugins, Scenes, and Scripts.  This creates these folders under the Asset folder in the project’s folder.

mobileunityorganize

Saving the Scene

One thing that helps at this point is to manually save the scene.  Select the File -> Save Scene menu option and then select the Scenes folder and save the scene, for this tutorial I named it MainScene.  This will create a MainScene.unity file in the Scenes folder.

mobilesavescene

Adding the Plugin

Next, let’s take the plugin from the GitHub repro and take all of the files from the Asset folder in the AzureMobileServicesUniversalPlugin project and save them into the same folder as our scene. 

mobilesaveplugin

From here we will follow the second instruction line and drag the AzureUI script file onto the Main Camera object to attach the script.  From here we are going to be making some changes to this script to remove the Facebook login and to point it at the new leaderboard service that we made earlier.  At this point the project will not compile or run because we are missing the Newtonsoft Json.Net DLL.

JSON Library

As I said above, the plugin from Bit Rave suggests getting a Json library from the asset store. 

Leaderboard Class

The sample from BitRave is great but it just ties to the standard sample ToDo list that mobile services will make for you to test with.

I would suggest the following to make a more robust leaderboard, the suggestion is have a leaderboard table getting called and used.  In the Scripts folder, you will see a ToDoItem.cs script file with the following class defined.
TodoScript
In the Scripts folder, right click and go to Create -> C# Script and name it LeaderBoard.  This will create a new class that is derived from MonoBehavior.  This is the default for any script that is added.  What we can do here is to delete the class and actually just make one for our leaderboard table that is in our Mobile Service.  Originally in Mobile Services the tables had an Id field of an int.  The current system makes the Id field a string instead.  To fit into the sample from BitRave, I am also going to create a ToString method for the class to use for displaying. So creating a class for our leaderboard will give us a class that looks like this.  Please keep in mind that the name of the class should match the name of your table.

mobileleaderboarditem

AzureUI.cs

This is the file that is doing all of the GUI in this sample game and also calling the leaderboard service.

So what is the experience?

The free version of Azure mobile Services can get you going on a simple service.  It is limited to the number of devices and number of transactions per month, but when you hit those limited you should be able to move the service up to the next level for more resources and abilities. Another option is using a dedicated third party gaming services such as http://www.gamesparks.com/ who offer a free services for FREE services for  upto 10,000 user per month

image

Other Resources

Stacey Mulcahy, making a leaderboard using Azure Mobile Services.  She showed how to add the leaderboard to your HTML5/JS game.   

Steve Maier Azure Mobile Services to make a Leaderboard for a Unity Game Steve shows how to create a leaderboard in Unity