Plugin-X Integration Guide for Android

Plugin-X 在android下的整合

集成第三方SDK

環境需求

1. python 2.7。 http://www.python.org/
2. Apache Ant build tool. http://ant.apache.org/
3. 若是你的操做系統是Windsws,你須要安裝Cygwin環境.

編譯Plugin-X 項目

1. 運行 publish.sh腳本 ，路徑爲plugin-x/tools/publish.sh. 這個腳本在 Mac OSX Mountain Lion v10.8.2 和 Cygwin on Windows 7下測試良好. 在腳本第一次運行的時候, 它會讓你輸入一些參數來設置環境, 以下

   在Windows上, 你輸入的路徑應該以Linux的路徑形式輸入. 示例 : 你能夠輸入 C:/adt-bundle-windows/sdk, 而不是C:\adt-bundle-windows\sdk

2. 編譯完成後, 名爲 publish 的文件夾會生成在plugin-x 項目的根目錄下. 若是你的 publish 文件夾以下圖, 那意味着你的編譯成功.

3. publish 文件夾包含以下文件:
   • plugin頭文件(*.h)
   • C++ 靜態庫 (*.a)
   • java 庫 (*.jar)
   • makefiles for android (*.mk)
   • 一些插件需求的android 項目

在使用插件以前編輯遊戲項目

咱們須要作什麼?

Plugin-x 爲第三方android的SDK封裝C/C++ 接口. 因此咱們須要編輯遊戲項目設置以便能使用它:

• 編輯 .mk 文件(Android.mk & Application.mk) 來連接由 plugin-x建立的靜態庫.
• 編輯android項目設置來連接由 plugin-x 建立的庫 和 第三方sdk庫. (.jar 文件)
• 編輯AndroidManifest.xml, 添加 activities的聲明, 和遊戲使用權限.
• 對於個別插件, 咱們須要添加額外的設置和資源文件.

遊戲開發者引導工具

有個名爲 gameDevGuide.sh 的腳本，路徑 plugin-x/tools/gameDevGuide.sh. 此腳本將幫助你編輯你的遊戲項目.

1. 在終端運行該腳本 (在Windows上, 你應該使用Cygwin來運行它). UI界面以下: 

   在edit-box裏面輸入你的遊戲的android項目的路徑. 請保證路徑沒有空格. （譯者注：windows下的路徑"\"改成"/"，否則的話，它也能正常到下一步，可是再繼續會出錯）而後點擊 'Next' 按鈕.

2. 選擇你須要的插件. UI界面以下:

    選擇插件以後, 點擊 'Finish' 按鈕. 該腳本將會編輯你的android項目裏的幾個配置文件.

如下配置文件將被編輯:

• Android.mk -------------- 添加遊戲依賴的C++ 庫
• Application.mk ----------- 爲ndk build添加參數
• .project ----------------- 連接publish目錄到遊戲工程做爲資源
• .classpath --------------- 添加遊戲依賴的java 庫
• AndroidManifest.xml ------ 添加遊戲所需的插件的activity的聲明 和 用戶權限

手動編輯

1. 編輯ndk-build 命令參數 : 添加 publish 目錄到 NDK_MODULE_PATH 參數下, 以下 :NDK_MODULE_PATH=${PLUGIN_ROOT}/publish

2. 添加代碼到JNI_OnLoad方法下, 以下 :

   #include 「PluginJniHelper.h」
   jint JNI_OnLoad
   {
   JniHelper::setJavaVM;
   PluginJniHelper::setJavaVM; // for plugins
   return JNI_VERSION_1_4;
   }

3. 在遊戲的main activity被建立的時候，調用 PluginWrapper.init()方法 :

   import org.cocos2dx.plugin.PluginWrapper;
   import org.cocos2dx.lib.Cocos2dxGLSurfaceView;
   public class HelloIAP extends Cocos2dxActivity{
   protected void onCreate{
   super.onCreate();
   PluginWrapper.init(); // for plugins
   // If you want your callback function can be invoked in GL thread, add this line:
   PluginWrapper.setGLSurfaceView();
   }
   static {
   System.loadLibrary;
   }
   }

4. 特別的插件修改項 若是你的遊戲使用的一下插件, 你可能須要一些特殊的修改. 咱們已經計劃添加這些修改項到開發者指導工具裏.

   • 對於nd91

     1. 導入android 工程 91SDK_LibProject_complete 到eclipse裏. 工程路徑爲 plugin-x/publish/nd91/andriod/DependProject

     2. 設置你的遊戲工程依賴於91SDK_LibProject_complete工程, 以下圖:

在你的C++ 代碼裏使用plugin-x

加載和卸載插件

全部的插件由 class PluginManager 管理. 你能夠經過插件的類名加載/卸載插件 , 示例代碼 :

// load plugin AnalyticsFlurry
    s_pFlurry = dynamic_cast
    (PluginManager::getInstance()->loadPlugin("AnalyticsFlurry"));

    // unload plugin AnalyticsFlurry
    PluginManager::getInstance()->unloadPlugin("AnalyticsFlurry");
    s_pFlurry = NULL;

建議 : 當遊戲開始的時候加載插件, 遊戲結束的時候卸載插件.

使用插件

你能夠調用在協議中聲明的方法. 示例代碼:

// enable the debug mode
    s_pFlurry->setDebugMode(true);

    // log an event
    s_pFlurry->logEvent("music");

    // log an event with params
    LogEventParamMap paramMap;
    paramMap.insert(LogEventParamPair("type", "popular"));
    paramMap.insert(LogEventParamPair("artist", "JJLin"));
    s_pFlurry->logEvent("music", ¶mMap);

一些插件擁有自定義方法。咱們在plugin-x中實現了一個簡單的反射。 你能夠經過名字調用自定義方法。像這樣：

// invoke setAge() method in plugin Flurry
    PluginParam pParam3(20);
    s_pFlurry->callFuncWithParam("setAge", &pParam3, NULL);

    // invoke logTimedEventBeginWithParams() method in plugin Flurry
    PluginParam event3("music-kv");
    LogEventParamMap paramMap;
    paramMap.insert(LogEventParamPair("type", "popular"));
    paramMap.insert(LogEventParamPair("artist", "JJLin"));
    PluginParam mapValue(paramMap);
    s_pFlurry->callFuncWithParam("logTimedEventBeginWithParams", &event3, &mapValue, NULL);

一樣，這裏有一些反射接口定義返回基礎類型值。方法列表以下：

// return string value for developers
    const char* callStringFuncWithParam(const char* funcName, PluginParam* param, ...);

    // return int value for developers
    int callIntFuncWithParam(const char* funcName, PluginParam* param, ...);

    // return bool value for developers
    bool callBoolFuncWithParam(const char* funcName, PluginParam* param, ...);

    // return float value for developers
    float callFloatFuncWithParam(const char* funcName, PluginParam* param, ...);

注意：

• 你能夠在方法中傳遞參數，參數的類型必須是PluginParam指針。
• 插件中的參數必須按順序傳遞
• 若是方法在插件中找不到，什麼都不會發生。

參考

1. 截圖和示例代碼來自plugin-x的例子工程 HelloIAP
2. 若是你有任何問題，請不要不肯意在這篇wiki上評論, 或者建立issues在github.com/chukong/plugin-x/ 工程上.