Getting started on Windows Store with Unity
This document provides an overview of the process for porting a Unity game to the Windows Store platform. It discusses requirements, design considerations during development in Unity, the build process to target Windows Store, runtime differences to test for, and submitting to the Windows Store. The document is intended to give high-level guidance on porting to Windows Store and points to additional resources for further details.
How to Troubleshoot Apps for the Modern Connected Worker
Getting started windows store unity
1. Getting started on Windows Store 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 Unity Windows Development
Forum: http://forum.unity3d.com/forums/50-Windows-Development
Contents
Introduction ................................................................................................................................ 1
Requirements to write a Windows Store game with Unity ....................................................... 2
Porting Overview........................................................................................................................ 2
Design Time – The Unity Editor Experience ........................................................................... 3
Including Windows Store code in your Unity project ............................................................ 3
Compile Time - Building from Unity to target Windows Store .................................................. 3
Choosing Store App Type ................................................................................................... 4
Choosing SDK Type ........................................................................................................... 5
Player Settings and .Net Core Compilation Override ........................................................... 5
Windows Store project and Visual Studio- Development Flow ............................................ 6
Run Time - Running the Generated Windows Store App ........................................................ 7
Hardware Differences ......................................................................................................... 7
Graphics ............................................................................................................................. 8
Displays .............................................................................................................................. 8
Memory ............................................................................................................................... 8
Mouse, Keyboard and Controller Support ........................................................................... 8
Orientation Support and Window resizing ........................................................................... 9
Beyond the port, Integrating with the platform ..................................................................... 9
Submitting to the store ..............................................................................................................10
Windows App Certification Kit ...................................................................................................10
Other useful references.............................................................................................................11
Feedback & Revision history ..............................................................................................11
Introduction
Getting started on Windows Store with Unity
1
2. With the release of Unity 4.3, porting games to Windows Store 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 Store. 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 Store game with
Unity
To develop, compile and submit a Unity game to the Windows store, 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.
Visual Studio.You can use any Visual Studio SKU, including the free Visual Studio
Express.
To target Windows 8.1, you will need Visual Studio 2013; to target Windows 8, you can
use Visual Studio 2012. These two editions can be installed side-by-side on the same
machine.
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 are targeting Windows 8.1, you must develop in Windows 8.1.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 and over the
air.
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 Store developer account. This will be needed submit your game to the
Windows store. 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 Phone (one registration submits to both stores). Registration is $19 for
individuals.
Windows 8.x test devices. You can develop on any device running Windows 8.x.The
simulator can simulate multi-touch and different display resolutions; but, we do
recommend you test on a real device with touch and ideally running Windows RT (ARM
architecture). A Surface RT or Surface 2device would be ideal for this kind of testing.
Porting Overview
Getting started on Windows Store with Unity
2
3. To prepare for a port, you must be familiar with Windows Store platform specific nuances in the
following areas:
Design Time– The Unity Editor Experience
Build Time– Building from Unity Editor to produce a Windows Store app
Run Time– Running the Windows Store App
Design Time – The Unity Editor Experience
To port your game to Windows Store, you will still be using the Unity Editor. 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 to generate your Windows Store
project that you will notice the difference: Unity will use the .NET compiler to build your game
and it will compile using the .NET core profile that targets Windows Store. .NET core is a subset
of .NET, so you might run into some compiler errors with some APIs that are in Mono and are
not in .NET Core Profile. 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 ourPorting tips for Windows Store with Unity documentation.
A positive corollary to this switch in compiler is that you can debug directly into your Unity code
from within a generated Windows Store solution using Visual Studio.
Another design-time difference to watch out for is the use of shaders and graphics features that
are hardware dependent; when you are in the editor, you are running on Windows desktop and
this follows different policies and is using your desktop’s hardware capabilities, which might be
more than the capabilities on Windows RT devices. To get a high fidelity design-time
experience, use Unity’s Graphics Emulation feature (located in the Edit menu), and select the
appropriate platform you want to target.
Including Windows Store code in your Unity project
If including script files that will run inside the Unity editor, use #if (UNITY_METRO &&
!UNITY_EDITOR) pre-processor directives to refer to code that should not run when in the
editor. This will ensure that the code will only run within the generated actual Windows Store
application. The !UNITY_EDITOR deals with the scenario where you are running in the editor
with the platform switched to Windows Store via File > Build Settings.Note that code running in
the editor can’t reference Windows Runtime (WinRT) APIs, since the editor will not know how to
resolve these.
WinRT APIs include most of the functionality to do integration with Windows such as access to
file system, implementing contracts and live tiles; you will still be able to reference these APIs
from Unity plugins, just not directly within editor compiled code.
Compile Time - Building from Unity to target Windows
Store
Getting started on Windows Store with Unity
3
4. In order to build you must switch your target platform in the Build Settings window toWindows
Store Apps using File > Build Settings
You will see a few new options that you might not recognize, here are the details on these new
choices:
Choosing Store App Type
You will notice that you have a Type dropdown, where you can select between Direct3D11 and
XAML and you can choose a target language C# or C++. TheXAMLoption is recommended
because that will give you the XAML UI stack for implementing splash screen, settings and
other recommended UI components for a great game.Since Direct3D and C++ are slightly
lower-level, this configuration will offer maximum performance but at the expense of some of the
UI stack integration features.
For more on these choices, see these references:
Developing Windows Store Games blog post that outlines the DirectX platform features.
Unlocking the Power of DirectX in Apps that use XAML video that explains how DirectX
and XAML can seamlessly compose a unified UI experience.
Getting started on Windows Store with Unity
4
5. Choosing SDK Type
In Unity 4.3 you have the option of generating an 8.0 or 8.1 store app.
Since Windows 8.1 is now released, it would be recommended that you choose the latest
version for all new games. However, as of this writing (early Nov 2013), there is still a good
percentage of Windows users running Windows 8.0, so consider targeting both. To target both
you can either:
Build a Windows 8.0 game without taking advantage of new 8.1 features. You will submit
this game to the store as targeting 8.0, and users running 8.0 or 8.1 will be able to install
it and run it. Or,
Build your game once and then target two run-times: 8.0 and 8.1. All your game play will
be the same, so the delta on work is marginal; you would just be coding for the new 8.1
features you want to use. When you submit to the store, you will submit both games at
once, and users on either version of the OS will only see the respective version for their
OS.
For more on this see here:
Windows Store – What’s
new or update in 8.1
Migrating Windows Store
apps to Windows 8.1
Player Settings and .Net
Core Compilation
Override
On the Player Settingsoption, you
will findsettings to configure the
generated Windows Store
solution. These settings will go on
the manifest for your file. Here,
you will configure the app name,
default icons, capabilities, etc.
One important setting to
understand is the Compilation
Overrides drop down which
defaults to “Use Net Core”.
Effectively this ensures that at
compile time, all scripts in Unity
(excluding any within the /Plugins
folder) will be compiled against
the.Net core profile. This is the
recommended setting if you are
using C#, if you are using
Getting started on Windows Store with Unity
5
6. UnityScript (or Boo), you can’t select use .NET core; Unity will use the mono compiler but still
generate an assembly that will pass certification in the Windows Store.
This generated assembly still can’t reference the missing types from Mono to .NET core; you
will see the same missing types, the Mono compiler will just throw errors at compile-time.
It should be noted that code within the plugins folder and any binaries referenced in the plugins
folder are notvalidated by this compilation override, so you may still have issues once the
solution is generated, both to run and validate the application for store (more on this later).
To know if a third party plugin you are referencing is compatible with Windows Store you can
use the scan tool from Xamarin, available for free, online at http://scan.xamarin.com.
Windows Store project and Visual Studio- Development Flow
When you target Windows Store, you will likely run into a few of the issues we mentioned
above, please refer to the Windows Store Porting Techniqueswhite paper, specifically the
getting your app to compile in Unity section,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 Unity
2. Compile in Visual Studio to create final binary and Windows Store 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.
Getting started on Windows Store with Unity
6
7. 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 Store
App
Compiling your project in Visual Studio generates the binary and manifest files required to run
as a Windows Store app. At this point you have a working binary, but it might still need tweaks
to accommodate for the hardware and the Windows 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 8.x targets a very large end-user base with a myriad of devices. Microsoft does a bit of
work in the platform to abstract hardware differences, but there is still a few details to consider
to define the right strategy and audience for your game. It helps to think of Windows as a
unified API targeting three distinct types of devices: tablets, laptops and desktops.
The tablets are often designed to maximize battery life. They will have multi-touch and be lighter
weight (keyboard will be optional); often you will see high-density displays in these tablets. Most
of these devices will have sensors (accelerometer, compass and a camera).
The laptops are modern, you will often see multi-touch, sensors; the deltas from tablet form
factor will be the attached keyboard, mouse or track pad, larger displays (in size, not resolution)
and often a slightly more powerful CPU, GPU and a bit more memory.
Desktops have the traditional form factor, with high resolution monitors, input coming from
mouse, keyboard and/or an attached controller.
Some of the tablets devices will be running on Windows RT (ARM architecture), but on the
software and the game play, the differences on targeting RT are very minor, as such we will not
Getting started on Windows Store with Unity
7
8. get deep into a Windows RT details. When you think of Windows RT, assume it is the same
platform, on slightly less powerful hardware and with the requirement that you use a remote
debugger; that should cover most of your architecture differences.
Let’s then focus on the hardware and form-differences, across the board.
Graphics
You will see a very wide-range of graphics capabilities in Windows.
Since you are running on Direct3D, the myriad of video cards will be neatly grouped into welldefined feature levels that guarantee you a specific set of graphics capabilities.
Refer to the feature level documentation to get every detail on the different levels.
We recommend you target the broadest set of feature levels, so going down to feature level 9_1
might still be a good option; that is the hardware you will see in first generation Surface RT
tablets. You can find more details on the graphics APIs on the porting documents.
Displays
After graphics cards capabilities, it is also important that you deal with pixel densities. A
common configuration on Windows is a high resolution display –such as 1080p- on a tablet
device that is 12 to 13”. The devices density should affect your touch target sizes. Unity will give
your game the native resolution of the device, and the WinRT APIs will have recommended
system-defined scale factors that you will need to keep in mind as you use assets outside of
your gameplay - such as icons, or XAML UI used for settings, dialogs, etc. You should get more
familiar with the guidelines for scaling to pixel density in Windows Store apps, and will also find
details on dealing with high-density displays on the porting guide.
Memory
Memory and disk storage will likely not be a factor for your game; you are running on systems
with >1GB RAM, and the system takes care of managing the resources so that most resources
are going to the app (or apps) in the foreground. On storage, your only limitation will be the
deployment size. The Windows 8 store allows you to deploy packages up to 2 GB. Windows 8.1
increases this limit to 8GB.
Mouse, Keyboard and Controller Support
Games ported from other mobile platforms such as iOS/Android are focused on touchscenarios. Besides touch, Windows 8 supports mouse, keyboard and it is a certification
requirement that all games be playable using mouse/keyboard.
Consider adding mouse/keyboard equivalents for all touch input. For example:
Properly localized text for scenarios where touch only “tap” or “swipe” messaging is
included on screen. For example, maybe replace “Tap” with “Tap/Click”.
Alternatives to accelerometer and sensors; for example, using arrow keys or wasd
Getting started on Windows Store with Unity
8
9. Ensure than on-screen keyboards for input (if your game has them) also work with a
hardware keyboard.
To ensure your game works well, fully test your game on a laptop or desktop computer without
touch support; make sure you can get to all screens and can perform all critical input. If you still
have a game that is designed and best experienced with touch, consider adding this information
in your application’s description page when you submit to the store; this way users who don’t
have touch can decide if they want to install; this type of proactive communication leads to less
bad reviews, and more satisfied users .
Another alternative, if your game is very touch centric is to provide gamepad controller support;
this should be optional, but it can be a great differentiator and in some cases it makes touchcentric games easier and more fun to play. Unity has controller support in their APIs.
Orientation Support and Window resizing
The Windows device ecosystem very broad when it comes do display size. Most modern
tablets will have a 16:9 aspect ratio and a resolution > 1366x768, but you will also see
displayswith 4:3 aspect ratios and in the newest Windows devices you can see smaller portrait
devices. Also, Windows has a lot of flexibility for users to resize their Windows to do multitasking showing two or more active apps at a time on the screen, so you have to be creative
and decide how your game will react to different screen sizes and resolutions. Here are the
most important scenarios to consider:
If you are targeting Windows 8, you will run into “snapped mode”. This is when a user
snaps your application to a side of the screen so they can have multiple apps at a time;
in snapped mode, your game will be 320 pixels wide, and take the full height of the
screen. When snapped you can just pause your game, show a meaningful teaser for the
user to resume gameplay.
When you are not snapped, your game is taking all other available space in the screen;
this is guaranteed to be more than 1024 pixels wide (in landscape orientation).
If you are targeting Windows 8.1, the smallest 320 pixels becomes optional. The default
minimum width you should support is 500 pixels – you can again choose to just pause
your game at this width. As you define when to pause your game for minimum size, keep
in mind that Windows 8.1 allows dynamic resizing, so your game might be displayed at
any width over 500 pixels, you get to decide at what width is your game playable. On the
sizes where you pause your game, keep it as functional as possible. You can display
scores, teasers, tips, etc. take advantage of the screen real-estate.
Portrait orientation should also play a factor. Try to support portrait orientations, but do not
assume that all devices will have sensors and support portrait. If you have a portrait game, do
your best to take advantage of the landscape orientation and remember that most Windows
devices will be wide aspect ratios.
Beyond the port, Integrating with the platform
Getting started on Windows Store with Unity
9
10. 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 Store users. You will probably also want to
add some of the Windows Store APIs to monetize your game. Such as:
Live Tiles and Push Notifications
Monetization including Trial and In App Purchase Support.
Windows 8 Charms
More information will be added on these topics in a later document.
Submitting to the store
To submit to the store, you will need your Windows Store developer account and a licensed
version of Unity. The trial version of Unity Pro, 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.
Remember that the Unity add-ons to target Windows are free; you can also use the free version
of Unity basic to submit to the store, it just has to be registered.
When you are ready to submit to the store, follow these steps. Especially #3.
1. Check out the App certification requirements for Windows Store and read through the
most common reasons for certification failures so you can avoid these.
2. Become familiar with Windows Store Apps product submission process.
3. Run your app through WACK to ensure your game is fit for certification. See below for
details on the WACK tool.
4. Submit your master configuration. Unity 4.3 will create a debug, release, and master
configuration for your visual Studio project. Make sure you submit the master, not the
release one.
Windows App Certification Kit
The Windows App Certification Kit (WACK) is a static analysis tool that will check the
performance and suitability of your app for store certification.
WACK will:
Check binary dependencies to ensure that you are not calling any unsupported APIs.
This is important because there may be dependencies (such as plugins and other binary
references) which will fail if your binaries are referencing unsupported or private APIs.
Test performance around startup and suspend/resume for your app. For this test, we
highly recommend you test on a Windows RT device. If you do not have one available,
test on the lowest-end x86 machines that you can find. Windows Store does not have a
beta submission process, but the requirements to deploy to a PC are just a Microsoft
account, so you can share binaries with your friends and have themrun the WACK test
for you.
Getting started on Windows Store with Unity
10
11. Validate assets to make sure you meet the minimum required icons (or tiles) for
submission.
When porting a game it’s very important to run this tool against the master build of your
Windows Store app. You should run this tool often, don’t wait until the end of your porting
project to try it.
Other useful references
Unity’s Windows Store: Getting Started guide is a must read.
The getting started with Windows Store guidewill walk you through downloading the tools,
registering your phone for development (aka unlocking the phone) and writing a basic app that
walks you through the Visual studio project structure.
The Windows Store app samples collection has hundreds of coding samples to accomplish
specific tasks.
This “Developing Windows Store games” has very useful design considerations and links for
game developers. It is not Unity specific but all advise applies to Unity games.
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
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 brain dump. Sharing for
comments.
Getting started on Windows Store with Unity
Contributors
Jaime Rodriguez
(Microsoft),
Keith Patton
(MarkerMetro), the
MarkerMetro team.
11