Porting Cocos2D-x Games to Windows Store and Windows Phone

Introduction

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 for Windows 8 and Windows Phone

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.

About this Article

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.

Setup your Development Environment

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.

Download Cocos2d-x Distribution

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:\>cd cocos2d-x
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.

 

image

Download the Sample Application

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

Porting the Application

Create a new Cocos2d-x Project

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>cd tools\project-creator
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/..
/../projects/parkour
Have Fun!

This creates a skeleton project structure that can be used for developing multi-platform applications. The directories for the project are organized as follows:

C:\cocos2d-x>cd tools\projects\parkour
C:\cocos2d-x\projects\parkour>dir

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.

clip_image004[4]

After Visual Studio has opened the project, click the Local Machine button with the green triangle or Debug > Start Debugging (or Start Without Debugging).

clip_image006[4]

After Visual Studio builds the files that are out of date, you should have the application running in Windows 8 mode.

clip_image008[4]

Modify Target Application

Now that we are able to run simple application on Windows 8, we are ready to port our target application.

Copy project class files to Classes directory

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>
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
C:\temp\SK_Parkour\projects\ParkourCPP\Classes\AppDelegate.cpp
C:\temp\SK_Parkour\projects\ParkourCPP\Classes\AppDelegate.h
C:\temp\SK_Parkour\projects\ParkourCPP\Classes\AppMacros.h”

26 File(s) copied

Copy Resources to Resources Directory

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
C:\temp\SK_Parkour\projects\ParkourCPP\Resources\background.mp3
C:\temp\SK_Parkour\projects\ParkourCPP\Resources\crouch.mp3
C:\temp\SK_Parkour\projects\ParkourCPP\Resources\jump.mp3

26 File(s) copied

Add Source Code to the Visual Studio Project

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

clip_image010[4]

Select all cpp and h files from c:\cocos2d-x\projects\parkour\Classes and click Add.

clip_image012[4]

Execute the application by selecting Debug > Run.

clip_image014[4]

Porting the Game to Windows Phone

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.

Audio file support on Windows Phone

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

audioEngine->preloadBackgroundMusic("background.wav");

audioEngine->preloadEffect("jump.wav");

audioEngine->preloadEffect("crouch.wav");

audioEngine->preloadEffect("pickup_coin.wav");

#else

audioEngine->preloadBackgroundMusic("background.mp3");

audioEngine->preloadEffect("jump.mp3");

audioEngine->preloadEffect("crouch.mp3");

audioEngine->preloadEffect("pickup_coin.mp3");

#endif

Similarly, modify the code in runner.cpp, playscene.cpp files to use WAV files.

#if CC_TARGET_PLATFORM == CC_PLATFORM_WP8

audioEngine->playBackgroundMusic("jump.wav", true);

#else

audioEngine->playBackgroundMusic("jump.mp3", true);

#endif

Font support on Windows Phone

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);

#else

    this->labelCoin = CCLabelTTF::create("Coins:0", "Helvetica", 25);

#endif

Once you have completed these code changes, click Debug > Run without Debugging to run the application in the Windows Phone emulator.

clip_image016[4]

Tips, Tricks and Troubleshooting

  1. 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’.
  2. 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?
  3. 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.
  4. 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
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.

     <ItemGroup>

        <ContentInclude="..\..\..\Resources\**\*">

          <Link>Assets\Resources\%(RecursiveDir)%(FileName)%(Extension)</Link>

          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>

        </Content>

     </ItemGroup>

  10. 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.
  11. 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.
  12. My application runs in the emulator but not on a real Windows Phone device.
    1. Missing V11 folder. Uninstall everything and install the recommended config.
    2. Follow troubleshooter specified on this web page.

Summary

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

  1. Create a Cocos2d-x project using project creator tool.
  2. Create Windows 8 and Windows Phone projects in Visual Studio.
  3. Copy the source code consisting of C++ and header files to the project Classes directory. Add these files to your project in Visual Studio
  4. Copy resources to the project Resources directory.
  5. Modify a couple of project settings necessary for compilation.
  6. 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.

7 thoughts on “Porting Cocos2D-x Games to Windows Store and Windows Phone

  1. Hi,

    Have you tried getting Cocos2d-x 3.0 to work with Windows 8 and Windows 8 Phone?

    Do you know what the difference is between these two repos?
    https://github.com/cocos2d/cocos2d-x
    https://github.com/cocos2d-x/cocos2d-x

    Thanks!
    Jim

    Here is what I have observed regarding the cocos2d-x git repos.

    The branch v3 at https://github.com/cocos2d/cocos2d-x seems to be the latest code. There is a tag called cocos2d-x-3.0, which, given its name, is probably the latest stable release.

    The branch master at https://github.com/cocos2d-x/cocos2d-x that this tutorial uses seems to be an older version with the most recent commit occurring last September… probably version 2.2 since the master branch was recently renamed in the https://github.com/cocos2d/cocos2d-x repo from master to v2.

    commit 36811e40a924365a1d275bb7c2ebf43b6da6c07a
    Merge: 492147a 50a3e54
    Author: James Chen
    Date: Mon Sep 16 07:45:57 2013 -0700

  2. Thanks a lot for this incredibly helpfull post!
    I’m releasing an iOS & Android game using Cocos2D-X and I was planning to release on Windows Phone 8 in the next weeks. I learnt many things.
    I want to point that it’s a shame to have to encode sounds in .WAV format. Regarding to this article, I understand that there is no compressed format that can be played on Windows Phone. OGG format – which is an open source format – could have been a good way to encode sounds. WAV format is so heavy!

  3. Hi,
    I tried to follow this posting since it seem to convey some great information.
    However, the parkour repository and the project creator do NOT create any project files for winrt. How was that achieved??? I can’t see how to get the app working on windows phone without those.

    Thanks,
    Totte

  4. Hi,
    I tried to build project using visual studio 2013 but i had a problem like below. Can you help me ?
    error C1189: #error : agile.h can only be used with /ZW C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\WPSDK\WP80\include\agile.h

  5. Pingback: 移植 Cocos2d-x 至 Windows 平台 - Meng-Ru Tsai's Blog - Site Home - MSDN Blogs

Leave a Reply