Tuesday 2 September 2014

Compiling and Deploying Windows Store Applications using MonoGame or Unity 3D

This time, I'm addressing an annoying concern that I found. Trying to understand how to build Windows Apps.

There are three flavors of Windows 8:
  • Windows 8 Desktop (the normal operating system we know and … use)
  • Windows 8 RT (which runs on the surface tablets)
  • Windows Phone 8 (yet another OS)
Windows 8 Desktop is simple to build applications for. Its backwards compatible with all the previous versions, so any techniques you used in the past work. But the Windows RT is a different beast. The main thing is it only runs Store Applications, it will not run any of the ‘normal’ windows applications.

The worst bit about all this is the lack/fragmented collection of documentation on the topic. So this is me, trying to put all the documentation all together in one place. To give a step by step process of compiling the application as a Windows Store Application and deploying it on a Windows Surface Device.

Most of this document will be on using MonoGame to make applications, with an extra section at the bottom on using Unity3D.

Setup:

You will need
  • A windows 8 Desktop machine with the following installed
  • A Windows RT device for deployment testing
  • A network
    • Because both devices MUST be in the same subnet
  • A Windows Live account to enable your developer access

Network Test:

First things, make sure that both sides can ping the other. Use ipconfig to get the IP addresses and ping to test connectivity. When I was testing, I found that my surface device did not respond to pings, so the following steps had to be done.
  • Go to control panel: system & security: Advanced settings: firewall
  • In the incoming settings: find ‘File and Printer Sharing (Echo Request –ICMP IPv4) and enable it
That allowed incoming pings and I was sure that the network was operational


The Blue Screen of Success:

Simplest task is to create a new project, compile & deploy to the device.
In VS2012, create a new project of type ‘Windows Store App’
There may be a requirement for you to get a windows developer license:
To get this you will need your live.com account. It will give you a licence for ~30 days.

Compile & test that you get a nice sky blue window on you development machine.

Running on Remote:

Now in the toolbar, change the location from ‘Local Machine’ to ‘Remote Machine’
You will get a dialog popping up asking for the IP address of the device, which you can enter.
If you ever need to change it again, just open the projects properties and select the Debug Settings:
On Tablet run the ‘Remote Debugger’ application:
It may be necessary to also setup the firewall exceptions and request a developer license for the tablet too. But at least Microsoft have made it fairly painless.
Once you have the Remote Debugger running, you can hit F5 on the development machine and watch the PC deploy and run the application on the tablet.
<Sarcasm> It’s a blue screen!!! Wow!!! </Sarcasm>
You can change the application name by altering the ‘Package.AppManifest’, and change the icons using your favourite paint program. And then start to write some real code.
All easy so far.

Content Pipeline Woes:

One of the create joys of working in XNA was the drag-drop nature and ‘it just works™’ of the content pipeline. However, MonoGame has yet to ace this one currently, so this will get a little bit messy.

Now add in a new project of the type ‘MonoGame content project’. I called mine ‘MyContent’.

Note:
I’m not sure it this is available in VS2012 by default. Most of the MonoGame documents say that you use VS2010 to use this. I believe that because I installed the XNA tools for VS2012 (https://msxna.codeplex.com/) it worked ok.

You add in XNA content as usual. But for each content you add, you must select it and change its content processor to the MonoGame equivalent:
Once all the content is in, right click on the content project and select the configuration manager:
For the content project, set it to Windows 8| any CPU
Compile the ‘MyContent’ project, then open up explorer & look into the “GameName1/MyContent/MyContent/bin/Windows8” directory.
Ignoring the dll (obviously), and drag drop the whole content folder into Visual Studio project
Say yes-to-all for any overwriting questions.

Now select ALL the XNB items and change build action to ‘content’. Some people say that you should change the ‘Copy to Output Directory’ to ‘Copy If Newer’ must also be set. However I didn’t and it seemed to work for me.
You can now use the Content as you would use it in a normal XNA project.


Debugging the Errors:

If you followed the above steps EXACTLY, it should have worked. Notice I say ‘should’. When I was developing, I spent a lot of time watching my application near silently fail with no idea what was wrong.

If you are one of those, look at the output window (if you don’t see it, Menu: Debug: Windows: Output)
There are a lot of first chance exceptions: File not found & Content Load Exception. But Visual Studio didn’t do its usual stopping as soon as it hit an error. I don’t know why it doesn’t instantly stop in MonoGame when it does in XNA. But here is how to re-enable this:

In the menu, select Debug: Exceptions. When the dialog box appears, press the Add button:
Add in: Managed Debugging Assistants, Microsoft.Xna.Framework.Content.ContentLoadException
You must then make sure the check box is ticked.
Now close the dialog box and in the menu select: Tools: Options.

In the dialog box, find Debugging: General. Then set ‘Enable the exception assistant’ and ‘Enable Just My Code’
Now if there is a problem with the content, it will now stop instantly (as it should). You can now double check the spelling, make sure the file is in the content folder, check that the properties are set correctly etc.

Extra: Compiling Windows Store Applications with Unity3D

To compile a Windows Store Application with Unity 3D is very simple once you have got the development machine with VS2012 and the hardware with the remote debugging tools working together.

Create your Unity3D project as usual (I’m using angry bots for this).

Open Unity’s Build settings and select Windows Store Apps. You are given the choice of XAML C# Solution or XAML C++ Solution. There seems to be little difference between the two (though C# gives the option ‘Debugging Unity C# Projects’).
Once you have done the settings, build the project. You will be prompted for a directory to put the files into. Once the building has finished, you will discover that Unity has creates a Visual Studio solution which you must now open.

Deploying the project:

This is basically the same as for MonoGame: Open the project, select remote device, compile & deploy.

The only item to note is that when compiling in Debug mode, the deployment size is greater than 100MB! That takes a very long time to deploy on your device unless you have very fast WiFi.

Therefore it’s a better idea to try compiling and testing locally or in the simulator before going for deployment to hardware.


Conclusion:


You can see my Window RT tablet with the games installed. It’s been an interesting challenge to get all the facts together and put it all into one place. Hopefully this will be useful to others working on getting Unity3D/MonoGame making Windows Store Applications.

Happy Coding:
Mark

No comments:

Post a Comment