Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Godot Android-Plugins

Einführung

Android-Plugins sind leistungsstarke Werkzeuge zur Erweiterung der Fähigkeiten der Godot-Engine, indem sie die von Android-Plattform und -Ökosystem bereitgestellten Funktionen nutzen.

In Godot 4 werden beispielsweise Android-Plugins verwendet, um mehrere Android-basierte XR-Plattformen zu unterstützen, ohne die Kern-Codebasis mit herstellerspezifischem Code oder Binärdateien zu belasten.

Android-Plugins

Version 1 (v1) des Android-Plugin-Systems wurde in Godot 3 eingeführt und ist mit Godot 4.0 und 4.1 kompatibel. Diese Version ermöglichte es Entwicklern, die Godot-Engine mit Java-, Kotlin- und nativen Funktionen zu erweitern.

Ab Godot 4.2 werden Android-Plugins, die auf der v1-Architektur basieren, nicht mehr verwendet. Stattdessen wird mit Godot 4.2 eine neue Version 2 (v2) Architektur für Android-Plugins eingeführt.

v2-Architektur

Bemerkung

Das Godot Android Plugin nutzt das Gradle Build System.

Aufbauend auf der vorherigen v1-Architektur werden Android-Plugins weiterhin von der Android-Archivbibliothek abgeleitet.

Im Kern ist ein Godot Android Plugin v2 eine Android-Bibliothek mit einer Abhängigkeit von der Godot Android-Bibliothek und einem benutzerdefinierten Android-Bibliotheksmanifest.

Diese Architektur ermöglicht es Android-Plugins, die Funktionalität der Engine mit Folgendem zu erweitern:

  • APIs der Android-Plattform

  • Android-Bibliotheken

  • Kotlin- und Java-Bibliotheken

  • Native Bibliotheken (über JNI)

  • GDExtension-Bibliotheken

Jedes Plugin hat eine Init-Klasse, die von der Klasse GodotPlugin abgeleitet ist, die von der Godot Android Bibliothek bereitgestellt wird.

Die Klasse GodotPlugin bietet APIs, um auf die laufende Godot-Instanz zuzugreifen und sich in ihren Lebenszyklus einzuklinken. Sie wird zur Laufzeit von der Godot-Engine geladen.

v2-Packaging-Format

v1 Android-Plugins erforderten eine eigene gdap-Konfigurationsdatei, die vom Godot-Editor verwendet wurde, um die Plugins zu erkennen und zu laden. Dieser Ansatz hatte jedoch mehrere Nachteile, von denen der wichtigste darin bestand, dass es ihm an Flexibilität mangelte und er vom bestehenden Godot-EditorExportPlugin-Format, -Bereitstellungs- und -Installationsfluss abwich.

Dieses Problem wurde für Android-Plugins der Version 2 behoben, indem der Paketierungs- und Konfigurationsmechanismus gdap zugunsten des bestehenden Godot-Paketierungsformats EditorExportPlugin veraltet wurde. Die EditorExportPlugin-API wurde ihrerseits erweitert, um Android-Plugins korrekt zu unterstützen.

Erstellung eines v2-Android-Plugins

Eine Github-Projektvorlage wird unter https://github.com/m4gr3d/Godot-Android-Plugin-Template als Schnellstart für die Erstellung von Godot-Android-Plugins für Godot 4.2+ bereitgestellt. Sie können der Vorlage-README folgen, um Ihr eigenes Godot-Android-Plugin-Projekt einzurichten.

Zum besseren Verständnis werden im Folgenden die Schritte zur Erstellung der Projektvorlage erläutert:

  1. Erstellen Sie ein Android-Bibliotheksmodul mit diesen Anweisungen

  2. Fügen Sie die Godot-Android-Bibliothek als Abhängigkeit hinzu, indem Sie die gradle Build-Datei: aktualisieren:

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

Die Godot-Android-Bibliothek wird auf MavenCentral gehostet und bei jeder Veröffentlichung aktualisiert.

  1. Erstellen Sie GodotAndroidPlugin, eine Init-Klasse für das Plugin, die GodotPlugin erweitert.

    • Wenn das Plugin Kotlin- oder Java-Methoden bereitstellt, die von GDScript aus aufgerufen werden sollen, müssen diese mit @UsedByGodot annotiert werden. Der Name, der von GDScript aufgerufen wird, muss genau mit dem Methodennamen übereinstimmen. Es gibt keine Erzwingung von snake_case zu camelCase. Zum Beispiel, von GDScript:

      if Engine.has_singleton("MyPlugin"):
          var singleton = Engine.get_singleton("MyPlugin")
          print(singleton.myPluginFunction("World"))
      
    • Wenn das Plugin Signale verwendet, muss die init-Klasse den Satz der verwendeten Signale durch Überschreiben von GodotPlugin::getPluginSignals() zurückgeben. Um Signale auszusenden, kann das Plugin die Methode GodotPlugin::emitSignal(...) verwenden.

  2. Aktualisieren Sie die AndroidManifest.xml Datei des Plugins mit den folgenden Metadaten:

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

Wobei:

  • PluginName der Name des Plugins ist

  • plugin.init.ClassFullName der vollständige Komponentenname (Paket + Klassenname) der Plugin-Init-Klasse (z.B.: org.godotengine.plugin.android.template.GodotAndroidPlugin) ist.

  1. Erstellen Sie die EditorExportPlugin-Konfiguration, um das Plugin zu verpacken. Die Schritte zum Erstellen der Konfiguration sind im Abschnitt Paketieren eines v2-Android-Plugins zu sehen.

Erstellen eines v2-Android-Plugins mit GDExtension-Funktionen

Ähnlich wie die GDNative-Unterstützung in v1-Android-Plugins, unterstützen v2-Android-Plugins die Fähigkeit, GDExtension-Funktionen zu integrieren.

Eine Github-Projektvorlage wird unter https://github.com/m4gr3d/GDExtension-Android-Plugin-Template als Schnellstart für die Erstellung von GDExtension Android-Plugins für Godot 4.2+ bereitgestellt. Sie können der README der Vorlage folgen, um Ihr eigenes Godot-Android-Plugin-Projekt einzurichten.

Migrieren eines Android-Plugins von v1 nach v2

Führen Sie die folgenden Schritte aus, wenn Sie ein Android-Plugin der Version 1 haben, das Sie auf die Version 2 migrieren möchten:

  1. Aktualisieren Sie die Manifestdatei des Plugins:

    • Ändern Sie das Präfix org.godotengine.plugin.v1 in org.godotengine.plugin.v2

  2. Aktualisieren Sie die Build-Abhängigkeit der Godot Android-Bibliothek:

    • Sie können weiterhin die Binärdatei godot-lib.<Version>.<Status>.aar von Godot's download page verwenden, wenn Sie das bevorzugen. Stellen Sie sicher, dass es auf die neueste stable-Version aktualisiert ist.

    • Oder Sie können auf die von MavenCentral bereitgestellte Abhängigkeit wechseln:

      dependencies {
          implementation("org.godotengine:godot:4.2.0.stable")
      }
      
  3. Nachdem Sie die Godot-Android-Bibliotheksabhängigkeit aktualisiert haben, synchronisieren oder erstellen Sie das Plugin und beheben Sie etwaige Kompilierungsfehler:

    • Die Godot-Instanz, die von GodotPlugin::getGodot() bereitgestellt wird, hat keinen Zugriff mehr auf eine android.content.Context-Referenz. Verwenden Sie stattdessen GodotPlugin::getActivity().

  4. Löschen Sie die gdap-Konfigurationsdatei(en) und folgen Sie den Anweisungen im Abschnitt Paketierung eines v2-Android-Plugins, um die Plugin-Konfiguration einzurichten.

Paketierung eines v2-Android-Plugins

Wie bereits erwähnt, wird ein v2 Android-Plugin jetzt als EditorExportPlugin-Plugin für den Godot-Editor zur Verfügung gestellt, so dass es viele der gleichen Paketierungsschritte teilt.

  1. Fügen Sie die Plugin-Ausgabe-Binärdateien in das Plugin-Verzeichnis ein (z.B.: in addons/<plugin_name>/)

  2. Fügen Sie das Toolskript für die Exportfunktionalität in das Plugin-Verzeichnis ein (z.B.: in addons/<plugin_name>/)

    • Das erstellte Skript muß ein @tool-Skript sein, sonst funktioniert es nicht richtig

    • Das Export-Tool-Skript wird verwendet, um das Android-Plugin zu konfigurieren und es in den Exportprozess des Godot-Editors einzubinden. Es sollte in etwa so aussehen:

      @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
      
    • Hier sind die wichtigsten EditorExportPlugin-APIs, die in diesem Toolskript verwendet werden:

      Die _get_android_manifest_*-Methoden ermöglichen es dem Plugin, automatisch Änderungen am Manifest der App bereitzustellen, die bei einer Aktualisierung des Godot-Editors erhalten bleiben, wodurch ein langjähriges Problem mit v1-Android-Plugins behoben wird.

  3. Erstellen Sie eine plugin.cfg. Dies ist eine INI-Datei mit Metadaten über Ihr Plugin:

    [plugin]
    
    name="<plugin_name>"
    description="<plugin_description>"
    author="<plugin_author>"
    version="<plugin_version>"
    script="<relative_path_to_the_export_tool_script>"
    

Zur Veranschaulichung sehen Sie hier die Ordnerstruktur für die Godot Android Plugin-Projektvorlage. Zur Build-Zeit wird der Inhalt des Verzeichnisses export_scripts_template sowie die generierten Plugin-Binärdateien in das Verzeichnis addons/<plugin_name> kopiert:

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file

Paketierung eines v2 Android-Plugins mit GDExtension-Funktionen

Für die GDExtension folgen wir den gleichen Schritten wie für Packaging a v2 Android plugin und fügen die GDExtension config file am gleichen Ort wie plugin.cfg hinzu.

Als Referenz ist hier die Ordnerstruktur für die GDExtension-Android-Plugin-Projektvorlage. Zur Build-Zeit wird der Inhalt des Verzeichnisses export_scripts_template sowie die generierten Plugin-Binärdateien in das Verzeichnis addons/<plugin_name> kopiert:

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file
|
+--plugin.gdextension       # GDExtension config file

So sollte die Konfigurationsdatei plugin.gdextension aussehen:

[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"
...

Erwähnenswert ist das Feld android_aar_plugin, das angibt, dass dieses GDExtension-Modul als Teil eines v2 Android-Plugins bereitgestellt wird. Während des Exportvorgangs wird dies dem Godot-Editor an, dass die nativen Shared-Libraries der GDExtension-Bibliotheken von den AAR-Binärdateien des Android-Plugins exportiert werden.

Für GDExtension-Android-Plugins muss die Plugin-Init-Klasse GodotPlugin::getPluginGDExtensionLibrariesPaths() überschreiben und die Pfade zu den gebündelten GDExtension-Bibliotheks-Konfigurationsdateien (*.gdextension) zurückgeben.

Die Pfade müssen relativ zum Verzeichnis assets der Android-Bibliothek sein. Zur Laufzeit wird das Plugin diese Pfade der Godot-Engine zur Verfügung stellen, die sie zum Laden und Initialisieren der gebündelten GDExtension-Bibliotheken verwenden wird.

Verwenden eines v2 Android-Plugins

Bemerkung

  • Godot 4.2 oder höher ist erforderlich

  • v2-Android-Plugin erfordert die Verwendung des Gradle-Build-Prozesses.

  • Die mitgelieferten Github-Projektvorlagen enthalten Demo-Godot-Projekte für schnelle Tests.

  1. Kopieren Sie das Ausgabeverzeichnis des Plugins (addons/<plugin_name>) in das Verzeichnis des Ziel-Godot-Projekts

  2. Öffnen Sie das Projekt im Godot-Editor; der Editor sollte das Plugin erkennen

  3. Navigieren Sie zu Projekt -> Projekteinstellungen -> Plugins, und stellen Sie sicher, dass das Plugin aktiviert ist

  4. Installieren Sie die Godot-Android-Build-Vorlage, indem Sie auf Projekt -> Android Build Template installieren... klicken

  5. Navigieren Sie zu Projekt -> Exportieren...

  6. Erstellen Sie im Fenster Export eine Android Exportvorgabe

  7. In der Voreinstellung Android-Export scrollen Sie zu Gradle-Build und setzen Gradle-Build verwenden auf true

  8. Aktualisieren Sie die Skripte des Projekts nach Bedarf, um auf die Funktionen des Plugins zuzugreifen. Zum Beispiel:

    if Engine.has_singleton("MyPlugin"):
            var singleton = Engine.get_singleton("MyPlugin")
            print(singleton.myPluginFunction("World"))
    
  9. Schließen Sie ein Android-Gerät an Ihren Rechner an und führen Sie das Projekt darauf aus

Verwendung eines v2-Android-Plugins als Android-Bibliothek

Da sie auch Android-Bibliotheken sind, können Godot v2-Android-Plugins aus ihrer EditorExportPlugin-Paketierung herausgenommen und als rohe AAR-Binärdateien zur Verwendung als Bibliotheken neben der Godot Android-Bibliothek durch Android-Anwendungen bereitgestellt werden.

Wenn Sie auf diesen Anwendungsfall abzielen, stellen Sie sicher, dass Sie zusätzliche Anweisungen einfügen, wie die AAR-Binärdateien eingebunden werden sollen (z.B.: eigene Ergänzungen zum Manifest der Android-App).

Referenzimplementierungen

Tipps und Leitlinien

Vereinfachen Sie den Zugang zu den exponierten Java / Kotlin APIs

Um den Zugriff auf die exponierten Java-/Kotlin-APIs im Godot-Editor zu erleichtern, wird empfohlen, eine (oder mehrere) gdscript-Wrapper-Klasse(n) bereitzustellen, mit der/denen sich die Benutzer Ihres Plugins verbinden können.

Zum Beispiel:

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")

Support using the GDExtension functionality in the Godot Editor

If planning to use the GDExtension functionality in the Godot Editor, it is recommended that the GDExtension's native binaries are compiled not just for Android, but also for the OS onto which developers / users intend to run the Godot Editor. Not doing so may prevent developers / users from writing code that accesses the plugin from within the Godot Editor.

Dies kann die Erstellung von Dummy-Plugins für das Host-Betriebssystem beinhalten, nur damit die API für den Editor veröffentlicht wird. Sie können die [godot-cpp-template](https://github.com/godotengine/godot-cpp-template) Github-Vorlage als Referenz für diese Vorgehensweise verwenden.

Godot stürzt beim Laden ab

Überprüfen Sie adb logcat auf mögliche Probleme, dann:

  • Prüfen Sie, ob die Methoden, die das Plugin bereitstellt, die folgenden Java-Typen verwenden: void, boolean, int, float, java.lang.String, org.godotengine.godot.Dictionary, int[], byte[], float[], java.lang.String[].

  • Komplexere Datentypen werden derzeit nicht unterstützt.