Getting started on Windows Phone with UnityThis document is evolving constantly with new and updated information. It is still a work in progress. If you need answers that this document does not address, try the Unity Windows Phone Development Forum: http://forum.unity3d.com/forums/50-Windows-Development.

Contents

Contents.................................................................................................................. 1

Introduction................................................................................................................2

Requirements to write a Windows Phone game with Unity.....................................2

Porting Overview........................................................................................................3

Design Time – The Unity Editor Experience.............................................................3

Including Windows Phone code in your Unity project...........................................3

Compile Time - Building from Unity to target Windows Phone................................4

Player Settings.....................................................................................................5

Windows Phone project and Visual Studio - Development Flow...........................5

Run Time - Running the Generated Windows Phone App........................................6

Hardware Differences...........................................................................................6

Graphics...............................................................................................................6

Displays................................................................................................................6

Memory................................................................................................................6

Hardware APIs......................................................................................................6

Beyond the port, Integrating with the platform....................................................7

Submitting to the store..............................................................................................7

Other useful references..............................................................................................8

Feedback & Revision history................................................................................8

Getting started on Windows Phone with Unity1

Introduction With the release of Unity 4.3, porting games to Windows Phone has become easier than ever.

This write up should give Unity developers all the high-level information they will need to take an existing Unity game and tweak it to target the Windows Phone.  The guidance is not all inclusive on technical features, but it should point you on right direction and give you the most relevant context and links to get further details. Make sure you click on the links, there is a lot that was not replicated on purpose.

Requirements to write a Windows Phone game with Unity

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

Unity 4.3 . Either the Unity free version or Unity Pro will work.  The add-ons for publishing to the Windows Store and to Windows Phone are free, for basic and Unity Pro users.

Windows Phone SDK 8.0 . The WP8 SDK includes a stand-alone version of Visual Studio Express 2013 - if you already have Visual Studio Pro, Premium or Ultimate, the SDK will work as an add-in 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 .  If you plan to target Windows Store in addition to Windows Phone, running Windows 8.1 and VS2013 is recommended since you can target both Windows 8.0 and 8.1 with this configuration.The upgrade from Windows 8.0 to Windows 8.1 is free

Microsoft account. You will need a Microsoft account to get a developer license. A Microsoft account is free, you can get one at http://signup.live.com

Windows Phone developer account . This will be needed submit your game to the Windows Phone marketplace. During this process you will register and get verified as an individual or as a business who can submit apps and games to the store. This registration is shared with Windows Store (one registration submits to both stores). Registration is $19 for individuals.

Windows Phone 8 device. In Unity 4.3, deploying and debugging to the Windows Phone emulator is supported, but it still does not beat testing on a real device. Once you have a phone, follow these instructions to register your phone for development and enable deployment and debugging .

Getting started on Windows Phone with Unity2

Getting started on Windows Phone with Unity3

Porting OverviewTo prepare for a port, you must be familiar with Windows Phone platform specific nuances in the following areas:

Design Time – The Unity Editor Experience Build Time – Building from Unity Editor to produce a Windows Phone app Run Time – Running the Windows Phone App

Design Time – The Unity Editor Experience

To port your game to Windows Phone, you will still be using the Unity IDE.   This will feel very familiar and keep your productivity high.

The design-time looks the same and should feel the same since within the editor Unity is running your game on Mono run-time. It is when you build and run your Windows Phone project that you will notice the difference as the Windows Phone runtime is .Net for Windows Phone.

.NET for Windows Phone is a subset of .NET, so you might run into some errors with some APIs that are in Mono and are not in .NET. For most of these types, there is alternate types and functionality using .NET or WinRT APIs, but you will have to tweak your code to make it run. For details on porting techniques, please read our Windows Phone – Porting Tips documentation.

It’s worth noting that you can debug directly into your Unity code from within a generated Windows Phone solution using Visual Studio.

Including Windows Phone code in your Unity project

If including script files that will run inside the Unity editor, use #if (UNITY_WP8 && !UNITY_EDITOR) pre-processor directives to refer to code that should not run when testing in the editor.  This will ensure that the code will only run within the generated actual Windows Phone application. The !UNITY_EDITOR deals with the scenario where you are running in the editor with the platform switched to Windows Phone via File > Build Settings.

If you are comfortable with the code running in the editor and when the platform is configured to Windows Phone apps, you can simply use #if UNITY_WP8. Note that code running in the editor can’t reference Windows Phone APIs, since the editor will not know how to resolve these.

.Net for Windows Phone APIs include most of the functionality to do integration with Windows Phone such as implementing launchers and tasks, or access to sensors, you will still be able to reference all these from Unity plugins, just not directly within code executing in the editor.

Getting started on Windows Phone with Unity4

Compile Time - Building from Unity to target Windows Phone

In order to build you must switch your target platform in the Build Settings window to Windows Phone 8 using File > Build Settings

When you build, this will generate a Windows Phone Xaml/C# solution that you will compile in Visual studio to get your final package. (aka XAP file). .

Getting started on Windows Phone with Unity5

Player Settings

After clicking on the Player Settings button, you will see settings that you can configure relating to the outputted Windows Phone solution which affect the creation of the Windows Phone app manifest file.

Windows Phone project and Visual Studio - Development Flow

When you target Windows Phone, you will likely run into a few of the issues we mentioned above, please refer to the Windows Phone Porting Tips white paper, specifically the getting your app to compile in Unity section, and for more on how to resolve API related errors during porting.

Once you have resolved any compile time errors, Unity will export a project that you will compile using Visual Studio to test, run and publish your game. This means there is two steps to creating a game:

1. Generate player and project from Unity2. Compile in Visual Studio to create final binary and Windows Phone solution

It’s worth noting that each time you build inside Unity, you can target the same folder and Unity will not overwrite any solution file changes that you have made in Visual Studio. Unity will update the following folders and files:

1. The /Data folder in your project2. Project reference assemblies (added to project root excluded from project

itself)

This allows you to alter the Visual Studio project and add more native features or to tweak manifest and configuration files and not lose these Visual Studio changes if you make a change to the gameplay.

One important thing to note is that if you make any changes inside Unity that would affect the project file (such as new plugins or references) then you will need to manually merge your Visual Studio project file to pick up these changes.

Getting started on Windows Phone with Unity6

Run Time - Running the Generated Windows Phone App

Compiling your project in Visual Studio generates the binary and manifest files required to run as a Windows Phone app. At this point you have a working binary, but it might still need tweaks to accommodate for the hardware and the Windows Phone features that differentiate your games and make it a huge hit. Listed below, find some key platform-specific considerations for tailoring your game.

Hardware Differences

Windows Phone 8 has a detailed minimum hardware spec that all devices must meet; you should expect high-degree of consistency across the devices. In this section we won’t cover every detail on the hardware, but we will highlight some factors that can affect your game play.

Graphics

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 take-away to notice are shader model level 2 and max texture size of 4096.

Displays

Windows phone 8 devices currently come in 4 resolutions: 480x800(WVGA), 768x1280 (WXGA), 720x1280(720p) and 1080x1920(1020p). 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, and Windows Phone will scale these.

Memory

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, see the Windows Phone Porting Tips document for how to extend memory and also how to opt out of low memory device support (not recommended).

Hardware APIs

Accelerometer is available on all phones and directly accessible from Unity APIs. Magnetometer and gyroscope are optional on the hardware on the phone. Compass, Microphone, Location and Camera APIs are all available in 4.3

Getting started on Windows Phone with Unity7

Unity support for Windows Phone is still growing so not all APIs have been ported, there is only a few missing, here are the ones I can think of (list might not be all inclusive):

- 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.

Beyond the port, Integrating with the platform

Once you are done with the basic port for your game, you should enhance your game with some of the platform features that delight Windows Phone users. You will probably also want to add some of the Windows Phone APIs to monetize your game. Such as:

Live Tiles and Push Notifications Monetization including Trial and In App Purchase Support.

More information will be added on these topics.

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 add-ons for Windows Phone are free for Unity basic and even Unity Pro users, the add-ons should be included with the editor.

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

1. Check out the App certification requirements for Windows Phone 2. Become familiar with Windows Phone app product submission process. 3. Make sure you handle properly the Back Button behavior (see Porting tips for

Windows Phone with Unity)4. 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.

5. 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.

Getting started on Windows Phone with Unity8

6. [Optional] Since this might be a new platform for you, we recommend you go through a beta submission. More details at the “Beta testing your app” page , on MSDN

7. 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 referencesUnity’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.

Other white papers and resources in this series include:

Getting started on Windows Phone with Unity Porting tips for Windows Phone with Unity Getting started on Windows Store with Unity Porting tips for Windows Store with Unity Sample Unity Project Github Repository

The Windows Phone SDK samples collection has hundreds of coding samples to accomplish specific tasks. They are all useful, but I recommend you look for the ones that come from the Windows Phone SDK team (they will have a Windows phone logo).

Feedback & Revision history

There is a lot more to cover. Check out the rest of the series and out suggested references. Let us know what missed or you want to hear more about, drop an email to jaimer@microsoft.com.

Revision Date Changes Contributors1.0 11/15/2013 Seeding this conversation

with a big brain dump. Sharing for comments.

Jaime Rodriguez (Microsoft), Keith Patton (Marker Metro), the Marker Metro team.

Getting started on Windows Phone with Unity9