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.

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

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

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

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

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

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

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

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

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

Клас GodotPlugin надає API для доступу до запущеного екземпляра 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 модуля:

   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, клас ініціалізації має повертати набір сигналів, які використовуються шляхом перевизначення 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 file з такими метаданими:

   <meta-data
       android:name="org.godotengine.plugin.v2.[PluginName]"
       android:value="[plugin.init.ClassFullName]" />
   

Де:

• PluginName - це назва плагіна

• plugin.init.ClassFullName — це повна назва компонента (пакет + назва класу) класу ініціалізації плагіна (наприклад: org.godotengine.plugin.android.template.GodotAndroidPlugin).

5. Створіть конфігурацію 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")
     }
     

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

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

4. Видаліть файл(и) конфігурації 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
     

   • Ось набір API EditorExportPlugin, який найбільше підходить для використання в цьому сценарії інструменту:

     • _supports_platform: повертає true, якщо плагін підтримує дану платформу. Для плагінів Android це має повертати true, якщо platform має значення EditorExportPlatformAndroid

     • _get_android_libraries: отримати локальні шляхи двійкових файлів бібліотек Android (файли AAR) ), що надається плагіном

     • _get_android_dependencies: отримати набір залежностей Android maven (наприклад: org .godot.example:my-plugin:0.0.0), що надається плагіном

     • _get_android_dependencies_maven_repos: отримати URL-адреси сховищ maven для залежності android, надані _get_android_dependencies

     • _get_android_manifest_activity_element_contents: оновити вміст ` <activity>` у створеному маніфесті Android

     • _get_android_manifest_application_element_contents: оновити вміст ` <application>` у створеному маніфесті Android

     • _get_android_manifest_element_contents: оновити вміст <manifest > у створеному маніфесті Android

     Методи _get_android_manifest_* дозволяють плагіну автоматично вносити зміни до маніфесту програми, які зберігаються під час оновлення редактора Godot, вирішуючи давню проблему з плагінами Android версії 1.

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 ми виконуємо ті самі кроки, що й для Packaging a v2 Android plugin і додаємо 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"))
   

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

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

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

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

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

• Приклади плагінів Godot Android

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

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

• Godot OpenXR Вантажники

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

Спростіть доступ до доступних 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 падає під час завантаження

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

• Перевірте, чи методи, надані плагіном, використовували такі типи Java: void, boolean, int, float, java.lang.String, `` org.godotengine.godot.Dictionary``, int[], byte[], float[], java.lang.String[].

• Більш складні типи даних наразі не підтримуються.