Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Плагины 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.

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

1. Создайте модуль библиотеки Android, используя эти инструкции

2. Добавьте библиотеку Godot для Android в качестве зависимости, обновив gradle файл сборки модуля:

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

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

3. Создайте 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>`_.

4. Обновите файл плагина 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).

5. Создайте конфигурацию 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:

1. Обновите файл манифеста плагина:

   • Замените префикс org.godotengine.plugin.v1 на org.godotengine.plugin.v2

2. Обновите зависимость сборки библиотеки Godot для Android:

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

   • Или вы можете переключиться на предоставленную MavenCentral зависимость:

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

3. После обновления зависимости библиотеки Godot для Android синхронизируйте или соберите плагин и устраните любые ошибки компиляции:

   • Экземпляр Godot, предоставляемый GodotPlugin::getGodot(), больше не имеет доступа к ссылке android.content.Context. Вместо этого используйте GodotPlugin::getActivity().

4. Удалите файл(ы) конфигурации gdap и следуйте инструкциям в разделе Packaging a v2 Android plugin, чтобы настроить конфигурацию плагина.

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

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

1. Добавьте выходные двоичные файлы плагина в каталог плагина (например: в addons/<plugin_name>/)

2. Добавьте инструментальный скрипт для функциональности экспорта в каталог плагина (например: в 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.

3. Создайте 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 для быстрого тестирования.

1. Скопируйте выходной каталог плагина (addons/<plugin_name>) в каталог целевого проекта Godot

2. Откройте проект в редакторе Godot; Редактор должен обнаружить плагин

3. Перейдите в Project -> Project Settings... -> Plugins и убедитесь, что плагин включен

4. Установите шаблон сборки Android Godot, нажав Project -> Install Android Build Template...

5. Перейдите в Project -> Export...

6. В окне Export создайте Android export preset

7. В Android export preset прокрутите до Gradle Build и установите для параметра Use Gradle Build значение true

8. Обновите скрипты проекта по мере необходимости, чтобы получить доступ к функционалу плагина. Например:

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

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

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

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

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

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

• Примеры плагинов Godot для Android

• Шаблон плагина Godot для Android

• Шаблон плагина Android GDExtension

• Загрузчики Godot OpenXR

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

Упростите доступ к открытым 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, чтобы узнать, как это сделать.

Поддерживаемые типы данных

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 аварийно завершает работу при загрузке

Проверьте adb logcat на наличие возможных проблем.