This post is part of 3 week series giving current and aspiring game devs the tools, resources, and advice they need to get started building for Windows. Check out the overview of the series to find what you need. For additional resources to build your app check out AppBuilder.
If you are an existing Unity developer, please ensure you check out our current offer here where you can get FREE STUFF and a potential for store promotion .
Porting your game to Windows
Why would you want to do that?Let’s start this off asking the most important question. Why?
As an Indie game developer myself I fully believe in today’s economy, developers should look at building for multiple platforms. There comes a point though where you can feasibly only support so many platforms given your own resources.
Windows Phone 8 is the strong third phone platform globally. With that said, Window Phone is currently growing faster than the phone market, and as of the latest figures is beating iPhone sales in 24 countries including India and Mexico, and is #2 in 10+ countries. There are more than 14 million downloads a day of apps on the phone alone. That’s nothing to shake a stick at. The Lumia 520 512 MB phone has sold more than any other Android phone – EVER. Again, not too shabby!
Windows Store applications run on the Windows 8 platform, not the phone which targets 3000+ different devices from hand held small tablets, larger tablets, laptops of all sizes, and of course desktop systems as well. Some folks new to the platform think this means only tablets, like a Microsoft Surface tablet. That’s not the case. Windows 8 runs on many device types as listed above. Every one of them can run a Windows Store app on it.
There is an ever so slightly different build and submission process for Windows 8 apps (ie Windows Store apps) than Windows Phone even though they share a lot of the same common features. We just announced Universal apps at our //build conference being the first platform to be able to take a single code base and go from phone to tablet to desktop to Xbox. Windows 8 in addition has sold over 200 million licenses. Each of those instances by default have access to the Windows Store on them, the marketplace to download and install applications.
With a fairly easy export between platforms, why not target another large ecosystem that isn’t yet oversaturated with apps? There are over 400K apps between Windows Phone and Windows 8. Not a bad number, but definitely not oversaturated. There’s still plenty of room for you to bring your apps on over and be effective. Don’t take my word for it though:
Pat Toulouse, President and Founder of RatRod Studio
“The process of porting our games to Windows and Windows Phone was very straight forward. Since then, it has helped us extend our reach by generating over 5 million downloads within the past 6 months. And this continues to grow rapidly”.
Magma Mobile’s CEO Nicolas Sorel: “first 1,000,000 downloads in 2 ½ months of being in the Windows Phone Store, and had 1,000,000 additional downloads in the last 30 days.”
So.. what’s required?
- Unity (I recommend the latest version. There are important Windows related changes in every build)
- Developer account to publish to the stores available here
- Windows 8 / 8.1 (Free trial http://technet.microsoft.com/en-us/evalcenter/hh699156.aspx)
- Windows 8 is freely upgradable to Windows 8.1
- If you are on a mac see these links for getting Windows 8 running on it. You can either use boot camp or install it as a virtual machine running inside of OSX. For some common instructions here see
- Visual Studio (Retail or the free Express edition)
- If you have the retail version of Visual Studio 2013, you are potentially all set. You may need the Windows Phone 8 SDK installed however and that is available here
- If you want to dev for Windows Phone 8, here’s the free version
- If you want to dev for Windows Store (Windows 8) here’s free the version
Coming from other platformsThere’s something to be aware of when you’ve been used to working on other platforms. Typically when you run your game on for ex. ios / android, the Mono framework is used. Your app is compiled against that framework as .NET is not natively supported on those platforms. Mono in the case of ios uses AOT (ahead of time) compilation because of ios restrictions preventing JIT (just-in-time) compiled code. As such, your game is developed with Mono which is what the Unity Editor runs, and your game is deployed and runs.
Enter in now .NET. Mono was essentially based off of Microsoft’s .NET. As such most of the api is cross compatible but Windows Phone 8 and Windows 8 share a common kernel between them and support a newer API. Some objects were dropped along the way and new ones added. You’ll find things like Hashtable & ArrayList to be deprecated on these system’s apis. This created a bit of a problem in the past as a lot of Unity C# code referenced these collections. When Unity would call .NET to compile the code, exceptions would be thrown over the missing collections.
Let's get to porting!
The basics of porting are pretty simple:
- Switch platform in Unity
- Set player settings (images, icons, etc)
- Build from Unity which creates a Visual Studio solution
- Open solution in Visual Studio
- Test the project and deploy to devices or local system (Note debug builds are slow, master builds are fastest more on this below)
- Upload to the Windows Store and Windows Phone Store
Switch Platform in UnityExpect on any platform to have some issues because of platform differences or potentially calls you make via plugins on one platform that another platform won’t support. The typical way in Unity code to handle this is to include a preprocessor directive to separate out your code.
When you switch your build settings to target another platform, you cause a variable that represents your platform to be true. For example, if in Unity you set Windows Store Apps to be the current platform by clicking on “Switch Platform”, behind the scenes the value of UNITY_METRO will become true. As is typically a safe bet in Unity, this code you generally run outside of the Unity Editor, hence the second part of the statement: && !UNITY_EDITOR although you surely could test this code out in the editor if the scenario fits.
For a listing of the variable names that you can reference see here
The three important Windows ones (to me) are
|Precompile Constant||True when platform is|
|UNITY_METRO||Windows Store (Windows 8)|
|UNITY_WP8||Windows Phone 8|
|UNITY_WINRT||Either of the above|
#if UNITY_METRO && !UNITY_EDITOR
//Any platform specific code here
If you have platform specific libraries in your /Assets/Plugins folder, then you likely this will be compiled using Mono and must be .NET 3.5 compatible, this is a general Unity rule. If you have any libraries in /Plugins/WP8 or /Plugins/Metro, those will be swapped out at compile time. This is how the Unity plugin system works. For more information on writing a plugin for Unity & Windows Phone see here.
Setting player (platform) settings & building your projectIn Unity click on the Player Settings icon from your Build settings.
Under your player settings there are a few important things to note.
On future builds, Unity will only overwrite the /data folder in the project that was generated. Any changes you make _in the player settings_ after you have already clicked Build in Unity and generated your solution/project, will not be overwritten in the visual studio project. For example, if you build your project from Unity, and then decide later to change the project name in Unity for your Windows Store build (in your player settings), Unity will not overwrite your project it created already. If you haven’t made any custom changes to your Visual Studio project (see my video link below from //build 2014 if you are interested in that) then you could simply delete your build project folder and have Unity recreate it. The other option if you don’t want to remove your project is you manually make the changes in both Unity and in your Visual Studio project.
Windows Store (Win8) Typical Player Settings
- Ensure your project name doesn’t start with a number or an underscore, as this is not a valid app name. You can fix this once your Visual Studio project is created though in your package.appxmanifest file if by chance you’ve missed this. You’ll actually see a red X when you open that file to show you where you need to change it.
- There are quite a few settings you can have for a Windows Store application. Most of the defaults will serve you well but you’ll quickly notice under Publishing Settings there are many images you can set. Why so many images? Well – you can have an image show up as a small icon in your Windows program list (30x30), a larger icon if pinned to the start screen (150x150 for a medium tile, 310x150 for a wide tile) , a splash screen (620x300), an image to show in the Windows Store (50x50). Unity will show you the sizes required. I wrote a basic utility to resize a square image and create several output images by simply dragging and dropping. You can see a demo of that in the //build video linked at the bottom of this post and the url is http://aka.ms/wsip. There are also more icon resources listed at the bottom.
Windows Phone Typical Player Settings
- As of now, you cannot set the Windows Phone icon in Unity. You must do this in your Visual Studio solution inside of the /Properties/WMAppManifest.xml file.
- You can force the orientation in Unity by setting Default Orientation as shown here
Creating the build
You’ll notice in the build settings there are several build options. Which one to choose?With Visual Studio 2013, you develop for Windows 8.1. Windows 8 folks cannot run a Windows 8.1 app. To target both you can just compile for Windows 8. not everyone has upgraded yet to it’s not a bad idea to target both.
You can compile but are limited in some modifications of a Windows 8 project in Visual Studio 2013. Only a Windows 8.1 project in VS 2013 has no restrictions. However Visual Studio will prompt you to retarget a Windows 8 project to Windows 8.1 when you first open it or you can right click on your project and select “Retarget to Windows 8.1” in Visual Studio as well. You may ask ‘then what can I manage a Windows 8 (not 8.1) project with?” and the answer is Visual Studio 2012-> Windows 8 and Visual Studio 2013->Windows 8.1, although as I mentioned you can compile and make some changes to a Windows 8 project in Visual Studio 2013.
Once you have set your player settings, simply click the build button in the build settings window. You’ll be prompted for a folder to select. I prefer to typically create a folder called “Builds” that will contain all of my platform build projects and I can then source code control each version relatively easily. Unity will then create a Visual Studio solution and a project file.
A Visual Studio solution file is not much more than a listing of one or more projects your solution will contain. For example, I can have a solution that contains projects for Windows 8, Windows Phone 8, XBox, and other code projects I want to use, it surely isn’t limited to just one project at a time that you can have open in Visual Studio.
Open project in Visual StudioNow that the project has been created, Unity will open the folder in Explorer that contains your build’s folder. Go into your build folder and look for the solution file and open it up. Visual Studio should open up. If you get prompted for the version, ensure you select which version you are trying to open it in – Visual Studio Express for Windows Phone if you are trying to use that build of course.
Compile and Test the projectThe first thing to notice when Visual Studio opens if what type of build you are currently going to create. The default for both Windows Store and Windows Phone are “Debug” builds. There are actually three build types, three platform (processor) types, and you may or may not use every one. On top of that there are several different places you can run your build – locally, on a device, on a simulator, on an emulator, even on a remote networked machine. Let’s see what all the options are used for:
Debug – Contains un-optimized code full of debug symbols and typically has a much slower frame rate, on the flip side it contains potentially crucial debugging information. If your game seems to run slow, the first thing is to always note you may be testing a debug build. I’ve seen this countless times and once you change to a release or master build, the problem disappears.
Release – This build contains optimized code but still supports the Unity Profiler so there is still a performance hit, although significantly different. Contrary to typical .NET applications, this is NOT the build you will use to send to the stores.
Master – This is the completely optimized game. There is no profiler support nor is there debug information. This is the build to send to the store. There can be only one
Choosing these will change which files get included into your build and how your build is compiled. If you select ARM, the Unity native code player files for ARM are included in the build. If you select x86, the Unity native code player files for x86 are included.
ARM – Only choose this if you are creating a build to run on a system that is ARM based. Let’s talk about both project types that use this for a moment. It’s very important to understand the use cases.
Windows Store projects – You only choose ARM in two cases. First is if you are your builds to upload to the store for a small subset of Windows 8 devices – those running on ARM. Most Windows 8 devices run x86 processors so you typically want the x86 build. You should actually create both builds to send to the store – ARM & x86. ARM is the default build type when you first open your project. Note that for local testing you will _always_ choose x86 – not x64, not ARM unless you are deploying right then to a tablet for testing that you know is an ARM based tablet (there are only a few models that are ARM based). The first time you load your project, change this setting to x86 so you can test locally.x86 – You will choose this when
Windows Phone 8 projects– You want an ARM build ONLY if you are creating a build right now to upload to the store or about to deploy to a phone for testing. If you are wanting to only run it in the emulator instead, you would actually want an x86 build not an ARM build.
Windows Store projects – You want to create a build to run on your development system, submit a build to the store that will run on the vast majority of Windows 8 devices (you should create a build for ARM and also x86 for that situation to make sure you can deploy to every single Windows 8 device type)x64 – As of this point, you will not use this platform type – at all. Unity does not make a 64 bit player for Windows phone or Windows Store.
Windows Phone 8 projects – Only when you are building to run in the emulator. There are no other times you would select x86 for a Windows Phone build.
Check out the //build video at the end for how you can debug Unity code in Visual Studio. You can’t do this in development without a third party plugin (UnityVS – well worth it - available here) but you can do this after you’ve built your solution from Unity out to Visual Studio by adding another project to your solution. The file to add is Assembly-CSharp-vs.csproj and this is a file that Unity creates for you.
Upload to the Windows Store and Windows Phone StoreThese steps are pretty easy, and it's the last steps to get your game in even more hands. There are specific certification requirements for each store and you can help meet those requirements by reading the following links but also running the test kits on your application.
Windows StoreSubmitting your app
App Submission Checklist
The process in short is build your package, test it, submit it.
Some things to be aware of:
- You should support touch & keyboard/mouse unless you note otherwise as noted in section 6.13.4
- 6.13.4 If your app doesn’t fully support touch input and fully support keyboard and mouse input, you must disclose that in the description elements of the app
Go to the following menu. In Visual Studio Express use the root "Store" menu instead of the Project menu as shown here for Visual Studio Ultimate Edition. If this menu doesn't have the items active, ensure you have your current project highlighted (and file in it) inside of the Solution Explorer window of Visual Studio. If you have the Solution file itself highlighted (the first item in the tree typically on the right) the menu options won't be active. You will be prompted then to login with your Microsoft account (see requirements section up top for a link to register for your dev center account). This will query the developer center for your existing apps and also allow you to specify a name for an app you can reserve for up to a year before you publish.
Note the opened folder below and the two .appxupload files. These are the files that will need to be uploaded to the store.
You will also need screenshots to send to the store. These are accessible in the Project->Store->Capture Screenshots menu item. This will launch the Simulator on your local machine so you can grab the screenshots. Note that this will change your project startup location from "Local Machine" to "Simulator". If you want to continue to test locally, make sure you change this back to Local Machine.
You are all ready to upload your files. Go to Project->Store->Upload App Packages and you can go through each step. For more details on that process see Submitting your app.
Windows Phone Store
Make sure you have specified an icon outside of the default Unity icon. This is in the WMAppManifest.xml file as shown below
Open the folder your project is in (you can right click on your project and select "Open in file explorer"). Once the folder opens simply type .xap in the search window in the upper right hand corner. This will search your folder for the .xap file you need to upload. Note that you only need the ARM version, NOT the x86 as that was just for the emulator.
Go to http://dev.windowsphone.com and click submit to begin the process, this is a shorter process than the Windows Store. When prompted, you'll upload the file noted above.
That's all there is to it! If you have any questions please contact me at microsoft.com with the first part intentionally separated of my email address of adamt :) Enjoy!
That's all there is to it! If you have any questions please contact me at microsoft.com with the first part intentionally separated of my email address of adamt :) Enjoy!
Unity’s site for Windows
Unity & Windows Porting Guidance
//build 2014 conference video - Building your first Windows game with Unity
Choosing your app images
Guidelines for tlies and badges