Cocos2d-x PluginX （一）使用手冊

簡介

Plugin-x是cocos2d-x最近版本中引入的特性，旨在解決第三方SDK接入的問題，最大程度的簡化接入工做，增長可重用性。第一部分主要介紹PluginX如何使用，不涉及設計原理相關內容。

${cocos2d-x root}\plugin目錄下是PluginX所在位置，從設計和相關文檔看感受這東西至關複雜，但實際上使用起來很是簡便。(複雜的設計是爲了使用上簡單方便)

前提

必要條件是配置好Android開發環境，須要NDK。Win下須要安裝Cygwin，Cygwin須要gcc、make包，由於這個模塊裏的自動化腳本是Unix Shell。

使用現有Plugin步驟

publish.sh 編譯輸出

1. 執行plugin/tools/publish.sh腳本，根據提示輸入Android SDK、NDK、Ant/bin的路徑。

   Ant是Android的打包工具，配置好的Eclipse Android開發環境，那這個工具不須要單獨安裝，能夠搜索下。我這裏的路徑是：開發環境目錄/adt-bundle-windows-x86/eclipse/plugins/org.apache.ant_1.8.3.v201301120609/bin。

2. 執行完畢後，會生成plugin/publish目錄，結果看起來大體以下：

   這一步實際上，是把Protocol工程、和各個Plugins工程，編譯打包輸出jar包和其它關鍵資源到publish目錄，以供後面目標工程中引用。

3. publish中的文件主要有：

   • 頭文件 .h
   • C++靜態庫 .a
   • java庫文件 .lib
   • Android makefile文件 .mk
   • 其它plugin用到的資源

一些問題

1. 因爲project.properties中的target版本找不到(默認level = 7)，編譯失敗。我都修改到了8。
2. copy的資源目錄爲只讀目錄而且權限不對，不能訪問，對後續的文件操做有影響。發現是Cygwin的問題，Google處理一下便可。

修改目標工程

把plugin應用到具體的Android工程中，這一步須要進行修改、增長內容，讓目標工程正常使用須要的plugin。

gameDevGuide.sh 自動化修改部分

這是一個作關鍵修改的自動化腳本，它會自動把資源添加、修改到目標工程，很是簡單、好用。

1. 執行plugin/tools/gameDevGuide.sh，根據UI提示輸入Android目錄，而後Next。
2. 接下來彈出一個帶複選框的界面，選擇須要使用的plugin，Finish便可。

大體會作以下修改：

• Android.mk —– 加入plugin模塊C++ 靜態庫的依賴
• Application.mk —– 增長ndk編譯選項
• .project —– 連接publish目錄下的相關資源
• .classpath —– 加入相關的java 庫文件依賴
• AndroidManifest.xml —– 加入plugin須要的Activity聲明或權限聲明

手動修改部分

還有一些須要手動修改的部分。

1. 修改ndk-build參數，加入publish目錄到NDK_MODULE_PATH，修改build_native.sh文件(須要在shell中定義PLUGIN_ROOT值)，例如：

   NDK_MODULE_PATH=${PLUGIN_ROOT}/publish:(冒號後面是原有值)

2. 修改main.cpp中的JNI_Onload方法

   #include "PluginJniHelper.h" 
   
    jint JNI_OnLoad(JavaVM *vm, void *reserved)
    {
        JniHelper::setJavaVM(vm);
        PluginJniHelper::setJavaVM(vm);  // for plugins
   
        return JNI_VERSION_1_4;
    }

3. 在Android主Activity中加入

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

4. 一些SDK的特殊修改

   例如nd91，須要依賴一個Lib工程。

C++代碼裏使用PluginX

JNI調用和相關的虛接口都已經在Protocol工程裏處理好了，因此使用時都不用關心，可直接使用。下面是一些示例代碼：

1. load/unload plugin，直接經過java類名操做

   // load plugin AnalyticsFlurry
    s_pFlurry = dynamic_cast<ProtocolAnalytics*>
    (PluginManager::getInstance()->loadPlugin("AnalyticsFlurry"));
   
    // unload plugin AnalyticsFlurry
    PluginManager::getInstance()->unloadPlugin("AnalyticsFlurry");
    s_pFlurry = NULL;

2. 使用plugin

   直接使用protocol中定義的接口基本能夠知足所有需求了，以下：

   // 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"));
    s_pFlurry->logEvent("music", &paramMap);

3. 還能夠調用自定義的方法，不詳細介紹。

一些問題

1. 導入工程到Eclipse後，Lib庫沒有找到。發現這裏是經過修改.project加入LinkedResources標記，把Plugin/publish目錄引入的。使勁刷新下工程就行了。。。

2. C++代碼ndk編譯不過，後來發現是Plugin有個獨立的命名空間，須要引入。。。

3. 找不到org/cocos2dx/plugin/AnalyticsUmeng，仔細一看，發現這個類是定義在plugin/plugins/umeng/proj.android/src下的。又一檢查，發現這個工程根本沒有編譯經過，沒有生成.jar文件。很奇怪，全部jar文件在publish腳本跑事後都沒有生成，手動ant操做一次纔出來。

   查了半天，原來是ANT路徑輸入不全，沒寫bin目錄。無奈啊。。。

通過艱苦的調試與修改，終於能夠正常跑通了。估計能遇到的問題我遇過了，總之都是小問題。

總結

使用上，兩個自動化腳本跑一下，手動修改幾個點，就能夠了，能夠說很是簡單。簡化了不少繁雜的工做，可是實際上整個模塊的設計比較複雜，若是對JNI、Ant打包、Shell腳本等等沒個詳細瞭解的話，出現問題很難搞定。