Creating Android plugins (Godot 3.2.2+)

はじめに

Androidプラグインは、Androidプラットフォームとエコシステムによって提供される機能を活用して、Godotエンジンの機能を拡張する強力なツールです。

モバイルゲームの収益化は、ゲームエンジンのコア機能セットに属さない機能を必要とするため、そのような例の1つです:

  • 分析
  • アプリ内購入
  • 証明書の検証
  • トラッキングのインストール
  • 広告
  • 動画広告
  • クロスプロモーション
  • ゲーム内のソフト通貨とハード通貨
  • プロモーションコード
  • A/B テスト
  • ログイン
  • クラウド保存
  • ランキングとスコア
  • ユーザーサポートとフィードバック
  • Facebook、Twitterなどへの投稿。
  • プッシュ通知

Androidプラグイン

While introduced in Godot 3.2.0, the Android plugin system got a significant architecture update starting with Godot 3.2.2. The new plugin system is backward-incompatible with the previous one, but both systems are kept functional in future releases of the 3.2.x branch. Since we previously did not version the Android plugin systems, the new one is now labelled v1 and is the starting point for the modern Godot Android ecosystem.

Note: In Godot 4.0, the previous system will be fully deprecated and removed.

前提条件として、Android用に カスタムビルド環境 をセットアップする方法を理解してください。

基本的に、Godot Androidプラグインは `Androidアーカイブライブラリ <https://developer.android.com/studio/projects/android-library#aar-contents>`_(aar アーカイブファイル)であり、次の注意事項があります:

  • The library must have a dependency on the Godot engine library (godot-lib.<version>.<status>.aar). A stable version is made available for each Godot release on the Godot download page.
  • ライブラリには、マニフェストファイルに特別に構成された <meta-data> タグを含める必要があります。

Androidプラグインの作成

前提条件: Androidプラグインの作成に使用するIDEとして、Android Studio を強く推奨します。以下の手順は、Android Studioを使用していることを前提としています。

  1. これらの手順 に従ってプラグイン用のAndroidライブラリモジュールを作成します。

  2. プラグインモジュールへの依存関係としてGodotエンジンライブラリを追加します:

    • Download the Godot engine library (godot-lib.<version>.<status>.aar) from the Godot download page (e.g: godot-lib.3.2.2.stable.aar).
    • これらの手順 に従って、プラグインの依存関係としてGodotエンジンライブラリを追加します。
    • プラグインモジュールの build.gradle ファイルで、Godotエンジンライブラリの依存関係行の implementationcompileOnly に置き換えます。
  3. プラグインモジュールで新しいクラスを作成し、それが org.godotengine.godot.plugin.GodotPlugin を拡張していることを確認します。実行時に、プラグインをロード、初期化、および実行するためにGodotエンジンによって使用されるシングルトンオブジェクトをインスタンス化するために使用されます。

  4. プラグイン AndroidManifest.xml ファイルを更新します:

    • プラグイン AndroidManifest.xml ファイルを開きます。

    • 存在しない場合は、<application></application> タグを追加します。

    • <application> タグで、次のように <meta-data> タグの設定を追加します:

      <meta-data
          android:name="org.godotengine.plugin.v1.[PluginName]"
          android:value="[plugin.init.ClassFullName]" />
      

      ここで、PluginName はプラグインの名前であり、plugin.init.ClassFullName はプラグイン読み込みクラスのフルネーム(パッケージ+クラス名)です。

  5. プラグインの残りのロジックを追加し、gradlew build コマンドを実行してプラグインの aar ファイルを生成します。ビルドはおそらく debugrelease aar``ファイルの両方を生成します。必要に応じて、ユーザーに提供するバージョンを1つだけ選択します(通常は ``release バージョン)。

    It's recommended that the aar filename matches the following pattern: [PluginName]*.aar where PluginName is the name of the plugin in PascalCase (e.g.: GodotPayment.release.aar).

  6. Create a Godot Android Plugin configuration file to help the system detect and load your plugin:

    • The configuration file extension must be gdap (e.g.: MyPlugin.gdap).

    • The configuration file format is as follow:

      [config]
      
      name="MyPlugin"
      binary_type="local"
      binary="MyPlugin.aar"
      
      [dependencies]
      
      local=["local_dep1.aar", "local_dep2.aar"]
      remote=["example.plugin.android:remote-dep1:0.0.1", "example.plugin.android:remote-dep2:0.0.1"]
      custom_maven_repos=["http://repo.mycompany.com/maven2"]
      

      The config section and fields are required and defined as follow:

      • name: name of the plugin
      • binary_type: can be either local or remote. The type affects the binary field
      • binary:
        • if binary_type is local, then this should be the filepath of the plugin aar file.
          • The filepath can be relative (e.g.: MyPlugin.aar) in which case it's relative to the res://android/plugins directory.
          • The filepath can be absolute: res://some_path/MyPlugin.aar.
        • if binary_type is remote, then this should be a declaration for a remote gradle binary (e.g.: org.godot.example:my-plugin:0.0.0).

      The dependencies section and fields are optional and defined as follow:

      • local: contains a list of filepaths to the local .aar binary files the plugin depends on. Similarly to the binary field (when the binary_type is local), the local binaries' filepaths can be relative or absolute.
      • remote: contains a list of remote binary gradle dependencies for the plugin.
      • custom_maven_repos: contains a list of URLs specifying the custom maven repositories required for the plugin's dependencies

Androidプラグインの読み込みと使用

Move the plugin configuration file (e.g.: MyPlugin.gdap) and, if any, its local binary (e.g.: MyPlugin.aar) and dependencies to the Godot project's res://android/plugins directory.

The Godot editor will automatically parse all .gdap files in the res://android/plugins directory and show a list of detected and toggleable plugins in the Android export presets window under the Plugins section.

../../../_images/android_export_preset_plugins_section.png

From your script:

if Engine.has_singleton("MyPlugin"):
    var singleton = Engine.get_singleton("MyPlugin")
    print(singleton.myPluginFunction("World"))

GDNativeリソースのバンドル

Androidプラグインは、ゲームロジックの機能を提供またはアクセスするために、C/C ++ GDNativeリソースを定義および提供できます。 GDNativeリソースはプラグイン aar ファイル内にバンドルすることができ、配布とデプロイのプロセスを簡素化します:

  • 定義されたGDNativeライブラリの共有ライブラリ(.so)は、aar ビルドシステムによって自動的にバンドルされます。
  • Godotの *.gdnlib および *.gdns リソースファイルは、プラグインの assets ディレクトリで手動で定義する必要があります。assets ディレクトリに対するこれらのリソースの推奨パスは、godot/plugin/v1/[PluginName]/ でなければなりません。

GDNativeライブラリの場合、プラグインシングルトンオブジェクトは org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths() メソッドをオーバーライドし、バンドルされたGDNativeライブラリ設定ファイル(*.gdnlib へのパスを返す必要があります)。パスは assets ディレクトリからの相対パスでなければなりません。実行時に、プラグインはこれらのパスをGodotコアに提供します。Godotコアはそれらを使用して、バンドルされたGDNativeライブラリをロードおよび初期化します。

トラブルシューティング

ロード時にGodotがクラッシュする

adb logcat で問題がないかチェックしてください:

  • Javaシングルトンで使用されるメソッドが単純なJavaデータ型のみを使用することを確認してください。より複雑なデータ型はサポートされていません。