This document provides an overview of getting started developing games for Windows Phone using Unity. It discusses the requirements, design process in Unity, building for Windows Phone, and running the generated app. Key aspects covered include using the Unity editor for Windows Phone, compiling in Visual Studio, differences in hardware and APIs, integrating platform features, and submitting apps to the Windows Phone store.
Getting Started with Unity for Windows Phone Development
1. Getting started on Windows Phone with
Unity
This 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 UnityWindows 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 ................................................ 3
Player Settings .................................................................................................................... 4
Windows Phone project and Visual Studio - Development Flow.......................................... 5
Run Time - Running the Generated Windows Phone App ...................................................... 5
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.............................................................................................................. 7
Feedback & Revision history ............................................................................................... 8
Getting started on Windows Phone with Unity
1
2. Introduction
With the release of Unity 4.3, porting games to Windows Phonehas 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 Phonegame 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 Unity
2
3. Porting Overview
To prepare for a port, you must be familiar with Windows Phoneplatform 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
Tipsdocumentation.
It’s worth noting that you can debug directly into your Unity code from within a generated
Windows Phonesolution using Visual Studio.
Including Windows Phonecode 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
Phoneapplication. 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 Phoneapps, 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.
Compile Time - Building from Unity to target Windows
Phone
Getting started on Windows Phone with Unity
3
4. In order to build you must switch your target platform in the Build Settings window toWindows
Phone8using 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). .
Player Settings
Getting started on Windows Phone with Unity
4
5. After clicking on the Player Settings button, you will see settings that you can configure relating
to the outputted Windows Phonesolution which affect the creation of the Windows Phoneapp
manifest file.
Windows Phoneproject 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 Tipswhite paper, specifically the getting your
app to compile in Unity section, andfor more on how to resolve API related errors during porting.
Once you have resolved anycompile timeerrors, 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 Unity
2. 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 project
2. 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.
Run Time - Running the Generated Windows
PhoneApp
Getting started on Windows Phone with Unity
5
6. Compiling your project in Visual Studio generates the binary and manifest files required to run
as a Windows Phoneapp. 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 Tipsdocument 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
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.
Getting started on Windows Phone with Unity
6
7. 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 addons 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.
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 references
Unity’s Windows Phone 8: Getting Started guide is a must read.
Getting started on Windows Phone with Unity
7
8. 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
1.0
Date
11/15/2013
Changes
Seeding this conversation with a
big braindump. Sharing for
comments.
Getting started on Windows Phone with Unity
Contributors
Jaime Rodriguez
(Microsoft),
Keith Patton
(MarkerMetro), the
MarkerMetro team.
8