Getting started building Windows Phone Games with Unity

With the release of Unity 4.2, you can now take your Unity games and quickly port them to Windows Phone 8 and extend your reach to Windows users.

Getting started building a Windows Phone 8 game with Unity

To develop, compile and submit a Unity game to the Windows Phone store, you will need:

Unity 4.2 . Either the Unity free version or Unity Pro will work. The add-ons to publish to Windows and Windows Store are free, even for Unity Pro users.

Windows Phone SDK 8.0 The WP8 SDK includes a stand-alone version of Visual Studio Express 2012 - if you already have Visual Studio Premium or Ultimate, the SDK will work as an addin and you can continue to use your version-.

Windows 8.0 or later. If you do not own a Windows 8 license, you can get a 90-day evaluation version. If you are running Mac OS X or will install on Apple hardware, check different options for installing using Boot Camp, VMWare , or Parallels.

Windows Phone developer account . This is needed to “unlock” your phone so you can side load your game for developing and testing. It will also be needed to submit your game to the Windows Phone store.

Windows Phone 8 device. In Unity 4.2, deploying and debugging to the Windows Phone emulator is not supported, so you will need a phone. Once you have a phone and your developer account, follow these instructions to register your phone for development.

Porting your game

Targeting a new platform always requires a few tweaks, such as using a few platform specific APIs (e.g. in-app purchase or application life cycle) and tailoring the game to the device’s hardware capabilities (e.g. a back button).

Design-time differences

To create your game, you will still be using the Unity IDE. This will feel very familiar and keep your productivity high. That said, there is a significant difference that you should keep in mind: When running the game within Unity, it will run using the Mono run-time; however, once you build for Windows Phone platform and deploy to the phone, you will be running in the .NET for Windows Phone run-time.

Here are a few tips for dealing with this “dual run-time” environment:

1. If including script files that will run in Unity, use the #if UNITY_WP8 pre-processor directive to refer to code that should not run inside Unity.

2. For plugins, include Unity plugins to be used in the Unity editor in the Assets/Plugins directory and include the run-time plugins for Windows Phone in the Assets/Plugins/WP8 folder.

3. Make sure you test your game thoroughly on a device. If you are referencing a Mono API that is not on Windows Phone, it will work fine in the Unity player, and throw an exception on the phone.

4. Unity uses the Mono compiler to generate phone assemblies, as such you may find that once in a while you will call a Mono API that is not in phone and even the compiler (when you build for phone) will not catch it. These errors will lead to exceptions when running on the phone. A good tool to validate an assembly’s portability to Windows Phone is https://scan.xamarin.com. You should extend this practice of validating your assemblies to compiled plugins. If you purchase a plugin that ships as a binary, validate it to make sure it uses only Windows Phone APIs.

If you find errors or missing Mono APIs that you are using in your game, you should look at the .NET API for Windows Phone reference site to find alternates.

User interface

Windows Phone renders their UI using XAML. This infrastructure can be useful if you want to have UI that is not in your Unity game (such as a splash screen or ads). XAML UI and Unity UI can compose seamlessly. The way this composition works is via the DrawingSurfaceBackgroundGrid control. This control uses Direct3D to render what is effectively the background to the whole screen. Unity renders your game against this surface using hardware accelerated Direct3D. For more details on XAML + Direct3D composition, refer to the XAML and Direct3D apps for Windows Phone 8 write-up on MSDN.

The graphics composition with via the Unity engine will all be transparent to you. It is where you mix and match that you will need to remember these four details:

1. Within your app, you can include XAML UI controls and widgets (such as an ad control, buttons, etc.) that compose visually with your game.

2. If you add XAML UI, this will be in front of your game since your game is rendered as the background of the scene.

3. To maximize compatibility across screen sizes, XAML content is scaled. XAML content is 480 wide, and then scaled. [So on devices with 1280x768 resolution, Unity will see this resolution and XAML content will be 480x800, scaled 1.6 times. If you are trying to align a pixel-perfect composite of a scene that uses XAML and Unity content, you will need to scale down your Unity content. You can get the scale from the Appication.Current.Host.Content.ScaleFactor property.

4. XAML UI runs on a different thread than Unity, so you will need to dispatch messages to the right thread in order to access the respective UI components for each technology:

To tweak XAML UI from a Unity callback, use this:

    1: Dispatcher.BeginInvoke(() => 
    2: { 
    3: //access XAML UI elements here..
    4: });

To call from within XAML UI thread onto the Unity thread, use:

    1: UnityApp.BeginInvoke(() => 
    2: { 
    3: //access Unity objets here..
    4: });

Capabilities

Windows Phone games must declare some of the resources or APIs they will consume.

This is done via declarations in the application manifest (WMAppManifest.xml). If you are making network requests, accessing sensors, using push notifications, etc. you will need to declare these, else your app with get exceptions or failures with access denied.

Everything you need to know about capabilities is in the capabilities documentation page. Review that page and double click on the WMAppManifest.xml document in your Visual Studio project to declare the resources you will need; there is no coding required for any of these.

Process Lifecycle Management

The Windows Phone application model has one foreground app (the one that is visible) that has access to most of the OS resources (memory, CPU, networking); to enable fast app switching, the OS does keep recently used apps that the user has not explicitly closed in memory. All of this app model is explained to great detail in the “App activation and deactivation for Windows Phone documentation.

For games where you are saving state as early as possible, the default mappings to Unity events should work well. If you want to optimize further, all these events are in App.xaml.cs and the default Unity generated code is subscribing to them, you can add extra logic in the event handlers on the C# side, and use a plugin to communicate with your game code.

Hardware details

Windows Phone 8 has a detailed minimum hardware spec that all devices must meet; you should expect high-degree of consistency across the devices.

Hardware acceleration with programmable GPU. Windows phone uses Direct3D with feature level set to 9_3. MSDN has a great table of the supported features by level. The two biggest take-aways to notice are shader model level 2 and max texture size of 4096.

Windows phone 8 devices come in three resolutions: 480x800(WVGA), 768x1280 (WXGA) and 720x1280(720p). To find the resolution of your device, you can query the Screen.width and Screen.height properties within your Unity scripts; you can then scale appropriately within the game. For static assets outside the game (tiles, splash image, etc.) supplying assets for the WXGA resolution often suffices, Windows Phone will scale these.

Memory comes in multiple configurations: 512 MB of RAM for the WVGA devices, and minimum of 1GB RAM for the 720p devices. The newest phones such as Nokia 1020 are up to 2GB.

The OS limits how much memory a single application can consume; for lower memory phones this is around 150MB for a single app, and it goes up to around 380MB for higher memory phones. There are capabilities you can declare in your manifest to opt into specific memory behaviours and to opt out of running on low-end devices.

The default Unity projects opt into the ID_FUNC_EXTENDED_MEM capability, which says your game will run in a lower memory device, getting up to 180 MB. You can opt out of lower memory devices by using the ID_REQ_MEMORY_300 capability; learn more about the limits and the capabilities from the App Memory Limits documentation.

Accelerometer is available on all phones and directly accessible from Unity APIs.

Magnetometer and gyroscope are optional on the hardware on the phone. Compass APIs are not implemented in 4.2, but they are in the upcoming 4.3 release.

Hardware Back button. All Windows Phones have a dedicated back button and there are specific guidelines on what an app should do when the back button is pressed:

• If you have implemented navigation within your app, pressing the back button should go back to the previous step in your navigation.

• If you are inside a modal dialog (e.g. settings or achievements, etc.) pressing back button should dismiss the dialog.

• If you are not in a dialog and you are at the root of the navigation game (or you do not have navigation in your game), pressing the back button should exit the game.

To handle the back button, use the same mechanism as android: listen for the Escape key.

Note that proper handling of the back button is a certification requirement. If you do not handle it, you will fail certification. The default code exported from Unity does not handle it, they do the work to suppress it, and expect you to handle Escape key. If you do not want to waste cycles on every update listening for the Escape key you have a game with a single screen and no modal dialogs where the back button would always exit the game, you can comment out the e.Cancel assignment from the

    1: BackKeyPress event handler in MainPage.xaml.cs
    2: private void PhoneApplicationPage_BackKeyPress(object sender,CancelEventArgs e) 
    3: { 
    4: //e.Cancel = UnityApp.BackButtonPressed();
    5: }

Performance

As any mobile platform, performance is important and you should test for it. Most of the standard Unity guidance on optimizations for mobile devices applies. Most games should not need platform specific optimizations (outside of tweaking visual features to the GPU capabilities on phone). For those looking to get every drop of performance, interop cost on Windows is a bit higher than on Mono. You need to be smart about crossing the boundaries from your script (C# or UnityScript) to the unity engine (which is written in native code).

A few APIs are still in progress

Unity support for Windows Phone is still growing so not all APIs have been ported, there is only a few missing,

• Compass support is not in Unity 4.2

• Location services is not in Unity 4.2

• Webcam support is not in Unity 4.2

•  Microphone support is not in Unity 4.2.

• WWW is implemented but multiplayer networking APIs are missing. You can used .NET APIs or third party libraries (e.g. photon) as an alternative.

• GPU profiling is not available yet.

• Application.OpenURL is not implemented. You can use the Windows Phone WebBrowserTask for this.

Adding Windows Phone 8 Features

Enhancing your game with some of the Windows Phone platform features

Tiles & push notifications

The Windows Phone Start screen is a signature and highly praised feature in Windows phone. Tiles are the ‘first impression’ your users will get about your app; when used effectively, tiles can be a differentiator that drives continuous engagement to your game.

Anyone shipping a game for Windows phone should read the introduction to tiles for Windows Phone and the tile design guidelines for Windows Phone.

At a minimum, your game should have beautiful tile that meets the design guidelines on all possible sizes – tiles come in 3 sizes: 159x159 (small), 336x336(medium) and 691x336(wide).

To configure and include the tiles for your app, you must use Visual Studio’s manifest editor and include the images in your VS project.

Once you have a beautiful static tile, consider how to “invite” your users to come and play often. If you have a turn-based game, you can use the tile to notify the user of their turn; if you have a game that can start at any level, let the user create a secondary tile that lets’ them pin their favorite level and start there every time. If you have any server-side features (high scores from peers, special offers, etc.) use Windows phone push notifications to let the user know about your offers or any other relevant data that invites your user to play a game. You can also do local notifications, and scheduled tiles. There is a lot of different options to keep your start screen alive.

Unity does not include APIs for tiles and since Unity uses the Mono compiler, you can’t just include a script in your project to access tiles (the compiler won’t be able to resolve this), you must do a plugin and compile it using Visual Studio. For details on the tile APIs for Windows Phone, refer to the ShellTile class.

Splash Screen Image

A few seconds will pass between a user tapping to launch your game, and the Unity engine rendering it to the screen. Windows Phone allows you to configure an image that the OS will show between the time the user launches your app and when XAML UI is rendered to the screen. This image is a JPG and you can configure different sizes for the different phone resolutions:

Resolution

Image size in pixels

Filename (you must use)

WVGA

480x800

SplashScreenImage.screen-WVGA.jpg

WXGA

768x1280

SplashScreenImage.screen-WXGA.jpg

720p

720x1280

SplashScreenImage.screen-720p.jpg

You can also just include a single image called SphashscreenImage.jpg, this is what the default Unity builds do; if you are shipping a single image, make it the WXGA size, the OS will scale appropriately.

The Unity 4.2 Player Settings dialog does not allow you to override the Splash Image with your own, so you must configure it in Visual Studio. Instructions on where to copy the images to and what resolutions to use are in this How to create a Splash Screen walk-through.

Having a splash screen is a must-do, but it is usually not enough. Windows Phone only shows the splash image while the app is getting started and once it is ready to show XAML UI, it transitions into this XAML UI. For some games, there are still a couple seconds between that and your Unity UI. To get around this, you can just edit your XAML to display your splash image (or any other UI you want to display) until Unity is ready. For details on how to accomplish this, look at the “Extending your splash image” in the common tasks section below.

Monetization APIs

Windows Phone offers different options for monetizing your game.

Beyond the one-time purchase of your game, Windows Phone offers trials (that you would need to convert to a full purchase), in-app purchase for durables and consumables and advertising.

To access the in-app purchase APIs you will need to write a Unity plugin. MSDN has a great overview of the in-app purchase APIs, most concepts will feel ‘familiar’ for those who have implemented in-app purchase in other platforms. The only ‘quirk’ you will encounter is that Windows Phone does not have a staging environment to test in app purchase. There is a Mock API library that you can use for your development; if you feel that testing the in-app purchase APIs (not just the mock library) is absolutely required before submitting to the store, then do a beta for your game. This would allow you to test inapp purchase using the real APIs before you submit to production.

If you prefer to purchase a plugin instead of writing one, here are vendors that have plugins. RobotoWP for Windows Phone , BitRave and Prime31 have Microsoft Store plugin and lots of other useful Windows Phone and Windows store plugins such as Microsoft ads plugin, and an essential plugins that includes a lot of sharing tasks

Submitting to the store

To submit to the store, you will need your Windows Phone developer account and a licensed version of Unity. The trial version of Unity, will produce a water mark in the build that says “development build” on the bottom right of your game, and this will not pass certification. The Unity addins for Windows Phone are free for Unity basic and even Unity Pro users, so just contact Unity to get your free license.

When you are ready to submit to the store, follow these steps.

1. Check out the App certification requirements for Windows Phone 2. Become familiar with Windows Phone app product submission process.

3. Run your app through the Windows Phone Store Test Kit. The Windows Phone Store test kit is a suite of automated tests and manual tests for your game. The kit will identify and help you fix issues that Microsoft testers will find during certification; by finding them early, you will save a lot of time. The store kit can be executed from within visual studio (under the project tab), this walkthrough gives you step-by step- instructions and details on running the kit.

You will be tempted to just run the automated tests and ignore the manual ones; this is a bad idea; you can learn a lot about the platform and about making your game better from looking at what the Microsoft certification folks are testing for; give the manual tests a try and see how your game fares.

4. We recommend you go through a beta submission. More details at the “Beta testing your app” page , on MSDN

5. Submit your master configuration. Unity will create a debug, release, and master configuration for your visual Studio project. Make sure you submit the master, not the release one.

Other useful references

• Unity’s Windows Phone 8: Getting Started guide is a must read.

• The getting started with Windows Phone will walk you through downloading the tools, registering your phone for development (aka unlocking the phone) and writing a basic app that walks you through Visual studio project structure.

• The Windows Phone SDK samples collection has hundreds of coding samples to accomplish specific tasks.

Debugging a Windows Phone game

Unity has instructions on debugging with visual studio.

Profiling in Visual Studio

Unity has instructions on profiling Windows phone apps