Creating Android plugins

简介

Android插件是通过挖掘Android平台和生态系统提供的功能来扩展Godot引擎功能的强大工具。

移动游戏货币化就是这样一个例子,因为它所需要的功能和能力并不属于游戏引擎的核心功能集:

  • 分析

  • 应用内购买

  • 收据验证

  • 安装跟踪

  • 广告

  • 视频广告

  • 交叉推广

  • 游戏中的软硬货币

  • 促销代码

  • A / B测试

  • 登录

  • 云保存

  • 排行榜和分数

  • 用户支持和反馈

  • 发布到Facebook,Twitter等。

  • 推送通知

Android plugin

虽然在Godot 3.2中引入了Android插件系统,但从Godot 3.2.2开始,Android插件系统得到了重大架构更新。新的插件系统与之前的插件系统是向后不兼容的,但在未来发布的3.2.x分支中,这两个系统都会保留功能。由于我们之前没有对Android插件系统进行版本更新,新的插件系统现在被标记为 v1 ,是现代Godot Android生态系统的起点。

注意: 在Godot 4.0中,以前的系统将被完全废弃和删除。

作为前提条件,请确保你了解如何为Android设置一个 自定义构建环境

odot Android插件的核心是一个 `Android归档库<https://developer.android.com/studio/projects/android-library#aar-contents>`_ ( aar 归档文件),其注意事项如下:

创建Android插件

前提条件: Android Studio 强烈建议作为创建Android插件的IDE使用。下面的说明假设你使用的是Android Studio。

  1. 按照 `这些说明<https://developer.android.com/studio/projects/android-library>`__ 为你的插件创建一个Android库模块。

  2. 将Godot引擎库作为依赖项添加到插件模块:

  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 文件。构建过程中可能会同时生成 debugreleaseaar 文件。根据你的需要,只选择一个版本(通常是 release 的版本)提供给你的用户。

    建议 aar 文件名符合以下模式: [PluginName]*.aar 其中 PluginName 是PascalCase中的插件名称(例如: GodotPayment.release.aar )。

  6. 创建一个Godot Android插件配置文件,帮助系统检测并加载你的插件:

    • 这配置文件必须是 gdap (例如: MyPlugin.gdap)。

    • 配置文件格式如下:

      [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"]
      

      config 部分和字段是必须的,定义如下:

      • 名称(name) :(插件的名称)

      • 二进制类型(binary_type) : 可以是 localremote 。类型影响 二进制(binary) 字段

      • 二进制(binary):

        • 如果 binary_typelocal ,那么这应该是插件 aar 文件的文件路径。

          • 文件路径可以是相对的(例如: MyPlugin.aar ),在这种情况下,它是相对于 res://android/plugins 目录的。

          • 它的文件路径可以是绝对路径:res://some_path/MyPlugin.aar.

        • 如果 binary_typeremote ,那么这应该是一个 `remote gradle二进制<https://developer.android.com/studio/build/dependencies#dependency-types>`_ (例如:org.godot.example:my-plugin:0.0.0 )的声明。

      dependencies 部分和字段是可选的,定义如下:

      • local: 包含插件所依赖的本地 .ar 二进制文件的文件路径列表。与 binary 字段类似(当 binary_typelocal 时),本地二进制文件的文件路径可以是相对的或绝对的。

      • remote: 包含插件的远程二进制gradle依赖列表。

      • custom_maven_repos: 包含一个URL列表,指定了插件的依赖关系所需的自定义maven仓库

加载和使用Android插件

将插件配置文件(例如: MyPlugin.gdap )和(如果有的话)它的本地二进制文件(例如: MyPlugin.aar )和对应的依赖移到Godot项目的 res://android/plugins 目录下。

Godot编辑器会自动解析 res://android/plugins 目录下的所有 .gdap 文件,并在 Plugins 部分的Android导出预设窗口中显示检测到的可切换插件列表。

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

从你的脚本中:

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

捆绑GDNative资源

安卓插件可以定义并提供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 core,Godot core将使用它们来加载和初始化捆绑的GDNative库。

故障排除

Godot在加载时崩溃

检查 adb logcat 是否存在可能的问题,然后:

  • 检查插件暴露的方法是否使用了下列Java类型。 voidbooleanintfloatjava.lang.Stringorg.godotengine.godot.Dictionaryint[]byte[]float[]java.lang.String[]

    • 暂时不支持更复杂的数据类型。