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

Libreria Android di Godot

Il Godot Engine per piattaforme Android è concepito per essere utilizzato come una libreria Android. Questa architettura abilita diverse funzionalità fondamentali sulle piattaforme Android:

• Possibilità di integrare il sistema di build Gradle all'interno dell'editor Godot, il che consente di sfruttare un maggior numero di componenti dell'ecosistema Android, come librerie e strumenti

• Possibilità di rendere il motore portatile e integrabile:

  • Fondamentale per trasferire l'editor Godot su dispositivi Android e XR mobili

  • Fondamentale per permettere di integrare e riutilizzare le funzionalità di Godot all'interno di codebase esistenti

Di seguito descriviamo alcuni dei casi d'uso e degli scenari resi possibili da questa architettura.

Utilizzo della libreria Android di Godot

La libreria Godot per Android è impacchettata come file di archivio AAR e ospitata su MavenCentral insieme alla sua documentazione.

Fornisce accesso alle API e alle funzionalità di Godot su piattaforme Android per i seguenti casi d'uso non esaustivi.

Estensioni Android di Godot

I plugin Android sono strumenti potenti che estendono le capacità del Godot Engine sfruttando le funzionalità offerte dalla piattaforma e dall'ecosistema Android.

Un plugin Android è una libreria Android che dipende dalla libreria Godot per Android, che il plugin utilizza per integrarsi nel ciclo di vita del motore e per accedere alle API di Godot, garantendogli potenti funzionalità come il supporto per GDExtension, che consente di aggiornare/modificare il comportamento del motore secondo necessità.

Per ulteriori informazioni, consultare Godot Android plugins.

Incorporare Godot nei progetti esistenti Android

È possibile incorporare il Godot Engine in applicazioni o librerie Android esistenti, consentendo agli sviluppatori di sfruttare codice e librerie collaudati e più adatti a un compito specifico.

Il componente host è responsabile di gestire il ciclo di vita del motore tramite le API Android di Godot. Queste API possono servire anche per fornire una comunicazione bidirezionale tra l'host e l'istanza di Godot incorporata, dando maggiore controllo sull'esperienza desiderata.

Mostriamo come ciò si realizza mediante un'app Android di esempio che incorpora il Godot Engine come vista Android e lo utilizza per renderizzare modelli 3D glTF.

L'app di esempio GLTF Viewer utilizza un componente Android RecyclerView per creare un elenco di elementi glTF, popolati dal pacchetto Kenney's Food Kit. Quando viene selezionato un elemento nell'elenco, la logica dell'app interagisce con il Godot Engine integrato per renderizzare l'elemento glTF selezionato come modello 3D.

Il codice sorgente dell'app di esempio è disponibile su GitHub. Seguire le istruzioni nel `file README <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/README.md> `_ per compilarlo e installarlo.

Di seguito, illustriamo i passaggi necessari per creare l'app GLTF Viewer.

Avvertimento

Attualmente è supportata una sola istanza di Godot Engine per processo. È possibile configurare il processo in cui è eseguita l'Android Activity tramite l'attributo android:process.

Avvertimento

Gli eventi di configurazione di ridimensionamento/orientamento automatico non sono supportati e potrebbero causare un arresto anomalo. È possibile disabilitare questi eventi:

• Bloccando un orientamento specifico tramite l'attributo android:screenOrientation <https://developer.android.com/guide/topics/manifest/activity-element#screen>`_.

• Dichiarando che l'Activity gestirà questi eventi di configurazione tramite l'attributo android:configChanges <https://developer.android.com/guide/topics/manifest/activity-element#config>.

1. Creare l'applicazione Android

Nota

L'app di esempio per Android è stata creata attraverso Android Studio e Gradle come sistema di compilazione.

The Android ecosystem provides multiple tools, IDEs, build systems for creating Android apps so feel free to use what you're familiar with, and update the steps below accordingly (contributions to this documentation are welcomed as well!).

• Configurare un progetto di applicazione Android. Può essere un progetto completamente nuovo e vuoto, oppure un progetto esistente

• Aggiungere la dipendenza maven per la libreria Godot Android

  • Se si utilizza gradle, aggiungere quanto segue alla sezione dependency del file di build gradle dell'app. Assicurarsi di aggiornare <version> all'ultima versione della libreria Godot per Android:

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

• Se si utilizza gradle, includere la seguente configurazione aaptOptions nella sezione android > defaultConfig del file di build gradle dell'app. Facendo così, gradle potrà includere le cartelle nascoste di Godot durante la compilazione dell'eseguibile dell'app.

  • Se il sistema di compilazione non supporta l'inclusione di cartelle nascoste, è possibile configurare il progetto Godot in modo che non le utilizzi deselezionando Applicazione > Configurazione > Utilizza cartella nascosta per i dati del progetto nelle Impostazioni del progetto.

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:!*~"
      }
    ...

• Creare/aggiornare l'Activity dell'applicazione che ospiterà l'istanza di Godot Engine. Per l'applicazione di esempio, questa è MainActivity

  • L'Activity host dovrebbe implementare l'interfaccia GodotHost

  • L'app di esempio utilizza Fragments per organizzare la sua interfaccia utente, quindi utilizzare GodotFragment, un componente frammento fornito dalla libreria Godot per Android per ospitare e gestire automaticamente l'istanza di 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()
      }
  
      ...
  

Nota

La libreria Godot per Android fornisce anche GodotActivity, un componente Activity che si può estendere per ospitare e gestire automaticamente l'istanza di Godot Engine.

Come alternativa, le applicazioni possono creare direttamente un'istanza di Godot, ospitarla e gestirla autonomamente.

• Using GodotHost#getHostPlugins(...), the sample app creates a runtime GodotPlugin instance that's used to send signals to the gdscript logic

  • The runtime GodotPlugin can also be used by gdscript logic to access JVM methods. For more information, see Godot Android plugins.

• Aggiungere qualsiasi logica in più che sarà utilizzata dalla propria applicazione

  • Per l'app di esempio, ciò include aggiungere il frammento ItemsSelectionFragment (e classi correlate), un frammento utilizzato per costruire e mostrare l'elenco degli elementi glTF

• Aprire il file AndroidManifest.xml e configurare l'orientamento, se necessario, tramite l'attributo android:screenOrientation

  • Se necessario, disabilitare i cambiamenti automatici alla configurazione di ridimensionamento/orientamento tramite l'attributo android:configChanges

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

    ...
</activity>

2. Creare il progetto Godot

Nota

Su Android, i file di progetto di Godot sono esportati nella cartella assets del file binario apk generato.

Sfruttiamo tale architettura per collegare la nostra app Android e il progetto Godot, creando il progetto Godot nella cartella assets dell'app Android.

Si noti che è anche possibile creare il progetto Godot in una cartella separata ed esportarlo come file PCK o ZIP nella cartella assets dell'app Android. Usare questo approccio richiede passare l'argomento --main-pack <percorso_file_pck_o_zip_relativo_alla_cartella_assets> all'istanza di Godot Engine ospitata tramite GodotHost#getCommandLine().

Esempio:

@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;
}

Le istruzioni seguenti e l'app di esempio seguono il primo approccio, ovvero creare il progetto Godot nella cartella assets dell'app Android.

• Come indicato nella nota precedente, aprire l'editor di Godot e creare un progetto Godot direttamente (senza sottocartelle) nella cartella assets del progetto dell'applicazione Android

  • Consultare il progetto Godot dell'app di esempio per riferimento

• Configurare il progetto Godot come desiderato

  • Assicurarsi che l'orientamento impostato per il progetto Godot corrisponda a quello impostato nel manifest dell'app Android

  • Per Android, assicurarsi che textures/vram_compression/import_etc2_astc sia impostato su true

• Aggiornare la logica negli script del progetto Godot secondo necessità

  • Per l'app di esempio, la logica nello script interroga l'istanza runtime di GodotPlugin e la utilizza per registrarsi ai segnali attivati dalla logica dell'app

  • La logica dell'app genera un segnale ogni volta che viene selezionato un elemento nell'elenco. Il segnale contiene il percorso del file del modello glTF, che viene utilizzato dalla logica gdscript per renderizzare il modello.

  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. Compilare ed eseguire l'applicazione

Una volta completata la configurazione del progetto Godot, compilare ed eseguire l'app Android. Se configurata correttamente, l'Activity host inizializzerà il Godot Engine integrato all'avvio. Il Godot Engine verificherà la cartella assets cercando i file del progetto da caricare (a meno che non sia configurato per cercare un main pack) e procederà all'esecuzione del progetto.

Mentre l'app è in esecuzione sul dispositivo, è possibile consultare Android logcat per esaminare eventuali errori o arresti anomali.

Per riferimento, consultare le istruzioni di compilazione e installazione per l'app di esempio GLTF Viewer.