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

Biblioteca Android do Godot

O Godot Engine para plataformas Android foi projetado para ser usado como uma biblioteca Android. Essa arquitetura permite vários recursos importantes em plataformas Android:

• Capacidade de integrar o sistema de compilação Gradle dentro do Editor Godot, o que oferece a capacidade de aproveitar mais componentes do ecossistema Android, como bibliotecas e ferramentas

• Capacidade de tornar o motor portátil e incorporável:

  • Fundamental para permitir a portabilidade do Editor Godot para dispositivos Android e XR móveis

  • Fundamental para permitir a integração e o reaproveitamento das capacidades do Godot em códigos existentes

Abaixo, descrevemos alguns dos casos de uso e cenários que essa arquitetura possibilita.

Usando a biblioteca Android do Godot

A biblioteca Android do Godot é empacotada como um arquivo de arquivo AAR e hospedada no MavenCentral junto com sua documentação.

Ela fornece acesso às APIs e capacidades do Godot em plataformas Android para os seguintes casos de uso não exaustivos.

Plugins do Godot para Android

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

Um plugin do Android é uma biblioteca Android com uma dependência da biblioteca Android do Godot, que o plugin usa para se integrar ao ciclo de vida do motor e acessar as APIs do Godot, concedendo-lhe capacidades poderosas, como o suporte a GDExtension, que permite atualizar/modificar o comportamento do motor conforme necessário.

Para mais informações, consulte Plugins Android do Godot.

Incorporando o Godot em projetos Android existentes

O Godot Engine pode ser incorporado em aplicativos ou bibliotecas Android existentes, permitindo que os desenvolvedores aproveitem códigos e bibliotecas maduros e testados em combate, mais adequados para uma tarefa específica.

O componente de hospedagem é responsável por conduzir o ciclo de vida do motor por meio das APIs Android do Godot. Essas APIs também podem ser usadas para fornecer comunicação bidirecional entre o hospedeiro e a instância incorporada do Godot, permitindo um maior controle sobre a experiência desejada.

Mostramos como isso é feito usando um aplicativo Android de exemplo que incorpora o Godot Engine como uma view do Android e o usa para renderizar modelos 3D glTF.

O aplicativo de exemplo GLTF Viewer usa um componente Android RecyclerView para criar uma lista de itens glTF, preenchida a partir do pacote Food Kit do Kenney. Quando um item da lista é selecionado, a lógica do aplicativo interage com o Godot Engine incorporado para renderizar o item glTF selecionado como um modelo 3D.

O código-fonte do aplicativo de exemplo pode ser encontrado no GitHub. Siga as instruções em seu README para compilá-lo e instalá-lo.

Abaixo, detalhamos as etapas usadas para criar o aplicativo GLTF Viewer.

Aviso

Atualmente, apenas uma única instância do Godot Engine é suportada por processo. Você pode configurar o processo no qual a Activity do Android é executada usando o atributo android:process.

Aviso

Eventos de redimensionamento automático / configuração de orientação não são suportados e podem causar uma falha. Você pode desabilitar esses eventos:

• Bloqueando para uma orientação específica usando o atributo android:screenOrientation.

• Declarando que a Activity lidará com esses eventos de configuração usando o atributo android:configChanges.

1. Crie o aplicativo Android

Nota

O aplicativo de exemplo para Android foi criado usando o Android Studio e usando o Gradle como sistema de compilação.

O ecossistema Android fornece várias ferramentas, IDEs e sistemas de compilação para criar aplicativos Android, portanto, sinta-se à vontade para usar o que você está familiarizado e atualize as etapas abaixo de acordo (contribuições para esta documentação também são bem-vindas!).

• Configure um projeto de aplicativo Android. Pode ser um projeto vazio totalmente novo ou um projeto existente

• Adicione a dependência maven para a biblioteca Android do Godot

  • Se estiver usando o gradle, adicione o seguinte à seção dependency do arquivo de compilação gradle do aplicativo. Certifique-se de atualizar <version> para a versão mais recente da biblioteca Android do Godot:

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

• Se estiver usando o gradle, inclua a seguinte configuração de aaptOptions na seção android > defaultConfig do arquivo de compilação gradle do aplicativo. Fazer isso permite que o gradle inclua os diretórios ocultos do Godot ao compilar o binário do aplicativo.

  • Se o seu sistema de compilação não suportar a inclusão de diretórios ocultos, você pode configurar o projeto do Godot para não usar diretórios ocultos desmarcando Application > Config > Use Hidden Project Data Directory nas Configurações do Projeto.

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

• Crie/atualize a Activity do aplicativo que hospedará a instância do Godot Engine. Para o aplicativo de exemplo, esta é a MainActivity

  • A Activity hospedeira deve implementar a interface GodotHost

  • O aplicativo de exemplo usa Fragments para organizar sua interface de usuário, por isso ele usa o GodotFragment, um componente de fragmento fornecido pela biblioteca Android do Godot para hospedar e gerenciar automaticamente a instância do 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

A biblioteca Android do Godot também fornece a GodotActivity, um componente de Activity que pode ser estendido para hospedar e gerenciar automaticamente a instância do Godot Engine.

Alternativamente, os aplicativos podem criar diretamente uma instância do Godot, hospedá-la e gerenciá-la por conta própria.

• Usando GodotHost#getHostPlugins(...), o aplicativo de exemplo cria uma instância em tempo de execução de GodotPlugin que é usada para enviar sinais para a lógica em gdscript

  • O GodotPlugin em tempo de execução também pode ser usado pela lógica em gdscript para acessar métodos da JVM. Para mais informações, veja Plugins Android do Godot.

• Adicione qualquer lógica adicional que será usada pelo seu aplicativo

  • Para o aplicativo de exemplo, isso inclui adicionar o fragmento ItemsSelectionFragment (e classes relacionadas), um fragmento usado para construir e mostrar a lista de itens glTF

• Abra o arquivo AndroidManifest.xml e configure a orientação, se necessário, usando o atributo android:screenOrientation

  • Se necessário, desative as alterações automáticas de redimensionamento/configuração de orientação usando o atributo android:configChanges

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

    ...
</activity>

2. Crie o projeto do Godot

Nota

No Android, os arquivos de projeto do Godot são exportados para o diretório assets do binário apk gerado.

Aproveitamos essa arquitetura para vincular nosso aplicativo Android e o projeto do Godot criando o projeto do Godot diretamente no diretório assets do aplicativo Android.

Note que também é possível criar o projeto do Godot em um diretório separado e exportá-lo como um arquivo PCK ou ZIP para o diretório assets do aplicativo Android. O uso dessa abordagem requer a passagem do argumento --main-pack <caminho_do_arquivo_pck_ou_zip_relativo_ao_diretorio_assets> para a instância hospedada do Godot Engine usando GodotHost#getCommandLine().

Exemplo:

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

As instruções abaixo e o aplicativo de exemplo seguem a primeira abordagem de criar o projeto do Godot no diretório assets do aplicativo Android.

• Como mencionado na nota acima, abra o Editor Godot e crie un projeto do Godot diretamente (sem subpasta) no diretório assets do projeto do aplicativo Android

  • Veja o projeto Godot do aplicativo de exemplo para referência

• Configure o projeto do Godot conforme desejado

  • Certifique-se de que a orientação definida para o projeto do Godot corresponda à definida no manifesto do aplicativo Android

  • Para o Android, certifique-se de que textures/vram_compression/import_etc2_astc esteja definido como true

• Atualize a lógica do script do projeto do Godot conforme necessário

  • Para o aplicativo de exemplo, a lógica do script consulta a instância do GodotPlugin em tempo de execução e a usa para se registrar nos sinais disparados pela lógica do aplicativo

  • A lógica do aplicativo dispara um sinal toda vez que um item é selecionado na lista. O sinal contém o caminho do arquivo do modelo glTF, que é usado pela lógica em gdscript para renderizar o modelo.

  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. Compile e execute o aplicativo

Assim que concluir a configuração do seu projeto do Godot, compile e execute o aplicativo Android. Se configurado corretamente, a Activity hospedeira inicializará o Godot Engine incorporado na inicialização. O Godot Engine verificará o diretório assets em busca de arquivos de projeto para carregar (a menos que configurado para procurar por um main pack) e prosseguirá com a execução do projeto.

Enquanto o aplicativo estiver sendo executado no dispositivo, você pode verificar o logcat do Android para investigar quaisquer erros ou falhas.

Para referência, verifique as instruções de compilação e instalação para o aplicativo de exemplo GLTF Viewer.