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

Plugins do Godot para Android

Introdução

Os plugins para Android são ferramentas poderosas para estender as capacidades do motor Godot, aproveitando as funcionalidades fornecidas pelas plataformas e pelo ecossistema do Android.

Por exemplo, no Godot 4, os plugins do Android são usados para suportar várias plataformas XR baseadas em Android sem sobrecarregar a base de código principal com códigos ou binários específicos do fornecedor.

Plugin de Android

A Versão 1 (v1) do sistema de plugins do Android foi introduzida no Godot 3 e era compatível com o Godot 4.0 e 4.1. Essa versão permitia que os desenvolvedores aumentassem o motor Godot com funcionalidades em Java, Kotlin e nativas.

A partir do Godot 4.2, os plugins do Android baseados na arquitetura v1 estão descontinuados. Em vez disso, o Godot 4.2 introduz uma nova arquitetura de Versão 2 (v2) para plugins do Android.

Arquitetura v2

Nota

O plugin do Android do Godot aproveita o sistema de compilação Gradle.

Com base na arquitetura v1 anterior, os plugins do Android continuam a ser derivados da biblioteca de arquivos do Android.

Em sua essência, um plugin do Android do Godot v2 é uma biblioteca Android com uma dependência da biblioteca Android do Godot e um manifesto de biblioteca Android personalizado.

Esta arquitetura permite que os plugins do Android estendam a funcionalidade do motor com:

• APIs da plataforma Android

• Bibliotecas Android

• Bibliotecas Kotlin e Java

• Bibliotecas nativas (via JNI)

• Bibliotecas GDExtension

Cada plugin tem uma classe de inicialização (init class) que estende da classe GodotPlugin que é fornecida pela biblioteca Godot Android.

A classe GodotPlugin fornece APIs para acessar a instância do Godot em execução e se conectar ao seu ciclo de vida. Ela é carregada em tempo de execução pelo motor do Godot.

Formato de empacotamento v2

Os plugins Android v1 exigiam um arquivo de configuração gdap personalizado que era usado pelo Editor Godot para detectá-los e carregá-los. No entanto, essa abordagem apresentava várias desvantagens, sendo as principais a falta de flexibilidade e o distanciamento do formato, fluxo de entrega e instalação existente do EditorExportPlugin do Godot.

Isso foi resolvido para os plugins Android v2 descontinuando o mecanismo de empacotamento e configuração gdap em favor do formato de empacotamento EditorExportPlugin existente do Godot. A API EditorExportPlugin, por sua vez, foi estendida para suportar adequadamente os plugins do Android.

Compilando um plugin Android v2

Um modelo de projeto do GitHub é fornecido em https://github.com/m4gr3d/Godot-Android-Plugin-Template como um início rápido para a construção de plugins Android do Godot para o Godot 4.2+. Você pode seguir o README do modelo para configurar seu próprio projeto de plugin Android do Godot.

Para fornecer uma maior compreensão, aqui está um detalhamento das etapas usadas para criar o modelo de projeto:

1. Create an Android library module by following these instructions.

2. Adicione a biblioteca Android do Godot como uma dependência atualizando o arquivo de compilação gradle do módulo:

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

A biblioteca Android do Godot está hospedada no MavenCentral e é atualizada a cada lançamento.

3. Crie a GodotAndroidPlugin, uma classe de inicialização para o plugin que herda de GodotPlugin.

   • Se o plugin expuser métodos Kotlin ou Java para serem chamados a partir do GDScript, eles devem ser anotados com @UsedByGodot. O nome chamado a partir do GDScript deve corresponder exatamente ao nome do método. Não há nenhuma coerção de snake_case para camelCase. Por exemplo, a partir do GDScript:

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

   • Se o plugin usar sinais, a classe de inicialização deve retornar o conjunto de sinais usados sobrescrevendo GodotPlugin::getPluginSignals(). Para emitir sinais, o plugin pode usar o método GodotPlugin::emitSignal(...).

4. Atualize o arquivo AndroidManifest.xml do plugin com os seguintes metadados:

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

Onde:

• PluginName é o nome do plugin

• plugin.init.ClassFullName é o nome completo do componente (pacote + nome da classe) da classe de inicialização do plugin (ex: org.godotengine.plugin.android.template.GodotAndroidPlugin).

5. Crie a configuração do EditorExportPlugin para empacotar o plugin. As etapas usadas para criar a configuração podem ser vistas na seção Empacotando um plugin Android v2.

Construindo um plugin Android v2 com capacidades GDExtension

Semelhante ao suporte a GDNative nos plugins Android v1, os plugins Android v2 suportam a capacidade de integrar recursos da GDExtension.

Um modelo de projeto do GitHub é fornecido em https://github.com/m4gr3d/GDExtension-Android-Plugin-Template como um início rápido para a construção de plugins Android GDExtension para o Godot 4.2+. Você pode seguir o README do modelo para configurar seu próprio projeto de plugin Android do Godot.

Migrando um plugin Android v1 para v2

Use as seguintes etapas se tiver um plugin Android v1 que deseja migrar para o v2:

1. Atualize o arquivo de manifesto do plugin:

   • Altere o prefixo org.godotengine.plugin.v1 para org.godotengine.plugin.v2

2. Atualize a dependência de compilação da biblioteca Android do Godot:

   • Você pode continuar usando o binário godot-lib.<version>.<status>.aar da página de download do Godot se essa for a sua preferência. Certifique-se de que ele esteja atualizado para a versão estável mais recente.

   • Ou você pode mudar para a dependência fornecida pelo MavenCentral:

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

3. Após atualizar a dependência da biblioteca Android do Godot, sincronize ou compile o plugin e resolva quaisquer erros de compilação:

   • A instância Godot fornecida por GodotPlugin::getGodot() não tem mais acesso a uma referência de android.content.Context. Use GodotPlugin::getActivity() em seu lugar.

4. Exclua os arquivos de configuração gdap e siga as instruções na seção Empacotando um plugin Android v2 para configurar a estrutura do plugin.

Empacotando um plugin Android v2

Como mencionado, um plugin Android v2 agora é fornecido ao Editor Godot como um plugin EditorExportPlugin, portanto ele compartilha muitas das mesmas etapas de empacotamento.

1. Adicione os binários de saída do plugin dentro do diretório do plugin (ex: em addons/<nome_do_plugin>/)

2. Adicione o script de ferramenta para a funcionalidade de exportação dentro do diretório do plugin (ex: em addons/<nome_do_plugin>/)

   • O script criado deve ser um script @tool, caso contrário ele não funcionará corretamente

   • O script de ferramenta de exportação é usado para configurar o plugin do Android e conectá-lo ao processo de exportação do Editor Godot. Ele deve se parecer com isto:

   @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 most relevant to use in this tool script:

     • _supports_platform:

       Return true if the plugin supports the given platform. For Android plugins, this must return true when platform is EditorExportPlatformAndroid
     • _get_android_libraries:

       Retrieve the local paths of the Android libraries binaries (AAR files) provided by the plugin
     • _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:

       Retrieve the urls of the maven repos for the android dependencies provided by _get_android_dependencies
     • _get_android_manifest_activity_element_contents:

       Update the contents of the <activity> element in the generated Android manifest
     • _get_android_manifest_application_element_contents:

       Update the contents of the <application> element in the generated Android manifest
     • _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.

3. Crie um plugin.cfg. Este é um arquivo INI com metadados sobre o seu plugin:

[plugin]

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

Para referência, aqui está a estrutura de pastas para o modelo de projeto de plugin Android do Godot. No momento da compilação, o conteúdo do diretório export_scripts_template, bem como os binários do plugin gerados, são copiados para o diretório addons/<nome_do_plugin>:

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

Empacotando um plugin Android v2 com capacidades GDExtension

Para a GDExtension, seguimos os mesmos passos de Empacotando um plugin Android v2 e adicionamos o arquivo de configuração GDExtension no mesmo local que plugin.cfg.

Para referência, aqui está a estrutura de pastas para o modelo de projeto de plugin Android GDExtension. No momento da compilação, o conteúdo do diretório export_scripts_template, bem como os binários do plugin gerados, são copiados para o diretório addons/<nome_do_plugin>:

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

Aqui está como o arquivo de configuração plugin.gdextension deve se parecer:

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

É de se notar o campo android_aar_plugin que especifica que este módulo GDExtension é fornecido como parte de um plugin Android v2. Durante o processo de exportação, isso indicará ao Editor Godot que as bibliotecas nativas compartilhadas da GDExtension são exportadas pelos binários AAR do plugin do Android.

Para plugins Android GDExtension, a classe de inicialização do plugin deve sobrescrever GodotPlugin::getPluginGDExtensionLibrariesPaths() e retornar os caminhos para os arquivos de configuração das bibliotecas GDExtension empacotadas (*.gdextension).

Os caminhos devem ser relativos ao diretório assets da biblioteca Android. Em tempo de execução, o plugin fornecerá esses caminhos ao motor do Godot, que os usará para carregar e inicializar as bibliotecas GDExtension empacotadas.

Usando un plugin Android v2

Nota

• O Godot 4.2 ou superior é obrigatório

• O plugin Android v2 exige o uso do processo de compilação Gradle.

• Os modelos de projeto fornecidos no GitHub incluem projetos de demonstração do Godot para testes rápidos.

1. Copie o diretório de saída do plugin (addons/<nome_do_plugin>) para o diretório do projeto Godot de destino

2. Abra o projeto no Editor Godot; o Editor deve detectar o plugin

3. Navegue até Project -> Project Settings... -> Plugins, e certifique-se de que o plugin está ativado

4. Instale o modelo de compilação do Android do Godot clicando em Projeto -> Instalar Modelo de Exportação Android...

5. Navegue até Projeto -> Exportar...

6. Na janela Exportar, crie uma Predefinição de exportação Android

7. Na Predefinição de exportação Android, role até Gradle Build e defina Use Gradle Build como true

8. Atualize os scripts do projeto conforme necessário para acessar a funcionalidade do plugin. Por exemplo:

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

9. Conecte um dispositivo Android ao seu computador e execute o projeto nele

Usando um plugin Android v2 como uma biblioteca Android

Como também são bibliotecas Android, os plugins Android v2 do Godot podem ser despojados de seu empacotamento EditorExportPlugin e fornecidos como binários AAR brutos para uso como bibliotecas juntamente com a biblioteca Android do Godot por aplicativos Android.

Se estiver visando esse caso de uso, certifique-se de incluir instruções adicionais sobre como os binários AAR devem ser incluídos (ex: adições personalizadas ao manifesto do aplicativo Android).

Implementações de referência

• Exemplos de Plugins Android para Godot

• Modelo de Plugin Android para Godot

• Modelo de Plugin Android GDExtension

• Godot OpenXR Loaders

Dicas e Diretrizes

Simplifique o acesso às APIs Java / Kotlin expostas

Para facilitar o acesso às APIs Java / Kotlin expostas no Editor Godot, recomenda-se fornecer uma (ou múltiplas) classe(s) wrapper em gdscript para os usuários do seu plugin fazerem a interface.

Por exemplo:

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

Suporte ao uso da funcionalidade GDExtension no Editor Godot

Se planeja usar a funcionalidade GDExtension no Editor Godot, recomenda-se que os binários nativos da GDExtension sejam compilados não apenas para Android, mas também para o sistema operacional no qual os desenvolvedores / usuários pretendem executar o Editor Godot. Não fazer isso pode impedir que os desenvolvedores / usuários escrevam códigos que acessem o plugin de dentro do Editor Godot.

Isso pode envolver a criação de plugins fictícios (dummy plugins) para o sistema operacional hospedeiro apenas para que a API seja publicada no editor. Você pode usar o modelo (template) do GitHub godot-cpp-template como referência de como fazer isso.

Tipos de dados suportados

Todos os tipos de dados são suportados. Os tipos comuns são mapeados para seus equivalentes do Godot (por exemplo, String[] é mapeado para PackedStringArray()), mas para outros tipos, você pode usar o JavaClassWrapper para acessá-los.

Godot trava ao carregar

Verifique o adb logcat para possíveis problemas.