Interested in porting your Cocos2d-x game to Windows 8 and Windows Phone? If you have a Cocos2d-x game written in C++, this article is for you. Windows 8 and Windows Phone are a huge and fast growing opportunity, and you will be surprised by how incredibly easy it is to port your existing Cocos2d-x games to these platforms.
Windows Store apps work on Windows for Windows 8 devices, such as Microsoft Surface, Dell Venue and thousands of other versatile devices. Windows Phone apps work on phones such as Nokia Lumia.
Cocos2d-x is a very popular and flexible game engine that is supported on a number of platforms including iOS, Android, Windows (Win32). It is particularly suitable for writing 2D games using sprites, animation, GUI controls, and audio, and has support for Physics engines like Box2D and Chipmunk.
Cosos2d-x for Windows 8 and Windows Phone have the same set of APIs as Cosos2d-x for iOS or Android. This makes porting the game very easy. Often, a game can be ported in hours.
Cocos2d-x is released under an MIT license. While it uses OpenGL on other platforms, on Windows Phone, it uses DirectX, but that is completely transparent to you as a game developer. The APIs hide the differences in the implementations. While the original Cocos2d-x development for Windows 8 and Windows Phone 8 was on different branches of code, the code base is now merged and you can use the master branch for porting.
In this article we will demonstrate how to port an existing Cocos2d-x game written in C++ with step by step instructions. We will cover important aspects to watch for and also provide some tips. We have also included additional resources and listed differences between Windows 8 and Windows Phone implementations.
We will use Parkour, which is a simple game that uses gestures to control the main character. We will show you how to setup your development environment to deploy the game on Windows 8 and Windows phone devices.
Before we begin, let us set up Visual Studio for developing the game. We will use Visual Studio Express editions for porting the game. Visual Studio Express editions are free to download and is a great way to begin developing for Windows 8 and Windows Phone. Visual Studio comparison guide can help if you are considering another edition for your project.
Download Visual Studio Express 2013 for Windows and Visual Studio Express 2012 for Windows Phone from Visual Studio Express site. The pre-requisites for Visual Studio Express 2013 include Windows 8.1. For Windows Phone emulation to work on the PC, you need Windows 8 Pro with a processor with SLAT support. If you are running Windows 8, you can upgrade to Windows 8.1 for free from the Windows Store. The Visual Studio express editions can be installed side by side with other versions of Visual Studio. Look at the pre-requisites carefully before installing these tools.
The installation for Visual Studio is quite simple. When you run Visual Studio for the first time, it will prompt you to obtain a developer license. You need to get a developer license for each machine on which you want to run the app.
You should clone Cocos2d-x distribution on your development machine. Use the following commands to do so:
C:\>git clone https://github.com/cocos2d/cocos2d-x.git
C:\cocos2d-x>git checkout master
C:\cocos2d-x>git submodule init
C:\cocos2d-x>git submodule update
After these commands have completed, you will have a clone of Cocos2d-x master branch on your desktop.
If you using Github application on your Windows machine, visit http://github.com/cocos2d/cocos2d-x. Click Clone in Desktop.
Download or clone the sample Cocos2d-x C++ application from https://github.com/iTyran/SK_Parkour. You can use command line git commands or the Github application to do so.
C:\temp>git clone https://github.com/itran/sk_parkour
Before we begin porting the application, we need to create a Cocos2d-x project. Cocos2d-x comes with a project creation tool. You will need Python to run the project creation tool. Install python from http://www.python.org if needed.
C:\cocos2d-x\tools\project-creator>python create_project.py -project parkour -package com.mycompany.parkour -language cpp
proj.ios : Done!
proj.android : Done!
proj.win32 : Done!
proj.winrt : Done!
proj.wp8 : Done!
proj.mac : Done!
proj.blackberry : Done!
proj.linux : Done!
proj.marmalade : Done!
proj.tizen : Done!
proj.wp8-xaml : Done!
New project has been created in this path: C:\cocos2d-x\tools\project-creator/..
This creates a skeleton project structure that can be used for developing multi-platform applications. The directories for the project are organized as follows:
Directory of C:\cocos2d-x\projects\parkour
03/24/2014 01:55 PM <DIR> .
03/24/2014 01:55 PM <DIR> ..
03/24/2014 01:55 PM <DIR> Classes
03/24/2014 01:55 PM <DIR> proj.android
03/24/2014 01:55 PM <DIR> proj.blackberry
03/24/2014 02:47 PM <DIR> proj.ios
03/24/2014 01:55 PM <DIR> proj.linux
03/24/2014 02:47 PM <DIR> proj.mac
03/24/2014 02:47 PM <DIR> proj.marmalade
03/24/2014 01:55 PM <DIR> proj.tizen
03/24/2014 02:47 PM <DIR> proj.win32
03/24/2014 02:47 PM <DIR> proj.winrt
03/24/2014 02:47 PM <DIR> proj.wp8
03/24/2014 02:47 PM <DIR> proj.wp8-xaml
03/24/2014 01:55 PM <DIR> Resources
Apart from various platform specific directories, the two directories of interest are Classes and Resources. From their names it is clear that Classes should hold our game classes and resources should hold various game resources such as images, audio files and fonts.
In fact, the project creator tool populates the classes with “Hello World”, a very simple game that we can compile and run as is. Start Visual Studio Express 2013 for Windows and click File -> Open project.. and navigate to c:\cocos2d-x\projects\parkour\proj.winrt and select parkour_2013.sln Microsoft Visual Studio Solution file.
After Visual Studio has opened the project, click the Local Machine button with the green triangle or Debug > Start Debugging (or Start Without Debugging).
After Visual Studio builds the files that are out of date, you should have the application running in Windows 8 mode.
Now that we are able to run simple application on Windows 8, we are ready to port our target application.
We will copy classes from the directory in which we downloaded SK_Parkour application to the newly created Parkour Classes directory.
C:\cocos2d-x>cd tools\projects\parkour>xcopy \temp\sk_parkour\classes
C:\cocos2d-x\projects\parkour>xcopy C:\temp\SK_Parkour\projects\ParkourCPP\Classes Classes /Y /s
26 File(s) copied
We will copy resources from SK_Parkour Resources subdirectory to the newly created Parkour Resources directory.
C:\cocos2d-x\projects\parkour>xcopy C:\temp\SK_Parkour\projects\ParkourCPP\Resources Resources /Y /s
26 File(s) copied
We will add newly copied C++ files from Classes directory to the project. In Visual Studio, right click on Classes folder and then click Add > Existing Item..
Select all cpp and h files from c:\cocos2d-x\projects\parkour\Classes and click Add.
Execute the application by selecting Debug > Run.
Now that we have ported the game to Windows 8, let us see what it takes to port the game to Windows Phone.
Start Visual Studio Express 2012 for Windows Phone and open parkour.sln, the Visual Studio solution file contained in c:\Cocos2d-x\projects\parkour\proj.wp8-xaml. Do not use proj.wp8 project which is being deprecated.
Apart from various library projects such as CocosDenshion, libChipmunk, there are two application related projects, namely, parkour and parkourComponent. The former is a C# project which is used to provide the primary application framework. The latter is a C++ project and includes the application files.
Add all sources to the C++ project. Right click on the Classes folder in the parkourComponent project. Click Add followed by Existing Item. Navigate to c:\cocos2d-x\projects\parkour\classes directory, select all CPP and h files and click OK.
We have already copied all resource files to c:\cocos2d-x\projects\parkour\resources directory. Otherwise, you will need to remember to copy resources from the original application to the resources directory.
There are two changes needed to make the application run on Windows Phone. Windows Phone only supports WAV audio files and not the MP3 files which are used in this application. We need to add corresponding WAV files for Windows phone project.
You can use a free, open-source software like Audacity to convert the MP3 files to WAV files. A number of online solutions also provide audio format conversion. Convert the original MP3 filea and add the converted WAV files to Resources directory at c:\cocos2d-x\projects\parkour\resources.
Cocos2d-x for Windows Phone is designed to not load .MP3 files but instead load corresponding .WAV files. For example, if it encounters a command to load or play “jump.mp3”, it will look for “jump.wav” file and load it instead. This will allow you to port the application without making any changes.
Alternately, you can modify the code so that it uses WAV files on Windows Phone app. For example, in MainScene.cpp, use the following code so that it uses WAV files on Windows Phone whereas MP3 files on other platforms.
#if CC_TARGET_PLATFORM == CC_PLATFORM_WP8
Similarly, modify the code in runner.cpp, playscene.cpp files to use WAV files.
#if CC_TARGET_PLATFORM == CC_PLATFORM_WP8
The application uses Helvetica true type font. However, Helvetica is not among the fonts supported on Windows Phone. A font that is not available on the system must be included in the assembly as a resource. As a result, you can add necessary font, as a ttf file, to Resources\fonts directory or use a different font available on Windows Phone. For this project, we will use Arial font for our Windows Phone project.
Modify the code in the following way to use Arial font on Windows Phone 8 whereas Helvetica on other platforms. Make similar changes in StatusLayer.cpp, CCLabelTTF.cpp, and CCControlButton.cpp.
#if CC_TARGET_PLATFORM == CC_PLATFORM_WP8
this->labelCoin = CCLabelTTF::create("Coins:0", "Arial", 25);
this->labelCoin = CCLabelTTF::create("Coins:0", "Helvetica", 25);
Once you have completed these code changes, click Debug > Run without Debugging to run the application in the Windows Phone emulator.
- Where do I add my game logic in the Windows Phone project? (or How is the Windows Phone solution organized? )
The Windows Phone Cocos2d-x solution created by the project creator tool includes two different projects - a C# project and a C++ project. For a project called ‘mygame’, the Windows Phone creates two different projects in the Visual Studio solution named ‘mygame’. It includes a C# project called ‘mygame’ and a C++ project called ‘mygameComponent’. The C# project provides the basic application framework whereas the game logic is part of the C++ project. In most situation, you will not need to modify the C# project. Make sure that you include your C++ code in ‘mygameComponent’.
- How do I include custom/third party DLLs used in my game?
Windows Phone applications are built for both the development environment (Win32/x86) as well as the real physical devices running on ARM. As such, custom/third party DLLs are needed for both Win32/x86 and ARM environments. Additionally, they need to be available in both Debug and Release environments. Four different version of custom/ third party DLLs need to be included with the application. These DLLs should be marked as ‘Content’ so that they are bundled in the application package.What is the exact way to accomplish this? Do you include 4 different versions?
- Are there any limits on the size of the app on Windows Phone? (or How to reduce the size of Windows Phone app?)
Windows Phone imposes a default memory limit on an app based on the type of app and the memory size of the device. Be aware that on low memory devices, the default memory limit for the app is 150 MB and as such, Windows Phone app should minimize its memory usage where possible. Since .wav audio files are bigger than their corresponding MP3 files, be judicious of the sampling rate and stereo/mono when converting MP3 files to WAV files.You can also manage the amount of texture memory used by the application. Debug build of Windows Phone shows the amount of texture memory being used. You can use this information to tweak the memory usage of your application.You can selectively turn off of features of your app for lower memory devices or you can choose to opt out of availability for lower memory devices.
- Developing on Mac using Fusion/Parallel/Bootcamp.
Look at http://blogs.msdn.com/b/interoperability/archive/2012/12/21/how-to-develop-for-windows-phone-8-on-your-mac.aspx on how to develop Windows Phone apps on Mac for details
- Developing Windows Phone application using Visual Studio 2013 or Visual Studio 2013 Express. While Visual Studio 2012 Express for Windows Phone includes the Windows Phone SDK, you can install Windows Phone 8 SDK separately and use Visual Studio 2013. See https://dev.windowsphone.com/en-us/downloadsdk for instructions.
- I have installed Visual Studio but I am not able to open the Windows Phone project.
If you are seeing an error opening Visual Studio solution file in WP8-xaml directory make sure that you have installed Windows Phone SDK. Windows Phone 8 SDK can be installed from https://dev.windowsphone.com/en-us/downloadsdk.Alternately, install and use Visual Studio 2012 Express for Windows Phone for developing Windows Phone game.
- I have set breakpoints in my C++ code but the app never stops at those breakpoints during while debugging.
Cocos2d-x Windows Phone solution consists of a C# project and C++ project of which the C# project is the startup project. In order to debug the C++ code, you will need to enable debugging native code. To enable debugging C++ code, right click the C# project and select properties. In Debug tab, select ‘Native only’ in ‘UI Task’ drop down for Debugger Type.
- I believe I have some issues with platform specific parts of my app. The game works alright on iOS and Android but not only Windows Phone.
If you have any platform specific code in your game, make sure that you handle Windows Phone and Windows 8 properly. Platform specific code is often enclosed using #ifdef that checks for iOS and Android. You will need to enclose Windows Phone and Windows 8 platform specific code using #ifCC_TARGET_PLATFORM == CC_PLATFORM_WP8 for WP8 and #ifCC_TARGET_PLATFORM == CC_PLATFORM_WINRTfor Windows 8.
- How do I add my resources if my project structure is non-standard? Visual Studio uses MSBuild for building the application. The MSBuild task included with the Windows Phone project looks for resources in the global resources directory and recursively copies them in the .xap file, i.e. the application package. If your game resources are kept in a different directory or organized differently, you will need to modify the MSBuild task. From Visual Studio, unload the C# project, edit .vcproj file to modify the following MSBuild task.
- My app does not use TTF fonts. What can I do?
Windows Phone only supports TTF fonts. Consider using TTF fonts for Windows using platform specific code for WP8 and WinRT.
- How do I test my app on Windows Phone device?
You should deploy and test your app on a real phone before you submit the app to the Windows Phone store.
To deploy the app on a real phone, you must be a registered developer. See Windows Phone developer registration.
Once you have tested your app in the emulator, it is time to deploy the application on a real phone. Before you deploy your application to a real phone, you need to register your phone for development. Please follow instructions specified on this web page.The next step is to deploy the app to a Windows Phone device. Follow instructions on this web page.
- My application runs in the emulator but not on a real Windows Phone device.
- Missing V11 folder. Uninstall everything and install the recommended config.
- Follow troubleshooter specified on this web page.
In this article, we saw how incredibly easy it is to port a Cocos2d-x app written in C++ to Windows 8 and Windows Phone. MSOpenTech, a Microsoft subsidiary focused on interoperability with Open Source software, has done most of the heavy lifting. The Cocos2d-x on Windows 8 and Windows phone provide identical APIs making it easy to port the applications.
The steps involved
- Create a Cocos2d-x project using project creator tool.
- Create Windows 8 and Windows Phone projects in Visual Studio.
- Copy the source code consisting of C++ and header files to the project Classes directory. Add these files to your project in Visual Studio
- Copy resources to the project Resources directory.
- Modify a couple of project settings necessary for compilation.
- For Windows Phone, convert any MP3 files to WAV files. Similarly, for Windows Phone replace fonts that are not supported by Windows Phone or update the code to use fonts available on the platform.
If you have already written a multi-platform game, you are likely to haven completed a few of these steps already. If you are planning to develop a multi-platform game, you can take care of some of these steps in the beginning to open up a huge new market of Windows 8 devices and Windows Phones with very little extra effort.