移植 Cocos2d-x 遊戲至 Windows Store 及 Windows Phone

除了 Unity 之外，Cocos2d-x 是另一個台灣遊戲開發者很常使用的 2D 遊戲引擎，Cocos2d-x 在 Windows 及 Windows Phone APIs 的支援上與 iOS 及 Android 完全相同，也就是要將 Cocos2d-x 所製作的遊戲移植至 Windows 平台並不困難，順利的話一個遊戲約數個小時即可移植成功。

簡單來說是以下 6 個步驟:

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.

你需要:

1. Windows 8.1 (64 bit) 評估版: https://technet.microsoft.com/zh-tw/evalcenter/hh699156.aspx

2. Visual Studio Express 2013:https://www.microsoft.com/en-us/download/details.aspx?id=43729

3. 註冊 Windows 市集以上架: https://blogs.msdn.com/b/mengtsai/archive/2014/09/23/windows-2014-09.aspx

以下段落完全轉貼自Porting Cocos2D-x Games to Windows Store and Windows Phone，文章中詳細說明了環境需求、移植步驟、小技巧及故障排除等資訊給各位參考:

source: Porting Cocos2D-x Games to Windows Store and Windows Phone

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 https://github.com/cocos2d/cocos2d-x. Click Clone in Desktop.

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 https://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.

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.

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

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

Execute the application by selecting Debug > Run.

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.

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 https://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.

Comments

• Anonymous
  September 23, 2014
  coool... thank you for sharing. nice article.