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

Версія 1 (v1) системи плагінів Android була представлена в Godot 3 і сумісна з Godot 4.0 і 4.1. Ця версія дозволила розробникам розширити движок Godot за допомогою Java, Kotlin і нативної функціональності.

Починаючи з Godot 4.2, плагіни Android, побудовані на архітектурі v1, більше не підтримуються. Натомість Godot 4.2 представляє нову архітектуру версії 2 (v2) для плагінів Android.

v2 Архітектура

Примітка

Плагін Godot для Android використовує Gradle build system.

Спираючись на попередню архітектуру v1, плагіни Android продовжують походити з бібліотеки архівів Android.

За своєю суттю плагін Godot Android v2 — це бібліотека Android із залежністю від Godot Android library та спеціального маніфесту бібліотеки Android.

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

  • API платформи Android

  • Бібліотеки Android

  • Бібліотеки Kotlin і Java

  • Власні бібліотеки (через JNI)

  • Бібліотеки GDExtension

Кожен плагін має клас ініціалізації, що походить від GodotPlugin класу, який надається Godot Android library.

Клас GodotPlugin надає API для доступу до запущеного екземпляра Godot і підключення до його життєвого циклу. Він завантажується під час виконання за допомогою механізму Godot.

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

Плагіни Android v1 вимагали спеціального файлу конфігурації gdap, який використовувався редактором Godot для їх виявлення та завантаження. Однак цей підхід мав кілька недоліків, основними з яких були те, що йому бракувало гнучкості та відходив від «існуючого формату Godot EditorExportPlugin, потоку доставки та встановлення <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html>`_.

Цю проблему для плагінів Android версії 2 було вирішено шляхом відмови від механізму пакування та налаштування gdap на користь існуючого формату пакування Godot EditorExportPlugin. API EditorExportPlugin, у свою чергу, було розширено для належної підтримки плагінів Android.

Створення плагіна v2 для Android

Шаблон проекту github надається на https://github.com/m4gr3d/Godot-Android-Plugin-Template як швидкий старт для створення плагінів Godot Android для Godot 4.2+. Ви можете слідувати шаблону README, щоб налаштувати власний проект плагіна Godot для Android.

Щоб краще зрозуміти, ось розбивка кроків, використаних для створення шаблону проекту:

  1. Створіть модуль бібліотеки Android за допомогою цих інструкцій

  2. Додайте бібліотеку Godot для Android як залежність, оновивши файл збірки модуля gradle <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/build.gradle.kts#L42>`_:

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

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

  1. Створити 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, клас ініціалізації має повертати набір сигналів, які використовуються шляхом перевизначення GodotPlugin::getPluginSignals(). Щоб надсилати сигнали, плагін може використовувати метод ` GodotPlugin::emitSignal(...) <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L317>`_.

  2. Оновіть файл плагіна 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 — це повна назва компонента (пакет + назва класу) класу ініціалізації плагіна (наприклад: org.godotengine.plugin.android.template.GodotAndroidPlugin).

  1. Створіть конфігурацію EditorExportPlugin, щоб запакувати плагін. Кроки, використані для створення конфігурації, можна побачити в розділі Пакування плагіна Android v2.

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

Подібно до підтримки GDNative у плагінах Android версії 1, плагіни Android версії 2 підтримують можливість інтегрувати можливості GDExtension.

Шаблон проекту github надається за адресою https://github.com/m4gr3d/GDExtension-Android-Plugin-Template як швидкий старт для створення плагінів GDExtension Android для Godot 4.2+. Ви можете переглянути README шаблону, щоб налаштувати власний проект плагіна Godot для Android.

Перенесення плагіна Android v1 на v2

Виконайте наведені нижче дії, якщо у вас є плагін Android версії 1, який ви хочете перенести на версію 2:

  1. Оновіть файл маніфесту плагіна:

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

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

    • Ви можете продовжувати використовувати двійковий файл godot-lib.<version>.<status>.aar зі сторінки завантаження Godot, якщо це ваші переваги. Переконайтеся, що його оновлено до останньої стабільної версії.

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

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

  1. Після оновлення залежності бібліотеки Godot Android синхронізуйте або створіть плагін і виправте будь-які помилки компіляції:

    • Екземпляр Godot, що надається GodotPlugin::getGodot(), більше не має доступу до посилання android.content.Context. Натомість використовуйте GodotPlugin::getActivity().

  2. Видаліть файл(и) конфігурації gdap і дотримуйтесь інструкцій у розділі Пакування плагіна v2 Android, щоб налаштувати конфігурацію плагіна.

Пакування плагіна v2 для Android

Як згадувалося, плагін версії 2 для Android тепер надається редактору Godot як плагін EditorExportPlugin, тому він має багато одних і тих самих кроків пакування.

  1. Додайте вихідні двійкові файли плагіна в каталог плагіна (наприклад, у addons/<plugin_name>/)

  2. Додайте скрипт інструмента для функції експорту в каталозі плагіна (наприклад, у addons/<назва_плагіна>/)

    • Створений скрипта має бути скриптою @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.

  1. Створіть 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.

Для довідки, ось структура папок для шаблону проекту плагіна Android GDExtension. Під час збирання вміст каталогу 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 експортуються двійковими файлами плагіна Android AAR.

Для плагінів GDExtension для Android клас ініціалізації плагіна має перевизначати GodotPlugin::getPluginGDExtensionLibrariesPaths(), і повертає шляхи до конфігураційних файлів бібліотек GDExtension (*.gdextension).

Шляхи мають бути відносними до каталогу assets бібліотеки Android. Під час виконання плагін надасть ці шляхи механізму Godot, який використовуватиме їх для завантаження та ініціалізації бібліотек GDExtension, що входять у комплект.

Використання плагіна v2 Android

Примітка

  • Потрібна версія Godot 4.2 або вище

  • Плагін версії 2 для Android вимагає використання процесу збирання Gradle.

  • Надані шаблони проектів github містять демонстраційні проекти Godot для швидкого тестування.

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

  2. Відкрийте проект у редакторі Godot; редактор повинен виявити плагін

  3. Перейдіть до Проект -> Налаштування проекту... -> Плагіни та переконайтеся, що плагін увімкнено

  4. Установіть шаблон збірки Godot для Android, натиснувши Проект -> Установити шаблон збірки Android...

  5. Перейдіть до Проект -> Експорт...

  6. У вікні Експорт створіть попереднє налаштування експорту Android

  7. У стандарті експорту Android прокрутіть до Gradle Build і встановіть Use Gradle Build значення true

  8. Оновіть скрипти проєкту за потреби, щоб отримати доступ до функціональності плагіна. Наприклад:

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

  1. Підключіть пристрій Android до своєї машини та запустіть на ньому проект

Використання плагіна Android v2 як бібліотеки Android

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

Якщо ви націлюєтеся на цей випадок використання, обов’язково включите додаткові вказівки щодо включення двійкових файлів AAR (наприклад, спеціальні доповнення до маніфесту програми Android).

Еталонні реалізації

Поради та вказівки

Спростіть доступ до доступних Java/Kotlin API

Щоб спростити доступ до відкритих 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

Якщо ви плануєте використовувати функціональні можливості GDExtension у редакторі Godot, рекомендовано, щоб рідні двійкові файли GDExtension були скомпільовані не лише для Android, а й для ОС, у якій розробники/користувачі мають намір запускати редактор Godot. Інакше це може перешкодити розробникам/користувачам писати код, який отримує доступ до плагіна з редактора Godot.

Це може передбачати створення фіктивних плагінів для головної ОС, щоб API було опубліковано в редакторі. Ви можете використати godot-cpp-template шаблон github, щоб дізнатися, як це зробити.

Підтримувані типи даних

Підтримуються всі типи даних. Поширені типи зіставляються з їхніми еквівалентами Godot (наприклад, String[] зіставляється з PackedStringArray()), але для інших типів можна використовувати JavaClassWrapper для доступу до нього.

Godot падає під час завантаження

Перевірте adb logcat на наявність можливих проблем.