Плагины Godot для Android

Введение

Плагины Android — это мощные инструменты для расширения возможностей движка Godot путем использования функциональных возможностей, предоставляемых платформами и экосистемой Android.

Например, в Godot 4 плагины Android используются для поддержки нескольких XR-платформ на базе Android, не перегружая основную кодовую базу кодом или двоичными файлами, специфичными для конкретного поставщика.

Android плагин

Version 1 (v1) системы плагинов Android была представлена в Godot 3 и совместима с Godot 4.0 и 4.1. Эта версия позволила разработчикам дополнить движок Godot функциями Java, Kotlin и нативными функциями.

Начиная с Godot 4.2, плагины для Android, основанные на архитектуре v1, объявлены устаревшими. Вместо этого в Godot 4.2 представлена новая архитектура Version 2 (v2) для плагинов Android.

v2 Архитектура

Примечание

Плагин Godot для Android использует Gradle build system.

Плагины Android, созданные на основе предыдущей архитектуры v1, по-прежнему создаются на основе библиотеки архива Android.

По своей сути плагин Godot Android v2 представляет собой библиотеку Android с зависимостью от Godot Android library и пользовательского манифеста библиотеки Android.

Такая архитектура позволяет плагинам Android расширять функциональность движка с помощью:

API-ы платформы Android
Android библиотеки
Kotlin и Java библиотеки
Нативные библиотеки (через JNI)
Библиотеки GDExtension

Каждый плагин имеет класс init, расширяющийся от класса GodotPlugin, который предоставляется Godot Android library.

Класс GodotPlugin предоставляет API для доступа к запущенному экземпляру Godot и подключения к его жизненному циклу. Он загружается во время выполнения движком Godot.

Формат упаковки v2

Для плагинов Android версии v1 требовался специальный конфигурационный файл gdap, который Godot Editor использовал для их обнаружения и загрузки. Однако этот подход имел ряд недостатков, главными из которых были недостаточная гибкость и отход от существующего формата Godot EditorExportPlugin, процесса доставки и установки.

Для плагинов Android версии 2 эта проблема была решена путём отказа от механизма упаковки и настройки gdap в пользу существующего формата упаковки Godot EditorExportPlugin. API EditorExportPlugin, в свою очередь, был расширен для корректной поддержки плагинов Android.

Создание v2 Android плагина

Шаблон проекта GitHub предоставлен по адресу https://github.com/m4gr3d/Godot-Android-Plugin-Template в качестве быстрого старта для создания плагинов Godot для Android 4.2+. Вы можете воспользоваться файлом README для шаблона <https://github.com/m4gr3d/Godot-Android-Plugin-Template#readme>`_, чтобы настроить свой собственный проект плагина Godot для Android.

Для лучшего понимания ниже приводится описание шагов, используемых для создания шаблона проекта:

Создайте модуль библиотеки Android, используя эти инструкции
Добавьте библиотеку Godot для Android в качестве зависимости, обновив gradle файл сборки модуля:
dependencies { implementation("org.godotengine:godot:4.2.0.stable") }

Библиотека Godot для Android размещена на MavenCentral и обновляется для каждого выпуска.

Создайте GodotAndroidPlugin, класс инициализации для плагина, расширяющего GodotPlugin.
- Если плагин предоставляет методы Kotlin или Java для вызова из GDScript, они должны быть аннотированы @UsedByGodot. Имя, вызываемое из GDScript, должно точно совпадать с именем метода. Приведение snake_case к camelCase не возможно. Например, из GDScript:
  if Engine.has_singleton("MyPlugin"): var singleton = Engine.get_singleton("MyPlugin") print(singleton.myPluginFunction("World"))
- Если плагин использует signals, класс init должен возвращать набор сигналов, используемых при переопределении GodotPlugin::getPluginSignals().Для подачи сигналов плагин может использовать метод `GodotPlugin::emitSignal(...)<https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L317>`_.
Обновите файл плагина AndroidManifest.xml https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/src/main/AndroidManifest.xml, добавив следующие метаданные:
<meta-data android:name="org.godotengine.plugin.v2.[PluginName]" android:value="[plugin.init.ClassFullName]" />

Где:

PluginName — имя плагина

plugin.init.ClassFullName — это полное имя компонента (пакета + имя класса) класса init плагина (например: org.godotengine.plugin.android.template.GodotAndroidPlugin).

Создайте конфигурацию EditorExportPlugin для упаковки плагина. Шаги по созданию конфигурации можно найти в разделе Упаковка плагина Android v2.

Создание плагина Android v2 с возможностями GDExtension

Подобно поддержке GDNative в плагинах Android v1, плагины Android v2 поддерживают возможность интеграции возможностей GDExtension.

Шаблон проекта GitHub доступен по адресу https://github.com/m4gr3d/GDExtension-Android-Plugin-Template в качестве руководства по быстрому началу работы над созданием плагинов GDExtension для Android для Godot 4.2 и более поздних версий. Чтобы настроить свой собственный проект плагина Godot для Android, ознакомьтесь с файлом README к шаблону <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template#readme>`_.

Мигрирование v1 Android плагина в v2

Используйте следующие шаги, если хотите мигрировать ваш v1 Android плагин в v2:

Обновите файл манифеста плагина:
- Замените префикс org.godotengine.plugin.v1 на org.godotengine.plugin.v2
Обновите зависимость сборки библиотеки Godot для Android:
- Вы можете продолжать использовать исполняемый файл godot-lib.<version>.<status>.aar со страницы загрузки Godot <https://godotengine.org/download>`_, если вам так удобнее. Убедитесь, что он обновлён до последней стабильной версии.
- Или вы можете переключиться на предоставленную MavenCentral зависимость:

dependencies {
    implementation("org.godotengine:godot:4.2.0.stable")
}

После обновления зависимости библиотеки Godot для Android синхронизируйте или соберите плагин и устраните любые ошибки компиляции:
- Экземпляр Godot, предоставляемый GodotPlugin::getGodot(), больше не имеет доступа к ссылке android.content.Context. Вместо этого используйте GodotPlugin::getActivity().
Удалите файл(ы) конфигурации gdap и следуйте инструкциям в разделе Packaging a v2 Android plugin, чтобы настроить конфигурацию плагина.

Упаковка плагина Android v2

Как уже упоминалось, плагин Android v2 теперь предоставляется Редактору Godot в виде плагина EditorExportPlugin, поэтому он имеет много общих этапов упаковки.

Добавьте выходные двоичные файлы плагина в каталог плагина (например: в addons/<plugin_name>/)
Добавьте инструментальный скрипт для функциональности экспорта в каталог плагина (например: в addons/<plugin_name>/)
- Созданный скрипт должен быть @tool скриптом, иначе он не будет работать корректно
- Скрипт инструмента экспорта используется для настройки плагина Android и его подключения к процессу экспорта в редакторе Godot. Он должен выглядеть примерно так:

@tool
extends EditorPlugin

# A class member to hold the editor export plugin during its lifecycle.
var export_plugin : AndroidExportPlugin

func _enter_tree():
    # Initialization of the plugin goes here.
    export_plugin = AndroidExportPlugin.new()
    add_export_plugin(export_plugin)


func _exit_tree():
    # Clean-up of the plugin goes here.
    remove_export_plugin(export_plugin)
    export_plugin = null


class AndroidExportPlugin extends EditorExportPlugin:
    # Plugin's name.
    var _plugin_name = "<plugin_name>"

    # Specifies which platform is supported by the plugin.
    func _supports_platform(platform):
        if platform is EditorExportPlatformAndroid:
            return true
        return false

    # Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
    func _get_android_libraries(platform, debug):
        if debug:
            return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
        else:
            return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])

    # Return the plugin's name.
    func _get_name():
        return _plugin_name


- Here are the set of `EditorExportPlugin APIs <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ most relevant to use in this tool script:

    - `_supports_platform <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-supports-platform>`_: returns ``true`` if the plugin supports the given platform. For Android plugins, this must return ``true`` when ``platform`` is `EditorExportPlatformAndroid <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html>`_
    - `_get_android_libraries <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-libraries>`_: retrieve the local paths of the Android libraries binaries (AAR files) provided by the plugin
    - `_get_android_dependencies <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies>`_: retrieve the set of Android maven dependencies (e.g: `org.godot.example:my-plugin:0.0.0`) provided by the plugin
    - `_get_android_dependencies_maven_repos <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies-maven-repos>`_: retrieve the urls of the maven repos for the android dependencies provided by ``_get_android_dependencies``
    - `_get_android_manifest_activity_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-activity-element-contents>`_: update the contents of the `<activity>` element in the generated Android manifest
    - `_get_android_manifest_application_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-application-element-contents>`_: update the contents of the `<application>` element in the generated Android manifest
    - `_get_android_manifest_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-element-contents>`_: update the contents of the `<manifest>` element in the generated Android manifest

    The ``_get_android_manifest_*`` methods allow the plugin to automatically provide changes
    to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins.

Создайте plugin.cfg. Это INI-файл с метаданными вашего плагина:

[plugin]

name="<plugin_name>"
description="<plugin_description>"
author="<plugin_author>"
version="<plugin_version>"
script="<relative_path_to_the_export_tool_script>"

Для справки, вот структура папок для шаблона проекта плагина Godot для Android. Во время сборки содержимое каталога export_scripts_template, а также сгенерированные двоичные файлы плагина копируются в каталог addons/<plugin_name>:

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file

Упаковка плагина Android v2 с возможностями GDExtension

Для GDExtension мы выполняем те же шаги, что и для Упаковки плагина Android v2 и добавляем файл конфигурации GDExtension в то же место, что и plugin.cfg.

Для справки, вот структура папок для шаблона проекта плагина GDExtension для Android. Во время сборки содержимое каталога export_scripts_template, а также сгенерированные двоичные файлы плагина копируются в каталог addons/<plugin_name>:

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file
|
+--plugin.gdextension       # GDExtension config file

Вот как должен выглядеть конфигурационный файл plugin.gdextension:

[configuration]

entry_symbol = "plugin_library_init"
compatibility_minimum = "4.2"
android_aar_plugin = true

[libraries]

android.debug.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/debug/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
android.release.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/release/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
...

Обратите внимание на поле android_aar_plugin, которое указывает, что этот модуль GDExtension предоставляется как часть плагина Android v2. В процессе экспорта это укажет редактору Godot, что собственные общие библиотеки GDExtension экспортируются двоичными файлами AAR плагина Android.

Для плагинов Android GDExtension класс init плагина должен переопределять GodotPlugin::getPluginGDExtensionLibrariesPaths(), и вернуть пути к конфигурационным файлам библиотек GDExtension, входящим в комплект поставки (*.gdextension).

Пути должны быть указаны относительно каталога assets библиотеки Android. Во время выполнения плагин предоставит эти пути движку Godot, который будет использовать их для загрузки и инициализации встроенных библиотек GDExtension.

Использование v2 Android плагина

Примечание

Необходим Godot 4.2 и выше
Для плагина Android v2 требуется использование процесса сборки Gradle.
Предоставленные шаблоны проектов GitHub включают демонстрационные проекты Godot для быстрого тестирования.

Скопируйте выходной каталог плагина (addons/<plugin_name>) в каталог целевого проекта Godot
Откройте проект в редакторе Godot; Редактор должен обнаружить плагин
Перейдите в Project -> Project Settings... -> Plugins и убедитесь, что плагин включен
Установите шаблон сборки Android Godot, нажав Project -> Install Android Build Template...
Перейдите в Project -> Export...
В окне Export создайте Android export preset
В Android export preset прокрутите до Gradle Build и установите для параметра Use Gradle Build значение true
Обновите скрипты проекта по мере необходимости, чтобы получить доступ к функционалу плагина. Например:

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

Подключите Android-устройство к своему компьютеру и запустите на нем проект

Использование v2 Android плагина как Android библиотеку

Поскольку они также являются библиотеками Android, плагины Godot v2 для Android можно извлечь из упаковки EditorExportPlugin и предоставить в виде необработанных двоичных файлов AAR для использования в качестве библиотек вместе с Godot Android library в приложениях Android.

Если вы ориентируетесь на этот вариант использования, обязательно включите дополнительные инструкции о том, как следует включать двоичные файлы AAR (например, пользовательские дополнения к манифесту приложения Android).

Референтные реализации

Советы и рекомендации

Упростите доступ к открытым API Java/Kotlin

Чтобы упростить доступ к открытым API Java/Kotlin в редакторе Godot, рекомендуется предоставить один (или несколько) классов-оболочек gdscript, с которыми смогут взаимодействовать пользователи вашего плагина.

Например:

class_name PluginInterface extends Object

## Interface used to access the functionality provided by this plugin.

var _plugin_name = "GDExtensionAndroidPluginTemplate"
var _plugin_singleton

func _init():
    if Engine.has_singleton(_plugin_name):
        _plugin_singleton = Engine.get_singleton(_plugin_name)
    else:
        printerr("Initialization error: unable to access the java logic")

## Print a 'Hello World' message to the logcat.
func helloWorld():
    if _plugin_singleton:
        _plugin_singleton.helloWorld()
    else:
        printerr("Initialization error")

Поддержка использования функциональности GDExtension в Godot Editor

Если вы планируете использовать функциональность GDExtension в редактор Godot, рекомендуется скомпилировать его собственные двоичные файлы не только для Android, но и для ОС, на которой разработчики/пользователи планируют запустить редактор Godot. В противном случае разработчики/пользователи не смогут писать код, обращающийся к плагину из редактора Godot.

Это может потребовать создания фиктивных плагинов для хостовой ОС, чтобы API было доступно в редакторе. Вы можете использовать шаблон godot-cpp-template на GitHub, чтобы узнать, как это сделать.

Supported data types

All data types are supported. Common types are mapped to their Godot equivalents (for example, String[] is mapped to PackedStringArray()), but for other types, you can use JavaClassWrapper to access it.

Godot аварийно завершает работу при загрузке

Check adb logcat for possible problems.