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

Estensioni Android di Godot

Introduzione

I plugin Android sono strumenti potenti che estendono le capacità del motore Godot sfruttando le funzionalità offerte dalle piattaforme e dall'ecosistema Android.

Ad esempio, in Godot 4, i plugin Android sono utilizzati per supportare diverse piattaforme XR basate su Android senza appesantire il codice sorgente con codice o file binari specifici dei fornitori.

Plugin Android

La Versione 1 (v1) del sistema di plugin Android è stata introdotta in Godot 3 ed era compatibile con Godot 4.0 e 4.1. Tale versione consentiva agli sviluppatori di estendere il motore di Godot con funzionalità Java, Kotlin e native.

A partire da Godot 4.2, i plugin Android basati sull'architettura v1 sono ora deprecati. Godot 4.2 introduce invece una nuova architettura Versione 2 (v2) per i plugin Android.

Architettura v2

Nota

Il plugin Godot per Android sfrutta il sistema di build Gradle.

Basandosi sulla precedente architettura v1, i plugin Android continuano a derivare dalla libreria di archivio Android.

In sostanza, un plugin Godot per Android v2 è una libreria Android con una dipendenza dalla libreria Android di Godot e un manifest personalizzato di libreria Android.

Questa architettura consente ai plugin di Android di estendere le funzionalità del motore con:

API della piattaforma Android
Librerie Android
Librerie di Java e Kotlin
Librerie native (tramite JNI)
Librerie GDExtension

Ogni plugin ha una classe di inizializzazione che estende la classe GodotPlugin che è fornita dalla libreria Android Godot.

La classe GodotPlugin fornisce API per accedere all'istanza di Godot in esecuzione e integrarsi nel suo ciclo di vita. È caricata in fase di esecuzione dal motore di Godot.

Formato di impacchettamento v2

I plugin Android v1 richiedevano un file di configurazione gdap personalizzato che serviva all'editor di Godot per rilevarli e caricarli. Tuttavia, questo approccio aveva diversi svantaggi, principalmente la mancanza di flessibilità e il distacco dal formato, dalla distribuzione e dal flusso di installazione esistenti di EditorExportPlugin in Godot.

Questo problema è stato risolto per i plugin Android v2 deprecando il meccanismo di impacchettamento e configurazione gdap a favore del formato di impacchettamento EditorExportPlugin già esistente in Godot. L'API di EditorExportPlugin è stata a sua volta estesa per supportare correttamente i plugin Android.

Compilare un plugin Android v2

Un modello di progetto GitHub è disponibile all'indirizzo https://github.com/m4gr3d/Godot-Android-Plugin-Template come guida rapida per la creazione di plugin Android per Godot 4.2+. È possibile seguire il file README del modello per configurare il proprio progetto di plugin Android per Godot.

Per una migliore comprensione, ecco una descrizione dettagliata dei passaggi utilizzati per creare il modello di progetto:

Creare un modulo di libreria Android seguendo queste istruzioni
Aggiungere la libreria Android di Godot come dipendenza aggiornando il file build gradle del modulo:
dependencies { implementation("org.godotengine:godot:4.2.0.stable") }

La libreria Android di Godot è ospitata su MavenCentral <https://central.sonatype.com/artifact/org.godotengine/godot> ed è aggiornata a ogni nuova versione.

Creare GodotAndroidPlugin, una classe di inizializzazione per il plugin che estende GodotPlugin.
- Se il plugin espone metodi in Kotlin o Java da chiamare da GDScript, questi devono essere annotati con @UsedByGodot. Il nome chiamato da GDScript deve corrispondere esattamente al nome del metodo. Non è effettuata alcuna conversione da snake_case a camelCase. Ad esempio, da GDScript:
  if Engine.has_singleton("MyPlugin"): var singleton = Engine.get_singleton("MyPlugin") print(singleton.myPluginFunction("World"))
- Se il plugin utilizza segnali, la classe di inizializzazione deve restituire l'insieme di segnali utilizzati sovrascrivendo GodotPlugin::getPluginSignals(). Per emettere segnali, il plugin può utilizzare il metodo GodotPlugin::emitSignal(...).

Aggiorna il file AndroidManifest.xml del plugin con i seguenti metadati:

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

Dove:

PluginName è il nome del plugin

plugin.init.ClassFullName è il nome completo del componente (pacchetto + nome della classe) della classe di inizializzazione del plugin (ad esempio: org.godotengine.plugin.android.template.GodotAndroidPlugin).

Creare la configurazione EditorExportPlugin per impacchettare il plugin. I passaggi necessari per creare la configurazione sono illustrati nella sezione Impacchettare un plugin Android v2.

Compilare un plugin Android v2 con funzionalità di GDExtension

Analogamente al supporto GDNative nei plugin Android v1, i plugin Android v2 supportano la possibilità di integrare le funzionalità di GDExtension.

Un modello di progetto GitHub è disponibile all'indirizzo https://github.com/m4gr3d/GDExtension-Android-Plugin-Template come guida rapida per la creazione di plugin Android GDExtension per Godot 4.2+. È possibile seguire il file README del modello per configurare il proprio progetto di plugin Android per Godot.

Migrazione di un plugin Android v1 a v2

Seguire questi passaggi se si desidera migrare un plugin Android v1 alla versione v2:

Aggiornare il file manifest del plugin:
- Cambiare il prefisso org.godotengine.plugin.v1 in org.godotengine.plugin.v2
Aggiornare la dipendenza di compilazione della libreria Godot per Android:
- Se preferito, è possibile continuare a utilizzare il file binario godot-lib.<version>.<status>.aar dalla pagina di download di Godot. Assicurarsi che sia aggiornato all'ultima versione stabile.
- Oppure è possibile passare alla dipendenza fornita da MavenCentral:

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

Dopo aver aggiornato la dipendenza della libreria Godot per Android, sincronizzare o compilare il plugin e risolvere eventuali errori di compilazione:
- The Godot instance provided by GodotPlugin::getGodot() no longer has access to an android.content.Context reference. Use GodotPlugin::getActivity() instead.
Eliminare il/i file di configurazione gdap e seguire le istruzioni nella sezione Impacchettare un plugin Android v2 per configurare il plugin.

Impacchettare un plugin Android v2

Come accennato, un plugin Android v2 è ora disponibile per l'editor Godot come plugin EditorExportPlugin, quindi condivide molti degli stessi passaggi di impacchettamento.

Aggiungere i file binari risultanti del plugin all'interno della cartella dei plugin (ovvero in addons/<nome_plugin>/)
Aggiungi lo script tool per la funzionalità di esportazione all'interno della cartella dei plugin (ovvero in addons/<plugin_name>/)
- Lo script creato deve essere uno script @tool, altrimenti non funzionerà correttamente
- Lo script tool di esportazione serve per configurare il plugin Android e integrarlo nel processo di esportazione di Godot Editor. Dovrebbe apparire più o meno così:

@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


- Here are the set of `EditorExportPlugin APIs <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ most relevant to use in this tool script:

    - `_supports_platform <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-supports-platform>`_: returns ``true`` if the plugin supports the given platform. For Android plugins, this must return ``true`` when ``platform`` is `EditorExportPlatformAndroid <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html>`_
    - `_get_android_libraries <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-libraries>`_: retrieve the local paths of the Android libraries binaries (AAR files) provided by the plugin
    - `_get_android_dependencies <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies>`_: retrieve the set of Android maven dependencies (e.g: `org.godot.example:my-plugin:0.0.0`) provided by the plugin
    - `_get_android_dependencies_maven_repos <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies-maven-repos>`_: retrieve the urls of the maven repos for the android dependencies provided by ``_get_android_dependencies``
    - `_get_android_manifest_activity_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-activity-element-contents>`_: update the contents of the `<activity>` element in the generated Android manifest
    - `_get_android_manifest_application_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-application-element-contents>`_: update the contents of the `<application>` element in the generated Android manifest
    - `_get_android_manifest_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-element-contents>`_: update the contents of the `<manifest>` element in the generated Android manifest

    The ``_get_android_manifest_*`` methods allow the plugin to automatically provide changes
    to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins.

Creare un file plugin.cfg. È un file INI con metadati sul plugin:

[plugin]

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

Per riferimento, ecco la struttura delle cartelle per il modello di progetto del plugin Godot per Android. In fase di compilazione, il contenuto della cartella export_scripts_template e i file binari generati del plugin vengono copiati nella cartella addons/<plugin_name>:

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

Impacchettare un plugin Android v2 con funzionalità GDExtension

Per GDExtension, seguiamo gli stessi passaggi descritti per Impacchettare un plugin Android v2 e aggiungiamo il file di configurazione di GDExtension nella stessa posizione di plugin.cfg.

Per riferimento, ecco la struttura delle cartelle per il modello di progetto del plugin Godot in GDExtension per Android. In fase di compilazione, il contenuto della cartella export_scripts_template e i file binari generati del plugin vengono copiati nella cartella addons/<plugin_name>:

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

Ecco come dovrebbe apparire il file di configurazione 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"
...

Da notare il campo android_aar_plugin che specifica che questo modulo GDExtension è fornito come parte di un plugin Android v2. Durante il processo di esportazione, questo indicherà all'editor di Godot che le librerie condivise native di GDExtension sono esportate dai binari AAR del plugin Android.

Per i plugin Android con GDExtension, la classe di inizializzazione del plugin deve sovrascrivere GodotPlugin::getPluginGDExtensionLibrariesPaths() e restituire i percorsi ai file di configurazione delle librerie GDExtension incluse (*.gdextension).

I percorsi devono essere relativi alla cartella assets della libreria Android. In fase di esecuzione, il plugin fornirà questi percorsi al motore di Godot, che li utilizzerà per caricare e inizializzare le librerie GDExtension incluse.

Utilizzare un'estensione Android v2

Nota

È richiesto Godot 4.2 o versioni successive
I plugin Android v2 richiedono l'utilizzo del processo di build Gradle <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html#class-editorexportplatformandroid-property-gradle-build-use-gradle-build>`_.
I modelli di progetto GitHub forniti includono progetti demo di Godot per test rapidi.

Copiare la cartella di output del plugin (addons/<plugin_name>) nella cartella del progetto Godot di destinazione
Aprire il progetto nell'editor di Godot; l'editor dovrebbe rilevare il plugin
Navigare su Progetto -> Impostazioni del progetto... -> Plugin e assicurarsi che il plugin sia abilitato
Installare il modello di compilazione Android di Godot cliccando su Progetto -> Installa modello di compilazione Android…
Navigare su Progetto -> Esporta...
Nella finestra Esporta, creare una preimpostazione d'esportazione Android
Nella preimpostazione d'esportazione Android, scorrere fino a Build Gradle e impostare Utilizza build Gradle su true
Aggiornare gli script del progetto dove necessario per accedere alle funzionalità del plugin. Ad esempio:

if Engine.has_singleton("MyPlugin"):
        var singleton = Engine.get_singleton("MyPlugin")
        print(singleton.myPluginFunction("World"))

Connettere un dispositivo Android al computer ed eseguire il progetto su di esso

Utilizzare un plugin Android v2 come libreria Android

Poiché sono anche librerie Android, i plugin Android v2 di Godot possono essere estratti dal loro pacchetto EditorExportPlugin e forniti come binari AAR grezzi da utilizzare come librerie insieme alla libreria Android di Godot dalle app Android.

Se si intende utilizzare questo caso d'uso, assicurarsi di includere istruzioni aggiuntive su come includere i file binari AAR (ad esempio, tramite aggiunte personalizzate al manifest dell'app Android).

Implementazioni di riferimento

Consigli e linee guida

Semplifica l'accesso alle API Java/Kotlin esposte

Per facilitare l'accesso alle API Java/Kotlin esposte nell'editor di Godot, si consiglia di fornire una (o più) classi wrapper gdscript con cui gli utenti del plugin possano interagire.

Per esempio:

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

Supporta l'utilizzo della funzionalità di GDExtension nell'editor di Godot

Se si intende utilizzare la funzionalità di GDExtension nell'editor di Godot, si raccomanda di compilare i binari nativi di GDExtension non solo per Android, ma anche per il sistema operativo su cui gli sviluppatori/utenti intendono eseguire l'editor di Godot. Altrimenti, si potrebbe impedire agli sviluppatori/utenti di scrivere codice che accede al plugin dall'interno dell'editor di Godot.

Questo potrebbe prevedere la creazione di plugin fittizi per il sistema operativo host, solo per pubblicare l'API nell'editor. È possibile usare il modello GitHub godot-cpp-template come riferimento per come procedere.

Tipi di dati supportati

Sono supportati tutti i tipi di dati. I tipi comuni sono mappati ai loro equivalenti in Godot (ad esempio, String[] è mappato a PackedStringArray()), ma per altri tipi è possibile utilizzare JavaClassWrapper per accedervi.

Godot si blocca al caricamento

Consultare adb logcat per eventuali problemi.