prime Azure plugin for Win8 & WP8 Unity games (Part 1)
This is a cross-post from my personal blog, found at www.davevoyles.azurewebsites.net. Go there to find more!
For some time now, prime has been an industry leader in platform specific extensions for Unity games. Many of these extensions allow developers to tie their Unity games with the native functionality of a platform. In the case of Windows 8 and Windows Phone, they include services such as the Microsoft Advertising SDK, Social network sharing, trials and in-app purchases, and of course Azure, which this tutorial will cover.
A big check mark in the plus column for Microsoft platforms is the fact that most of the Microsoft based plugins for Windows Phone and Windows 8 are free, due to our partnership. You can find them all here.
Jaime Rodriguez wrote a great piece about the partnership here, and how all of these plugins are available for free to developers over the next year.
Prime31 has a great set of documentation around their plugins, and the Azure one in particular. Quite simply, there are 7 functions exposed to you:
// Prepares the connection to the Azure servers. This must be called before any other methods. public static void connect( string applicationUrl, string applicationKey ) // Inserts a new item into the database public static void insert<T>( T item, Action completionHandler ) // Updates an item in the database public static void update<T>( T item, Action completionHandler ) // Deletes an item from the database public static void delete<T>( T item, Action completionHandler ) // Queries the database public static void where<T>( Expression<Func<T,bool>> predicate, Action<List<T>> completionHandler ) // Looks an item up to see if it is in the database public static void lookup<T>( T item, Action<T> completionHandler ) // Authenticates a user with the service provider. Note that the service provider must first be setup in the Azure web dashboard! The completionHandler // will return null in the event of a login failure. public static void authenticateWithServiceProvider( MobileServiceAuthenticationProvider serviceProvider, Action<MobileServiceUser> completionHandler )
It’s important to note that before you can use this plugin you must download and install the Mobile Services SDK from here.
Usages for Azure and BizSpark
Azure allows developers to tie into the cloud and take full advantage of all of the cloud. Personally, I use it for hosting my sites and HTML5 based games, as well as leaderboards for Unity games.
Larger studios, such as Turn 10, who recently released Forza 5 on Xbox One, use Azure for crunching physics calculations in real time, as well as the drivatars for racing against friends when they aren’t actually online. I’ve also seen people use the cloud for simple tasks like acquiring a static IP or batch crunching images through a virtual machine, rather than rely on your PC to handle it.
If you don’t have Azure already, you can sign up for a free trial. If you are a startup or budding developer, reach out to me and I can set you up with BizSpark, which is completely free and offers you:
- Windows 8 / Windows Phone developer accounts
- Visual Studio Ultimate 2013
- Windows 8
- $150 / month Azure credits
- Visual Studio Online (Formerly TFS)
- 90 Days of pluralsight + DigitalTutors training
- Free marketing support with Microsoft
Don’t worry about the cost if you’re a startup – we can help you with that, and many of the smaller studios I work with don’t foot the bill at all.
If you are completely new to Azure, then I’d suggest starting here at our educational center, which is how I learned. The Microsoft Azure Educator Grant program provides educators Microsoft Azure for use in their University curricula as well. (5 months).
Azure Mobile Services
Azure Mobile Services has a free tier that includes up to 500 devices and 500k API calls, and additionally, you can also use the free tier for up to 10 services. When I first got started with Mobile Services, I had no idea of what I was doing. Fortunately, Scott Guthrie has a great 10 minute video, where he gives a high-level overview of Azure Mobile Services.
He also gives a great overview of what Mobile Services is, but here is the gist:
Windows Azure Mobile Services makes it incredibly easy to connect a scalable cloud backend to your client and mobile applications. It allows you to easily store structured data in the cloud that can span both devices and users, integrate it with user authentication, as well as send out updates to clients via push notifications.
That link also provides a great starting point for creating your first mobile service, so I won’t cover it here.
Downloading and installing the prime Azure plugin
Start off by going to the plugins page and downloading the Azure Plugin. When you click on the download now button, it will prompt you for your name and e-mail. Fill out that form, and you’ll receive a link to download the plugin in your email moments later.
Download the plugin and import it into your current Unity project by double-clicking on it. This will place a new folder with several items inside of your Plugins folder in Unity. Your structure will now look like this:
Because this plugin was installed by hand, it will not appear in our prime Plug tab. This tab generally manages the plugins you’ve installed, and can be found at the top of the Unity Editor, under the prime pull-down.
When you load the MetroAzureTestScene, you won’t see anything other than a blue background. Press play, and you’ll be greeted with four buttons. They won’t do anything just yet though, because we haven’t built our project for Windows 8. In order to see any kind of functionality, we’ll need to build the project, and run it from Visual Studio.
Preparing your Build for prime plugins
We’re not quite finished yet. Go to File --> Build Settings, located at the top-right corner of Unity. Make sure that your Inspector window is visible, because we’re going to change some build settings for Windows 8 here.
You'll want to add the current scene to the build as well. While your MetroAzureTestScene is loaded, click on the Add Current button, and you'll see the path to the scene appear in your build settings. The checked box signifies that it will be included.
Click on Windows Store Apps, and on the right-hand side you will see several options. prime currently only supports C# / XMAL apps, so under Type you must select XAML C# solution. For SDK, I’m currently building for Windows 8, and I have Unity C# projects checked.
Select the button for Player Settings, and look at your Inspector window. You should see a tab for Publishing Settings; select that. Move down to Unprocessed Plugins, and you’ll see that the size currently reads 0. Change that to 1, and a new line appears, with the text Element 0 to the left of it.
This is a key bit of information missing from the prime documentation, and I spent 2 days troubleshooting the issue! This thread illustrates the issue, and the resolution.
You need to add "P31MetroAzure.dll" in this empty field, otherwise Unity never knows to build the project with your Azure plug.
Without that, you’ll receive this error when you try to build:
Error building Player: Exception: Failed to run Reference Rewriter with cmdline --target="Temp/StagingArea\P31MetroAzure.dll" --framework="C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETCore\v4.5" --platform="C:\Program Files (x86)\Windows Kits\8.0\References\CommonConfiguration\Neutral\Windows.winmd" --support="Temp/StagingArea\WinRTLegacy.dll" --system=System --dbg=pdb --alt=System.Xml.Serialization --ignore=System.IConvertible,mscorlib.[Temp/StagingArea\P31MetroAzure.dll] Catastrophic failure while running rrw: Mono.Cecil.AssemblyResolutionException: Failed to resolve assembly: 'Microsoft.WindowsAzure.MobileServices.Managed, Version=0.1.6.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' at Unity.ReferenceRewriter.RewriteContext.RewriteResolver.Resolve(AssemblyNameReference name) at Mono.Cecil.MetadataResolver.Resolve(TypeReference type) at Unity.ReferenceRewriter.RewriteTypeReferences.Visit(TypeReference type, String referencingEntityName) at Unity.ReferenceRewriter.ReferenceDispatcher.DispatchFields(TypeDefinition type, String referencingEntityName) at Unity.ReferenceRewriter.ReferenceDispatcher.Dispatch(TypeDefinition type) at Unity.ReferenceRewriter.ReferenceDispatcher.Dispatch() at Unity.ReferenceRewriter.RewriteOperation.Execute(RewriteContext context) at Unity.ReferenceRewriter.Program.Main(String args)
With that out of the way, go back to the Build Settings popup, and select Build. When it prompts you for a location, I generally create a new folder inside of my project called “Builds”, and then have more folders inside of that one for each platform. In this case, “Win8”. You’ll see a command prompt appear, and your game will build itself in the background.
To be continued.....
I'll consider the second and final part of this tutorial in my next blog post, but this should hold you over until then! Let me know in the comments below if you have any questions.