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

Godot Engine для платформ Android розроблено для використання як бібліотеки Android. Ця архітектура забезпечує кілька ключових функцій на платформах Android:

• Можливість інтегрувати систему збирання Gradle у редактор Godot, що надає можливість використовувати більше компонентів екосистеми Android, таких як бібліотеки та інструменти

• Можливість зробити двигун портативним і вбудовуваним:

  • Увімкніть порт редактора Godot для Android і мобільних пристроїв XR

  • Ключ у дозволі інтеграції та повторного використання можливостей Godot в існуючій кодовій базі

Нижче ми описуємо деякі варіанти використання та сценарії, які дозволяє ця архітектура.

Використання бібліотеки Godot Android

Бібліотека Godot Android упакована як архівний файл AAR і розміщена на MavenCentral разом із її документацією.

Він надає доступ до API Godot і можливостей на платформах Android для наступних невичерпних варіантів використання.

Плагіни Godot для Android

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

Плагін Android — це бібліотека Android із залежністю від бібліотеки Godot Android, яку плагін використовує для інтеграції в життєвий цикл двигуна та доступу до API Godot, надаючи йому потужні можливості, такі як підтримка GDExtension, яка дозволяє оновлювати/змінювати поведінку двигуна за потреби.

Для отримання додаткової інформації див. Godot Android plugins.

Вбудовування Godot в існуючі проекти Android

Godot Engine можна вбудувати в існуючі програми або бібліотеки Android, дозволяючи розробникам використовувати зрілий і перевірений у боях код і бібліотеки, які краще підходять для конкретного завдання.

Компонент хостингу відповідає за керування життєвим циклом двигуна через Android API Godot. Ці API також можна використовувати для забезпечення двонаправленого зв’язку між хостом і вбудованим екземпляром Godot, що дозволяє краще контролювати бажаний досвід.

Ми демонструємо, як це робиться, використовуючи зразок програми для Android, яка вбудовує Godot Engine як вигляд Android і використовує його для візуалізації 3D-моделей glTF.

Зразок програми GLTF Viewer використовує компонент Android RecyclerView для створення списку елементів glTF, заповненого з Kenney's Food Комплект набору. Коли вибрано елемент у списку, логіка програми взаємодіє з вбудованим механізмом Godot Engine, щоб відобразити вибраний елемент glTF як 3D-модель.

Зразок вихідного коду програми можна знайти on GitHub. Дотримуйтесь інструкцій на its README побудувати та встановити його.

Нижче ми розбираємо етапи створення програми GLTF Viewer.

Попередження

Наразі для кожного процесу підтримується лише один екземпляр Godot Engine. Ви можете налаштувати процес, у якому виконується Android Activity, за допомогою атрибута android:process.

Попередження

Події автоматичної зміни розміру/конфігурації орієнтації не підтримуються та можуть призвести до збою. Ви можете вимкнути ці події:

• За допомогою фіксації певної орієнтації за допомогою атрибута android:screenOrientation.

• Оголосивши, що Activity оброблятиме ці події конфігурації за допомогою атрибута android:configChanges.

1. Створіть додаток для Android

Примітка

Зразок програми для Android було створено за допомогою Android Studio з використанням Gradle як системи збірки.

Екосистема Android надає численні інструменти, IDE, системи побудови для створення програм Android, тож не соромтеся використовувати те, що ви знаєте, і відповідним чином оновлювати наведені нижче кроки (внесок у цю документацію також вітається!).

• Налаштуйте проект програми Android. Це може бути абсолютно новий порожній проект або існуючий проект

• Додайте залежність maven для бібліотеки Godot Android

  • Якщо ви використовуєте gradle, додайте наступне до розділу dependency файлу збірки gradle програми. Обов’язково оновіть <version> до останньої версії бібліотеки Godot Android:

  implementation("org.godotengine:godot:<version>")
  

• Якщо ви використовуєте gradle, додайте таку конфігурацію aaptOptions у розділ android > defaultConfig файлу збірки gradle програми. Це дозволяє gradle включати приховані каталоги Godot під час створення двійкового файлу програми.

  • Якщо ваша система збірки не підтримує включення прихованих каталогів, ви можете налаштувати проект Godot так, щоб він не використовував приховані каталоги, скасувавши прапорець Application > Config > Use Hidden Project Data Directory в налаштуваннях проекту.

android {

  defaultConfig {
      // The default ignore pattern for the 'assets' directory includes hidden files and
      // directories which are used by Godot projects, so we override it with the following.
      aaptOptions {
          ignoreAssetsPattern "!.svn:!.git:!.gitignore:!.ds_store:!*.scc:<dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"
      }
    ...

• Створіть/оновіть програму Activity, яка розміщуватиме примірник Godot Engine. Для прикладу програми це MainActivity

  • Активність хоста має реалізовувати інтерфейс GodotHost

  • Зразок програми використовує Fragments для організації свого інтерфейсу користувача, тому він використовує GodotFragment, компонент фрагмента, наданий бібліотекою Godot Android для автоматичного розміщення та керування примірником Godot Engine.

  private var godotFragment: GodotFragment? = null
  
  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
  
      setContentView(R.layout.activity_main)
  
      val currentGodotFragment = supportFragmentManager.findFragmentById(R.id.godot_fragment_container)
      if (currentGodotFragment is GodotFragment) {
          godotFragment = currentGodotFragment
      } else {
          godotFragment = GodotFragment()
          supportFragmentManager.beginTransaction()
              .replace(R.id.godot_fragment_container, godotFragment!!)
              .commitNowAllowingStateLoss()
      }
  
      ...
  

Примітка

Бібліотека Godot Android також надає GodotActivity, дію компонент, який можна розширити для автоматичного розміщення та керування примірником Godot Engine.

Крім того, програми можуть безпосередньо створювати екземпляр Godot, розміщувати та керувати ним самостійно.

• Використання GodotHost#getHostPlugins(...), зразок програми створює екземпляр ` GodotPlugin під час виконання <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/AppPlugin.kt>`_ який використовується для надсилання signals до логіки gdscript

  • Середовище виконання GodotPlugin також може використовуватися логікою gdscript для доступу до методів JVM. Для отримання додаткової інформації див. Godot Android plugins.

• Додайте будь-яку додаткову логіку, яку використовуватиме ваша програма

  • Для зразка програми це включає додавання фрагмента ItemsSelectionFragment (і пов’язаних класів), фрагмента, який використовується для створити та показати список елементів glTF

• Відкрийте файл AndroidManifest.xml і за потреби налаштуйте орієнтацію за допомогою android:screenOrientation атрибута

  • За потреби вимкніть автоматичне змінення розміру/конфігурації орієнтації за допомогою атрибута android:configChanges

<activity android:name=".MainActivity"
    android:screenOrientation="fullUser"
    android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
    android:exported="true">

    ...
</activity>

2. Створіть проект Godot

Примітка

На Android файли проекту Godot експортуються до каталогу assets згенерованого двійкового файлу apk.

Ми використовуємо цю архітектуру, щоб зв’язати нашу програму Android і проект Godot разом, створивши проект Godot у каталозі assets програми Android.

Зауважте, що також можна створити проект Godot в окремому каталозі та експортувати його як a Файл PCK або ZIP до каталогу assets програми Android. Використання цього підходу вимагає передачі аргументу --main-pack <pck_or_zip_filepath_relative_to_assets_dir> розміщеному екземпляру Godot Engine за допомогою GodotHost#getCommandLine().

Приклад:

@Override
public List<String> getCommandLine(){
    List<String> results = new ArrayList<>();
    results.addAll(super.getCommandLine());
    results.add("--main-pack");
    results.add("res://foo.pck");
    return results;
}

Наведені нижче інструкції та зразок програми відповідають першому підходу створення проекту Godot у каталозі assets програми Android.

• Як зазначено в примітці вище, відкрийте редактор Godot і створіть проект Godot безпосередньо (без підпапки) у каталозі assets проекту програми Android

  • Для довідки перегляньте приклад програми Godot project

• Налаштуйте проект Godot за бажанням

  • Переконайтеся, що орієнтація, встановлена для проекту Godot, відповідає у маніфесті програми Android

  • Для Android переконайтеся, що textures/vram_compression/import_etc2_astc має значення true

• За потреби оновіть логіку сценарію проекту Godot

  • Для зразка програми логіка сценарію запитує для середовища виконання Екземпляр GodotPlugin і використовує його для реєстрації сигналів, що надсилаються логікою програми

  • Логіка програми запускає сигнал кожного разу, коли елемент вибирається в списку. Сигнал містить шлях до файлу моделі glTF, який використовується логікою gdscript для відтворення моделі.

  extends Node3D
  
  # Reference to the gltf model that's currently being shown.
  var current_gltf_node: Node3D = null
  
  func _ready():
    # Default asset to load when the app starts
    _load_gltf("res://gltfs/food_kit/turkey.glb")
  
    var appPlugin = Engine.get_singleton("AppPlugin")
    if appPlugin:
      print("App plugin is available")
  
      # Signal fired from the app logic to update the gltf model being shown
      appPlugin.connect("show_gltf", _load_gltf)
    else:
      print("App plugin is not available")
  
  
  # Load the gltf model specified by the given path
  func _load_gltf(gltf_path: String):
    if current_gltf_node != null:
      remove_child(current_gltf_node)
  
    current_gltf_node = load(gltf_path).instantiate()
  
    add_child(current_gltf_node)
  

3. Створіть і запустіть додаток

Після завершення налаштування проекту Godot створіть і запустіть програму Android. Якщо налаштовано правильно, хост Activity ініціалізує вбудований Godot Engine під час запуску. Godot Engine перевірить каталог assets для завантаження файлів проекту (якщо не налаштовано шукати main pack), і продовжить виконання проекту.

Коли програма працює на пристрої, ви можете перевірити Android logcat, щоб дослідити будь-які помилки чи збої.

Для довідки перегляньте інструкції зі збирання та встановлення прикладу програми GLTF Viewer.