Saturday, April 5, 2014

Why and how to Port your Unity game to Windows and Windows Phone


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
We have an awesome program for startups called BizSpark. It gives startups free software including Windows, Office, Visual Studio, and access to the Windows / Windows Phone Store - for free. Check it out at www.microsoft.com/bizspark. Note that you can download 90 day trials of Windows 8 as well to do testing on if you need a quick way to get up and running on Windows.

Coming from other platforms

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

As of Unity 4.3, UnityScript (Javascript) is now supported as it previously didn’t created compliant .NET code for WP8 and W8, but it does now. As of Unity 4.3.3 however, Unity has now added in a WinRtLegacy.dll into your builds. This includes a lot of the missing classes that caused issues before in your builds and UnityScript is supported as well. In other words, the support is now awesome to easily target Window Phone and Windows Store.

Let's get to porting!

unity to windows
The basics of porting are pretty simple:
  1. Switch platform in Unity
  2. Set player settings (images, icons, etc)
  3. Build from Unity which creates a Visual Studio solution
  4. Open solution in Visual Studio
  5. Test the project and deploy to devices or local system (Note debug builds are slow, master builds are fastest more on this below)
  6. Upload to the Windows Store and Windows Phone Store

Switch Platform in Unity

Expect 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
Windows Store Build

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
An example of usage is:

#if UNITY_METRO && !UNITY_EDITOR
     //Any platform specific code here
#endif

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 project

In Unity click on the Player Settings icon from your Build settings.
Player 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

windows store icon
  • If you need to access the internet OR profile your app (which requires network access), you will need to check off the Internet Client capability as your app cannot communicate with a network without it. If you check this off, you MUST set a privacy policy URL when you are submitting your app to the store or you will get rejected. If your application does not communication with the Internet, I’d recommend ensuring this isn’t checked off (and it is not set by default) so you won’t need a privacy policy url. Note that the store submission process won’t force you to set a url during your submission process, so it’s something you need to know to add if you require access to the internet from your application directly. If you use a third party plugin that uses Internet access for ads or leaderboards, then you will require this capability.
  image
  • 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.
player images windows store

Windows Phone Typical Player Settings

windows phone icon
  • 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
Orientation

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 Studio

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

image


Compile and Test the project

The 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:

Build Types

image
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 Smile
Platform Types

image
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.
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.
x86 – You will choose this when
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)
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.
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.

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 Store

These 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 Store

Submitting 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
  • If your application communicates with the Internet in any way, even through a third party ad sdk, you will need to specify a privacy policy url when you are submitting your app to the store. This will not be required on submission, so note you must add it. A privacy policy can easily be generated and there are easy ways to set this up for free. See Jim's great post here.

The process

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.





Specify a build location for your files. Ensure you check of BOTH x86 and ARM as is shown below. This is because you should support both platform types.


Once done, you can now test your application. Click on Launch Windows App Certification Kit. While passing this doesn't guarantee approval, it does run a lot of the same checks that are run on the store side. Also click on the "Output Location" link shown below to open the folder with the files you will need to upload to the store. You can run the test kit any time by searching for "cert" on your systems (press the windows key and type cert on the start screen).


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


This process is a little shorter. You can run the tests for the phone project first via the Project->Open Store Test Kit menu option.  First you'll want to create your app package by ensuring you have the proper build settings. Once that is set simply go to the Build->Build Solution menu.



 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!
Resources:
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

6 comments:

  1. Thanks for your ideas. You can also find the details on Affity Solutions, at the web development nagpur. The main object of the Affity Solutions is to provide quality web services and is among the few software development company in Nagpur.

    ReplyDelete
  2. Nice info, Ive been making a game in unity for a while, lets give this a try!
    webdesign agentur

    ReplyDelete
  3. Well done, indeed! We've never worked with Unity but you can see how we import our mobile games in custom software development company. Glad to share with you our experience.

    ReplyDelete
  4. IT Staff outsourcing services First of all, it is a risk of information leak. Each company which performs outsourcing IT services guarantees confidentiality, thus this risk is minimal but still it happens to be. Another unpleasant probable situation is a bankruptcy of the chosen company which provides you with software outsourcing services, thus you will have to look for another one and to start all over again.

    ReplyDelete
  5. Great articles here in your blog. Thanks for posting. We love it here in website development Philippines.

    ReplyDelete
  6. We offer cross platform mobile solutions including SIP dialer to Windows Application Development Company worldwide clients. We specialize in the development of business apps for iOS, Android, Windows, and SmartPhones.

    ReplyDelete