Porting a cocos2d-x game from Windows to Android involves multiple configuration steps and toolchain setups. This guide provides a comprehensive walkthrough based on practical experience with cocos2d-x 2.1.2, covering environment preparation, project generation, compilation, and common pitfalls.

Development Environment

The development environment used in this process includes:

• Operating System: Windows 8 Professional 64-bit
• IDE: Visual Studio 2012 RTM, Eclipse
• cocos2d-x Version: 2.1.2
• Additional Tools: Android SDK, Android NDK, Cygwin

Toolchain Installation

Cygwin Setup

Download the Cygwin installer from the official website (http://cygwin.com/install.html). For 64-bit Windows, use the x86_64 version.

During installation, when prompted to select a download mirror, choose a reliable server. The mirror ftp://mirrors.neusoft.edu.cn provides good download speeds in many regions. Note that not all mirrors contain complete packages—if downloads fail, try alternative mirrors.

In the package selection dialog, ensure these development packages are selected under the Devel category:

• binutils
• gcc-core
• gcc-g++
• gdb
• make
• mingw-gcc-core
• mingw-gcc-g++

After installation, verify by running thece commands in the Cygwin terminal:

gcc --version
g++ --version
make --version
gdb --version

If any command returns "command not found," rerun the installer and add the missing package.

Android SDK, NDK, and Eclipse

Download and install the following components:

• Android SDK: http://developer.android.com/sdk/index.html
• Android NDK: http://developer.android.com/tools/sdk/ndk/index.html (extract to a location without spaces)
• Eclipse: http://www.eclipse.org/downloads/

Configure Eclipse for Android development by installing the ADT plugin and setting the SDK location in preferences.

Project Creation Script Configuration

In the cocos2d-x root directory, locate create-android-project.bat. Open it with an editor that supports Unix line endings (such as Notepad++ or UltraEdit).

Modify these path variables:

set _CYGBIN=c:\cygwin64\bin
set _ANDROIDTOOLS=c:\android-sdk\tools
set _NDKROOT=c:\android\ndk-r9d

Replace the paths with your actual installation directories. Save the changes and run the script through Cygwin by dragging it into the terminal window. If configured correctly, you'll see:

Input package path. For example: org.cocos2dx.example:

Generating the Android Project

Execute the create-android-project script. When prompted:

1. Enter the package identifier (e.g., com.gamedev.spaceshooter)
2. Enter the project name (e.g., SpaceShooter)
3. Select the target Android API level from the displayed list

The script creates a project directory containing Classes and Resources folders. Remove the default HelloWorld files from both directories and copy your game's source files (.cpp, .h) into Classes and assets (images, audio) into Resources.

Note: The main entry point at proj.android/jni/hellocpp/main.cpp may have restricted permissions. Adjust file security settings to view/edit if needed, though modifications are rarely required.

Build Configuration

Modifying Android.mk

The Android.mk file in proj.android/jni defines the build configuration. Here's a typical setup:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE := game_module
LOCAL_MODULE_FILENAME := libgamecore

LOCAL_SRC_FILES := hellocpp/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../Classes/GameScene.cpp \
                   ../../Classes/Player.cpp \
                   ../../Classes/Enemy.cpp \
                   ../../Classes/Projectile.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
                    $(LOCAL_PATH)/../../../cocos2dx/platform/third_party/win32 \
                    $(LOCAL_PATH)/../../../extensions

LOCAL_WHOLE_STATIC_LIBRARIES := cocos2dx_static cocosdenshion_static cocos_extension_static

include $(BUILD_SHARED_LIBRARY)

$(call import-module,CocosDenshion/android) \
$(call import-module,cocos2dx) \
$(call import-module,extensions)

Critical Configuration Points:

• LOCAL_MODULE and LOCAL_MODULE_FILENAME must match the library name loaded in Java code
• List all source files in LOCAL_SRC_FILES with proper line continuation using \
• Add necessary include paths for third-party libraries or extensions

Java Integration: In src/com/gamedev/spaceshooter/SpaceShooter.java, ensure the library name matches:

static {
    System.loadLibrary("gamecore"); // Matches LOCAL_MODULE_FILENAME without 'lib' prefix
}

Thread Compatibility

If using pthread, change #include "pthread/pthread.h" to #include "pthread.h" in source files to ensure proper compilation.

Compilation Process

Running build_native.sh

Navigate to the project directory and execute build_native.sh through Cygwin. Successful compilation produces:

Install: libgamecore.so => libs/armeabi/libgamecore.so

Common Compilation Errors

NDK_ROOT Undefined:

If you encounter "please define NDK_ROOT," edit ~/.bash_profile in Cygwin's home directory and add:

NDK_ROOT=/cygdrive/c/android/ndk-r9d
export NDK_ROOT

Missing Function Declarations:

Functions like itoa() may not be available in the NDK toolchain. Implement a replacement:

char* int_to_string(int value, char* buffer, int base) {
    // Implementation here
    return buffer;
}

Format String Isues:

Android's logging requires explicit format specifiers. Change:

LOGD(deviceModel); // Incorrect

To:

LOGD("%s", deviceModel); // Correct

File I/O Operations:

Replace standard C++ file streams with cocos2d-x utilities:

std::string path = CCFileUtils::sharedFileUtils()->getWritablePath() + "save.dat";
unsigned long size = 0;
char* data = (char*)CCFileUtils::sharedFileUtils()->getFileData(path.c_str(), "r", &size);
if (data == NULL) {
    // Handle error
}

Eclipse Project Import

Importing the Project

1. In Eclipse, select File > New > Project > Android > Android Project from Existing Code
2. Browse to your project's proj.android directory
3. Finish the import wizard

Required File Copies

1. Copy cocos2dx/platform/android/java/src contents to proj.android/src
2. Copy all resources from Resources to proj.android/assets
3. Refresh the project in Eclipse (F5)

Final Adjustments

• Ensure the library name in Java matches the compiled .so file
• Add a launcher icon in res/drawable/ if missing
• Verify AndroidManifest.xml has proper permissions and activity declarations

Debugging Techniques

Device Debugging: Emulators often lack OpenGL ES 2.0 support and run slowly. Use physical devices via USB debugging for reliable testing.

Log Analysis: Use adb logcat or Eclipse's LogCat view to identify runtime errors. Search for keywords like "shader" or "permission" to locate issues.

Progressive Logging: Add trace logs to isolate failures:

CCLOG("Loading texture: %s", textureName);
CCLOG("Initializing physics engine");
CCLOG("Scene setup complete");

This helps identify the exact failure point when encountering black screens or crashes.

Resolution Handling

Add resolution adaptation in AppDelegate.cpp:

bool AppDelegate::applicationDidFinishLaunching() {
    // ... existing code ...
    CCEGLView::sharedOpenGLView()->setDesignResolutionSize(
        800, 480, kResolutionNoBorder);
    // ... rest of code ...
}

The parameters are: design width, design height, and scaling policy. Available policies include:

• kResolutionExactFit: Stretches to fill screen, may distort aspect ratio
• kResolutionNoBorder: Maintains aspect ratio, may crop edges
• kResolutionShowAll: Maintains aspect ratio, may show borders

Choose based on your game's visual requirements.