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:
Erstellen Sie ein Android-Bibliotheksmodul mit diesen Anweisungen
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.
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
zucamelCase
. 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.
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.
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:
Aktualisieren Sie die Manifestdatei des Plugins:
Ändern Sie das Präfix
org.godotengine.plugin.v1
inorg.godotengine.plugin.v2
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") }
Nachdem Sie die Godot-Android-Bibliotheksabhängigkeit aktualisiert haben, synchronisieren oder erstellen Sie das Plugin und beheben Sie etwaige Kompilierungsfehler:
Die
Godot
-Instanz, die vonGodotPlugin::getGodot()
bereitgestellt wird, hat keinen Zugriff mehr auf eineandroid.content.Context
-Referenz. Verwenden Sie stattdessenGodotPlugin::getActivity()
.
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.
Fügen Sie die Plugin-Ausgabe-Binärdateien in das Plugin-Verzeichnis ein (z.B.: in
addons/<plugin_name>/
)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 richtigDas 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:
_supports_platform: gibt
true
zurück, wenn das Plugin die angegebene Plattform unterstützt. Für Android-Plugins muss diestrue
zurückgeben, wennplatform
EditorExportPlatformAndroid ist_get_android_libraries: ermittelt die lokalen Pfade der vom Plugin bereitgestellten Android-Bibliotheken (AAR-Dateien)
_get_android_dependencies: Abrufen des Satzes von Android-Maven-Abhängigkeiten (z.B.: org.godot.example:my-plugin:0.0.0), die vom Plugin bereitgestellt werden
_get_android_dependencies_maven_repos: liefert die URLs der Maven-Repos für die Android-Abhängigkeiten, die von
_get_android_dependencies
bereitgestellt werden_get_android_manifest_activity_element_contents: aktualisiert den Inhalt des Elements <activity> im generierten Android-Manifest
_get_android_manifest_application_element_contents: aktualisiert den Inhalt des Elements <application> im generierten Android-Manifest
_get_android_manifest_element_contents: aktualisiert den Inhalt des Elements <manifest> im generierten Android-Manifest
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.
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.
Kopieren Sie das Ausgabeverzeichnis des Plugins (
addons/<plugin_name>
) in das Verzeichnis des Ziel-Godot-ProjektsÖffnen Sie das Projekt im Godot-Editor; der Editor sollte das Plugin erkennen
Navigieren Sie zu
Projekt
->Projekteinstellungen
->Plugins
, und stellen Sie sicher, dass das Plugin aktiviert istInstallieren Sie die Godot-Android-Build-Vorlage, indem Sie auf
Projekt
->Android Build Template installieren...
klickenNavigieren Sie zu
Projekt
->Exportieren...
Erstellen Sie im Fenster
Export
eineAndroid Exportvorgabe
In der Voreinstellung
Android-Export
scrollen Sie zuGradle-Build
und setzenGradle-Build verwenden
auftrue
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"))
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.