创建Android插件

创建Android插件

简介

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

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

分析
应用内购买
收据验证
安装跟踪
广告
视频广告
交叉推广
游戏中的软硬货币
促销代码
A / B测试
登录
云保存
排行榜和分数
用户支持和反馈
发布到Facebook,Twitter等.
推送通知

安卓插件

虽然在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 归档文件),其注意事项如下:

该库必须依赖Godot引擎库(godot-lib.<version>.<status>.aar).每一个Godot版本都有一个稳定的版本,可以在 `Godot下载页面<https://godotengine.org/download>`_ .
库必须在其清单文件中包含一个专门配置的 <meta-data> 标签.

创建Android插件

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

按照 `这些说明<https://developer.android.com/studio/projects/android-library>`__ 为你的插件创建一个Android库模块.
将Godot引擎库作为依赖项添加到插件模块:
- 从 `Godot下载页面<https://godotengine.org/download>`_ 下载Godot引擎库( godot-lib.<版本(version)>.<状态(status)>.arr )(例如: godot-lib.3.2.2.stable.arr ).
- 按照 `这些说明<https://developer.android.com/studio/projects/android-library#AddDependency>`__ 来添加Godot引擎库作为你的插件的依赖.
- 在插件模块的 build.gradle 文件中,将Godot引擎库的依赖行 implementation 改为 compileOnly .
在插件模块中创建一个新的类,并确保它扩展为 org.godotengine.godot.plugin.GodotPlugin .在运行时,它将被用于实例化一个单例对象,该对象将被Godot引擎用于加载、初始化和运行插件.
更新插件 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 是插件加载类的全称(包+类名).
为你的插件添加剩余的逻辑,并运行 gradlew build 命令来生成插件的 aar 文件.构建过程中可能会同时生成 debug 和 release 的 aar 文件.根据你的需要,只选择一个版本(通常是 release 的版本)提供给你的用户.

建议 aar 文件名符合以下模式: [PluginName]*.aar 其中 PluginName 是PascalCase中的插件名称(例如: GodotPayment.release.aar ).
创建一个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) : 可以是 local 或 remote .类型影响 二进制(binary) 字段
  - 二进制(binary):
    - 如果 binary_type 是 local ,那么这应该是插件 aar 文件的文件路径.
      
      文件路径可以是相对的(例如: MyPlugin.aar ),在这种情况下,它是相对于 res://android/plugins 目录的.
      
      它的文件路径可以是绝对路径:res://some_path/MyPlugin.aar.
    - 如果 binary_type 是 remote ,那么这应该是一个 `remote gradle二进制<https://developer.android.com/studio/build/dependencies#dependency-types>`_ (例如:org.godot.example:my-plugin:0.0.0 )的声明.
  dependencies 部分和字段是可选的,定义如下:
  - local: 包含插件所依赖的本地 .ar 二进制文件的文件路径列表.与 binary 字段类似(当 binary_type 为 local 时),本地二进制文件的文件路径可以是相对的或绝对的.
  - remote: 包含插件的远程二进制gradle依赖列表.
  - custom_maven_repos: 包含一个URL列表,指定了插件的依赖关系所需的自定义maven仓库

加载和使用Android插件

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

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

从你的脚本中:

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核心,核心将使用它们来加载和初始化捆绑的GDNative库.

参考方案

`Godot Oculus Mobile插件<https://github.com/GodotVR/godot_oculus_mobile>`_
- `捆绑的gdnative资源<https://github.com/GodotVR/godot_oculus_mobile/tree/master/plugin/src/main/assets/addons/godot_ovrmobile>`_
`Godot Google Play Billing插件<https://github.com/godotengine/godot-google-play-billing>`_

故障排除

Godot在加载时崩溃

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

检查插件暴露的方法是否使用了下列Java类型. void、boolean、int、float、java.lang.String、org.godotengine.godot.Dictionary、int[]、byte[]、float[]、java.lang.String[].
- 暂时不支持更复杂的数据类型.