Android библиотека в Godot

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

• Возможность интеграции системы сборки Gradle в редактор Godot, что позволяет использовать больше компонентов экосистемы Android, таких как библиотеки и инструменты

• Возможность сделать движок портативным и встраиваемым:

  • Ключевой фактор, обеспечивающий возможность порта Godot Editor на устройства Android и мобильные устройства XR

  • Ключ к обеспечению интеграции и повторного использования возможностей 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, что позволяет разработчикам использовать проверенный и надежный код и библиотеки, которые лучше подходят для решения конкретной задачи.

Компонент хостинга отвечает за управление жизненным циклом движка через API-ы Godot для Android. Эти API-ы также можно использовать для обеспечения двунаправленной связи между хостом и встроенным экземпляром Godot, что обеспечивает более точный контроль над желаемым взаимодействием.

Мы демонстрируем, как это делается, на примере приложения для Android, которое встраивает Godot Engine в качестве представления Android и использует его для рендеринга 3D-моделей glTF.

Пример приложения GLTF Viewer использует компонент Android RecyclerView для создания списка элементов glTF, заполненного из набора Kenney's Food Kit. При выборе элемента из списка логика приложения взаимодействует со встроенным движком Godot Engine для визуализации выбранного элемента glTF в виде 3D-модели.

Исходный код примера приложения можно найти на GitHub. Следуйте инструкциям в файле README, чтобы собрать и установить его.

Ниже мы подробно описываем этапы создания приложения GLTF Viewer.

Предупреждение

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

Предупреждение

События автоматического изменения размера/ориентации не поддерживаются и могут привести к сбою. Вы можете отключить эти события:

• Путем фиксации определенной ориентации с помощью атрибута android:screenOrientation.

• Объявив, что Activity будет обрабатывать эти события конфигурации с помощью атрибута android:configChanges.

1. Создание приложения (app) для 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 в Project Settings.

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

  • Хост Activity должен реализовывать интерфейс GodotHost

  • В примере приложения для организации пользовательского интерфейса используются Фрагменты, поэтому в нем используется компонент фрагмента 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, компонент Activity, который можно расширить для автоматического размещения и управления экземпляром Godot Engine.

В качестве альтернативы приложения могут напрямую создавать экземпляр Godot, размещать его и управлять им самостоятельно.

• Используя GodotHost#getHostPlugins(...), пример приложения создает экземпляр GodotPlugin среды выполнения, который используется для отправки 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. Создайте проект

Примечание

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

Мы используем эту архитектуру, чтобы связать наше приложение Android и проект Godot, создав проект Godot в каталоге assets приложения Android.

Обратите внимание, что проект Godot также можно создать в отдельном каталоге и экспортировать его как файл 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

  • Для справки см. app's 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 соберите и запустите приложение (app) для Android. При правильной настройке host Activity инициализирует встроенный Godot Engine при запуске. Godot Engine проверит каталог assets на наличие файлов проекта для загрузки (если не настроен поиск main pack), а затем приступит к запуску проекта.

Пока приложение работает на устройстве, вы можете проверить Android logcat, чтобы исследовать любые ошибки или сбои.

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