Use Azure Services from Unity

tl;dr – Azure and Unity, really?

Azure Services for Unity is a small library (currently in beta) that provides you an easy way you to access an Azure database and/or APIs (hosted on Azure App Service) via the Unity game engine. You can use it to save highscores, status messages, send messages between players and much more. As there are no plugins involved, library is cross-platform and can run everywhere that Unity runs (editor, standalone players, iOS, Android, Windows Phone and Windows Store Apps). Of course, it is completely open source and free to use. It was last tested on Unity 5.3.4f1. Current version 0.0.2.

Update: for some additions and fixes to the library check out my newer blog post here
Update2: check this blog post for an addition to the library that allows you to access Azure Table Storage Service.

Intro

Azure App Service is quite an interesting cloud platform to develop web and mobile apps. One can easily create web apps that scale, create mobile apps backend and integrate with existing services either on the cloud or on-premise. App Service also has a very simple mechanism to store data and use various APIs, called Easy Tables and Easy APIs, respectively. Those can be rather helpful to game developers that want to create a backend for their game. In this blog post, we’ll describe a small library that allows a game written in Unity to access them.

Creating an Azure App Service and database

We assume you have an active Azure subscription. If not, refer to the last paragraph on this blog post to find out easy ways to get one. First, you’ll need to visit the new Azure portal at http://portal.azure.com.

Create the App Service

Select “New”, “Web+Mobile”, “Mobile App”. Select a URL, a Resource Group and a Service Plan (you can even use a free tier).

Screen Shot 2016-04-13 at 19.29.26.png

Click “Create” and wait a few minutes, till the new App Service is deployed.

Create the Database

Find the newly created App Service via the “All Resources” blade. Click “Settings”, then “Easy Tables”. You’ll see a message that there is a need to “Configure Easy Tables/Easy APIs”. Click there to continue. You’ll see another message that you need a database. Click it.

On the “Data Connections” window, click the “+” sign to create a new connection. Click “Create a new database” (we suppose that you do not have one).

Screen Shot 2016-04-13 at 19.35.48.png

Fill the necessary settings to create a new database and a new database server to host it. You can use a free database (up to 32MB, so be careful!).

Screen Shot 2016-04-13 at 19.37.37.png

Press “OK” on the blades that you have opened (I counted 3 “OK” button clicks) and wait for the data connection to be created, it may take a couple of minutes. Once it’s done, close the “Data Connection” blade and return to the “Easy Tables” one. Press the “Initialize App”, after you acknowledge that this will overwrite your existing contents. Again, wait for a few minutes for the backend to initialize.

Create a table

On the “Easy Tables” blade, click on the “Add” button to create a new table. Let’s name it “Highscore”. Take notice that you can set authentication options for each table operation. Click “OK”. Once it’s created, click on it and then click on “Manage Schema”. You’ll see some columns already defined, click “Add a column” to add a couple more. We’ll add a “score” with datatype “Number” and a “playername” with datatype “String”.

Screen Shot 2016-04-13 at 20.04.35.png

Create an Easy API

Return to the App Service’s “Settings” blade. Click the “Easy APIs” setting. Click the “Add” button and select a name for your new API. Again, take notice of the fact that you can alter authorization options for the various HTTP operations you can perform on this specific API. We named our API “Hello”.

Once you click “Edit”, you will be transferred to “Visual Studio Online” where you’ll see that your App Service is based on a Node.js backend. So, your API will be a JavaScript method. Since we named our API “Hello”, the Azure portal created a file “Hello.js” on the “api” subfolder. There, I created the following method that just responds with a simple JSON message.

Screen Shot 2016-04-13 at 20.10.43.png

How do I use the library?

Simple! You can download the code. Inside it you’ll find a scene with some buttons that call the relevant code to do CRUD operations on the database or call an Easy API. The calls have the following format

AzureUnityServices.Instance.Operation(arguments, callback)

The callback method carries a CallbackResponse object that has

  • a Status property, that determines the status of the operation
  • a Result property, that carries the response object (of type ReturnObjectType

All the code resides in the AzureServicesForUnity folder. Inside it you can also find a prefab GameObject that you can drag/drop onto existing scenes to take advantage of the library. Don’t forget to set the url of your App Service in the format http://yourdomain.azurewebsites.net

ab

Check the UIScript file on the Scripts folder, you’ll find that the method calls are easily self-explainable.

Last but not least, you need to create a class that corresponds to the Easy Table you’ve created. For example, for the Highscore table we created on the Azure portal, we have created this class

[Serializable()]
public class Highscore : AzureObjectBase
{
    public int score;
    public string playername;
}

This class needs to inherit the AzureObjectBase class (which just provides an ID variable) and be Serializable.

What operations are offered by the library?

The following operations are supported by the library

  • CallAPI(apiname, httpMethod, callback) – to access EasyAPIs
  • Insert(instance, callback)
  • SelectFiltered(query, callback) – query can be null in order to get all rows
  • SelectByID(id, callback) – returns single object
  • UpdateObject(instance, callback)
  • DeleteByID(id, callback)

The most interesting method is the SelectFiltered one. The query object is an IQueryable object, like

string pn = "d";
var query = q.Where(x => x.score > 500 || x.playername.StartsWith(pn)).OrderBy(x => x.score);

This is by no means a fully functional IQueryable implementation! We’ve implemented some features of it which are the most commonly used, specifically

  • Where
  • Select (simple projections)
  • OrderBy and OrderByDescending
  • Skip
  • Take
  • some string operations, like StartsWith, Contains, ToUpper, ToLower

These are all translated to their OData equivalents (yup, Easy Tables are OData friendly!). For example, this piece of code

ODataQueryProvider odqp = new ODataQueryProvider();
ODataQuery query = new ODataQuery(odqp);
int min = 50, max = 100;
string name = “Dimitris”;
var q = query.OrderBy(x => x.score).Skip(3).Take(2).
Where(x => ((x.score > min && x.score < max && x.playername.ToLower().Contains(“d”)) || x.playername == name).Select(x=>
new { x.id, x.playername });

would be translated to

?$filter=((((score gt 50) and (score lt 100)) and substringof(‘d’,tolower(playername))) or (playername eq ‘Dimitris’))&$skip=3&$take=2&$orderby=score&$select=id,playername

and get appended to the URL. Of course, it would bring the relevant results.

How can I use authentication?

Using authentication almost always involves calling platform specific (native) code. Since we wanted this library to be plugin free, we opted to leave the authentication method completely to other relevant libraries. For example, you can use Facebook’s Unity SDK to get an authentication token for logged in users. Once you have it, you can pass it to AzureUnityServices.Instance.AuthenticationToken field and your Azure App Service calls would be authenticated and (hopefully!) authorized!

Why beta?

This library is in beta, for, well, many reasons. First of all, our OData implementation is pretty basic and still may contain bugs. Secondly, Unity’s JSON Parser is still pretty basic since it can’t deserialize responses that contain object arrays, so we had to resort to a small hack to get it working. Finally, we use a fairly new Unity class to do the HTTP Requests, called UnityWebRequest. It currently resides in a namespace called UnityEngine.Experimental.Networking. Well, from the “Experimental” word you can feel the beta of it!

Where does it run?

That’s the best part. Almost everywhere! Copying and pasting from the Unity manual (as of April 14th, 2016)

The UnityWebRequest system supports most Unity platforms, with the notable exception of the Unity Web Player.

Platforms supported in 5.2:

  • All versions of the Editor & Standalone players
  • WebGL

Platforms supported in 5.3:

  • Mobile Platforms: iOS, Android, Windows Phone 8
  • Windows Store Apps

Additional platform support will be rolled out in further 5.x releases:

  • PS3, PS4, PS Vita, and PS Mobile
  • XBox 360 and XBox One
  • Wii U

Can I use it in my game?

Yes, feel free to do whatever you want with it. Check the MIT license file here.

I can’t find any documentation for Azure App Service REST API. How did you do it?

Two things

  • Fiddler. If you are doing anything related to HTTP and don’t use it, DOWNLOAD IT NOW
  • Lots of step by step debugging and variable monitoring on official Azure Mobile Apps SDK. If you ask “hey, there’s an official SDK for that, so what am I doing here?” the answer is that the official SDK relies heavily (and for good reason) on azync/await methods (and other C# goodies) which Unity does not support yet.

Next steps

Well, a lot! We basically want to see if you use it, if it’s useful for you, extinguish possible bugs. Some specific things:

  • We definitely want to enhance the OData parser since, well, it’s pretty basic now
  • Probably merge the SelectFiltered and SelectByID methods, still under consideration

How do I get some Azure???

So, you’ve read the blog post (thanks, by the way!) and you may be wondering how to get access to Azure to use for your game. Well, there are many ways!

  • You can use a free trial here
  • If you only want to test the App Service, check out this page
  • If you’re a student, try getting access by visiting www.dreamspark.com. There, among other things, you can find some free access to Azure. It’s a bit limited regarding services you’ll get, but it’s more than enough to get you started.
  • You can also try and enroll into the Visual Studio Dev Essentials program that also includes some free access to Azure services.
  • If you’re an indie game dev team, you may qualify as a startup and, thus, have access to the BizSpark program. Here, you’re getting about 27k$ in a 3 year period worth of Azure services. Technically, you get 5 MSDN subscriptions (for 5 developers in your team, that is) and each subscription has 150$ worth of Azure. This lasts for three years.
  • If you’re doing good as a game dev startup and are ready to scale more, you may check the BizSpark plus program. Want cloud? Come get’some! 120k$ worth of Azure services, free for a year! Yup, you’re not reading it wrong.

26 thoughts on “Use Azure Services from Unity

  1. Hi,

    Just wanted to show my appreciation for the work that was done. This is a really simply and easy to use solution. Managed to customize to meet my requirements in minutes, good job on this post.

    Thank you very much.

    Any chance there is a support blog or some way to report issues if found?

    Like

  2. Hi

    Please help,

    We tested our project on an IOS device today and when you try to use “SelectFiltered()” we are getting the following error:

    ExecutionEngineException: Attempting to JIT compile method ‘(wrapper dynamic-method) System.Runtime.CompilerServices.ExecutionScope:lambda_method (System.Runtime.CompilerServices.ExecutionScope)’ while running with –aot-only.

    Like

  3. IOS does not support JIT only AOT.

    so this is what we have found to try and resolve, but still too much of a noob to understand what they are saying.

    http://www.reentrygames.com/unity-3d-using-extension-methods-to-solve-problems-with-generics-and-aot-on-ios/

    This link discusses the issue in detail, but again we tried but it does not look like we understand what they are saying.
    http://forum.unity3d.com/threads/executionengineexception-on-ios-only.113750/

    Like

      • This is the complete debug log.

        ExecutionEngineException: Attempting to JIT compile method ‘(wrapper dynamic-method) System.Runtime.CompilerServices.ExecutionScope:lambda_method (System.Runtime.CompilerServices.ExecutionScope)’ while running with –aot-only.

        (Filename: Line: -1)

        Loading…

        (Filename: /Users/builduser/buildslave/unity/build/artifacts/generated/common/runtime/UnityEngineDebugBindings.gen.cpp Line: 37)

        Like

      • Thank you. Try something for me and let me know if the debug log is any different.
        Visit the PartialEvaluator.cs class and in the EvaluateIndependentSubtrees change these lines of code

        if (expr != null &&
        subtrees.Contains(expr) &&
        expr.NodeType != ExpressionType.Constant)
        {
        // Turn the expression into a parameterless lambda,
        // evaluate it, and return the response as a constant.
        Delegate compiled = Expression.Lambda(expr).Compile();
        object value = compiled.DynamicInvoke();
        return Expression.Constant(value, expr.Type);
        }
        else
        {
        return recur(expr);
        }

        to just

        return recur(expr);

        and let me know. I suspect that the problem is in the call of the DynamicInvoke method, which is prohibited due to AOT compiling.

        Like

      • Hi,

        We made the suggested change:
        return VisitorHelper.VisitAll(
        expression,
        (expr, recur) =>
        {
        return recur(expr);
        // if (expr != null &&
        // subtrees.Contains(expr) &&
        // expr.NodeType != ExpressionType.Constant)
        // {
        // // Turn the expression into a parameterless lambda,
        // // evaluate it, and return the response as a constant.
        // Delegate compiled = Expression.Lambda(expr).Compile();
        // object value = compiled.DynamicInvoke();
        // return Expression.Constant(value, expr.Type);
        // }
        // else
        // {
        // return recur(expr);
        // }
        });

        We are getting the following:
        NotSupportedException: The member ‘startWith’ is not supported in the ‘Where’ Mobile Services query expression ‘value(hwsh_Azure_Data_Manager+c__AnonStoreyB).startWith’.

        Our testing led us here,

        Debug.Log(“2========= get tables url: “+ url); //THIS IS THE LAST LOG WE SEE

        private IEnumerator SelectFilteredInternal(EasyTableQuery query, Action<CallbackResponse> onSelectCompleted)
        where T : AzureObjectBase
        {
        Debug.Log (“1========= selectFilteredInternal method”);
        string url = GetTablesUrl();
        Debug.Log(“2========= get tables url: “+ url); //THIS IS THE LAST LOG WE SEE

        if (query != null) {
        Debug.Log (“3========= Query not null: ” + query);
        url += “?” + query.ToODataString ();
        Debug.Log (“4========= url built: ” + url);

        We did test on the device as well and we are no longer seeing the JIT error, only the above described issue.

        Like

  4. this is the code we are calling,

    public void hwsh_Select()
    {
    EasyTableQueryHelper queryHelper = new EasyTableQueryHelper();

    string startWith = “”;
    var query = queryHelper.Where(x => x.hwsh_user_popularity_score x.hwsh_user_popularity_score);

    if we remove this section the query runs successfully and we can retrieve the data.
    x.fb_user_name.StartsWith(startWith)).OrderByDescending(x => x.hwsh_user_popularity_score)

    But now we are unable to sort the data in order. Is there another way to sort the data? Because that would solve our problem and we could carry on. :)

    Like

      • Unfortunately we need the retrieve the data presorted, we first attempted sorting client side but due to the large amount of potential entries we would be retrieving from the database this is not something we can do.

        good news, my buddy just did some magic.
        we are now able to retrieve the data and order it,

        made the following change.
        var query = queryHelper.Where(x => x.hwsh_user_popularity_score > 0).OrderByDescending(x => x.hwsh_user_popularity_score);

        and it is now working.

        Like

  5. Thanks for the amazing work, however it doesn’t work everywhere as stated in your description for example try to build a UWP project from unity and you get 104 errors, mostly because some code is not supported in UWP library and so you would have to provide 2 casses for each one for #if NETFX_CORE and the #else for others.
    I’ve added an issue on github with a small part of the errors I get when building.
    Thank you!

    Like

  6. Hi there, great tutorial you got there..very easy to implement..
    However i got problem to understand the authentication part.
    Did you got any tutorial of it? it seem i really cant understand the about facebook auth for unity using ms azure very well. Any help is greatly appreciate..Thank you :D

    Like

    • I would recommend checking Facebook SDK for Unity and its relevant documentation here. When you use it in your game, you will allow your player to login using Facebook. When this does happen, you will get a token which you pass here AzureUnityServices.Instance.AuthenticationToken. Let me know, thanks!

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s