Desenvolvimento Android

Dispositivos Android permitem que você execute livremente seus próprios aplicativos neles. É muito fácil criar uma versão do seu jogo e copiá-la para um dispositivo Android. Este manual explica as etapas envolvidas em empacotar seu jogo para Android. Durante o desenvolvimento, executar seu jogo pelo aplicativo de desenvolvimento muitas vezes é preferível, pois permite usar hot reload de conteúdo e código diretamente no seu dispositivo.

Processo de assinatura Android e Google Play

O Android exige que todos os APKs sejam assinados digitalmente com um certificado antes de serem instalados em um dispositivo ou atualizados. Se você usar Android App Bundles, precisa assinar apenas seu app bundle antes de enviá-lo para o Play Console, e o Play App Signing cuida do resto. No entanto, você também pode assinar manualmente seu aplicativo para envio para o Google Play, outras lojas de aplicativos e para distribuição fora de qualquer loja.

Quando você cria um pacote de aplicativo Android a partir do editor Defold ou da ferramenta de linha de comando, você pode fornecer um keystore (contendo seu certificado e chave) e a senha do keystore que serão usados ao assinar sua aplicação. Se você não fornecer, o Defold gera um keystore de depuração e o usa ao assinar o pacote de aplicativo.

Criando um keystore

Você pode criar um keystore usando o Android Studio ou a partir de um terminal/prompt de comando:

keytool -genkey -v -noprompt -dname "CN=John Smith, OU=Area 51, O=US Air Force, L=Unknown, ST=Nevada, C=US" -keystore mykeystore.keystore -storepass 5Up3r_53cR3t -alias myAlias -keyalg RSA -validity 9125

Isso irá criar um arquivo keystore chamado mykeystore.keystore contendo uma chave e certificado. O acesso à chave e certificado será protegido pela senha 5Up3r_53cR3t. A chave e o certificado serão válidos por 25 anos (9125 dias). A chave e o certificado gerados serão identificados pelo alias myAlias.

Criando um pacote de aplicativo Android

O editor permite criar facilmente um pacote de aplicativo independente para seu jogo. Antes de empacotar, você pode especificar qual(is) ícone(s) usar para o aplicativo, definir o código de versão etc. no arquivo game.project de configurações do projeto.

Para empacotar, selecione Project ▸ Bundle... ▸ Android Application... no menu.

Se você quiser que o editor crie automaticamente certificados de depuração aleatórios, deixe os campos Keystore e Keystore password vazios:

Se você quiser assinar seu bundle com um keystore específico, especifique o Keystore e Keystore password. Espera-se que o Keystore tenha a extensão de arquivo .keystore, enquanto a senha deve ser armazenada em um arquivo de texto com a extensão .txt. Também é possível especificar uma Key password se a chave no keystore usar uma senha diferente do próprio keystore:

O Defold tem suporte à criação de arquivos APK e AAB. Selecione APK ou AAB no menu suspenso Bundle Format.

Pressione Create Bundle quando tiver configurado as definições do pacote de aplicativo. Em seguida, você será solicitado a especificar onde em seu computador o pacote será criado.

Variantes de build

Ao empacotar um jogo, você precisa escolher que tipo de engine deseja usar. Você tem três opções básicas:

• Debug
• Release
• Headless

Essas versões diferentes também são chamadas de Build variants

Debug

Este tipo de executável é normalmente usado durante o desenvolvimento de um jogo, pois inclui vários recursos úteis de depuração:

• Profiler - Usado para coletar contadores de desempenho e uso. Aprenda a usar o profiler no manual de profiling.
• Logging - A engine registrará informações do sistema, avisos e erros quando o logging estiver habilitado. A engine também emitirá logs da função Lua print() e de logs de extensões nativas usando dmLogInfo(), dmLogError() e assim por diante. Aprenda a ler esses logs no manual de logs do jogo e do sistema.
• Hot reload - Hot reload é um recurso poderoso que permite ao desenvolvedor recarregar recursos enquanto o jogo está em execução. Aprenda a usá-lo no manual de Hot Reload.
• Engine services - É possível conectar-se e interagir com uma versão de debug de um jogo por meio de várias portas TCP abertas e serviços. Os serviços incluem o recurso de hot reload, acesso remoto a logs e o profiler mencionado acima, além de outros serviços para interagir remotamente com a engine. Saiba mais sobre os serviços da engine na documentação do desenvolvedor.

Release

Esta variante tem os recursos de depuração desabilitados. Esta opção deve ser escolhida quando o jogo estiver pronto para ser lançado na loja de aplicativos ou compartilhado com jogadores de outras formas. Não é recomendado lançar um jogo com os recursos de depuração habilitados por vários motivos:

• Os recursos de depuração ocupam um pouco de espaço no binário, e é uma boa prática tentar manter o tamanho do binário de um jogo lançado o menor possível.
• Os recursos de depuração também consomem um pouco de tempo de CPU. Isso pode impactar o desempenho do jogo se um usuário tiver hardware de baixo desempenho. Em celulares, o aumento de uso da CPU também contribuirá para aquecimento e consumo de bateria.
• Os recursos de depuração podem expor informações sobre o jogo que não foram feitas para os olhos dos jogadores, seja por motivos de segurança, trapaça ou fraude.

Headless

Este executável roda sem gráficos nem som. Isso significa que você pode rodar testes unitários/de smoke do jogo em um servidor de CI, ou até usá-lo como servidor de jogo na nuvem.

Instalando um pacote de aplicativo Android

Instalando um APK

Um arquivo .apk pode ser copiado para seu dispositivo com a ferramenta adb ou para o Google Play através do console do desenvolvedor do Google Play.

A ferramenta de linha de comando adb é um programa fácil de usar e versátil usado para interagir com dispositivos Android. Você pode baixar e instalar o adb como parte do Android SDK Platform-Tools, para macOS, Linux ou Windows.

Baixe o Android SDK Platform-Tools em: https://developer.android.com/studio/releases/platform-tools. Você encontrará a ferramenta adb em /platform-tools/. Como alternativa, pacotes específicos de plataforma podem ser instalados pelos respectivos gerenciadores de pacotes.

No Ubuntu Linux:

$ sudo apt-get install android-tools-adb

No Fedora 18/19:

$ sudo yum install android-tools

No macOS (Homebrew)

$ brew cask install android-platform-tools

Você pode verificar se o adb funciona conectando seu dispositivo Android ao computador via USB e executando o seguinte comando:

$ adb devices
List of devices attached
31002535c90ef000    device

Se o seu dispositivo não aparecer, verifique se você habilitou USB debugging no dispositivo Android. Abra Settings no dispositivo e procure por Developer options (ou Development).

$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
  pkg: /data/local/tmp/my_app.apk
Success

Instalando um APK usando o editor

Você pode instalar e iniciar um arquivo .apk usando as caixas de seleção “Install on connected device” e “Launch installed app” no diálogo Bundle do editor:

Para que este recurso funcione, você precisará ter o ADB instalado e a Depuração USB (USB debugging) habilitada no dispositivo conectado. Se o editor não conseguir detectar a localização de instalação da ferramenta de linha de comando ADB, você precisará especificá-la nas Preferências.

Instalando um AAB

Um arquivo .aab pode ser enviado para o Google Play através do console do desenvolvedor do Google Play. Também é possível gerar um arquivo .apk a partir de um arquivo .aab para instalá-lo localmente usando o Android bundletool.

Permissões

A engine Defold requer várias permissões diferentes para que todos os recursos da engine funcionem. As permissões são definidas no AndroidManifest.xml, especificado no arquivo game.project de configurações do projeto. Você pode ler mais sobre permissões Android na documentação oficial. As seguintes permissões são solicitadas no manifesto padrão:

android.permission.INTERNET e android.permission.ACCESS_NETWORK_STATE (Nível de proteção: normal)

Permite que aplicativos abram soquetes de rede (network sockets) e acessem informações sobre redes. Essas permissões são necessárias para acesso à internet. (Documentação oficial Android) e (Documentação oficial Android).

android.permission.WAKE_LOCK (Nível de proteção: normal)

Permite usar PowerManager WakeLocks para impedir que o processador entre em modo de suspensão ou que a tela escureça. Esta permissão é necessária para impedir temporariamente que o dispositivo entre em suspensão enquanto recebe uma notificação push. (Documentação oficial Android)

Usando AndroidX

O AndroidX é uma grande melhoria em relação à biblioteca de suporte Android original, que não é mais mantida. Os pacotes AndroidX substituem completamente a Biblioteca de Suporte, fornecendo paridade de recursos e novas bibliotecas. A maioria das extensões Android no Portal de Assets suporta AndroidX. Se você não deseja usar o AndroidX, pode explicitamente desativá-lo em favor da antiga Biblioteca de Suporte Android marcando a opção Use Android Support Lib no manifesto da aplicação.

FAQ

P: É possível ocultar as barras de navegação e status no Android?

R: Sim, defina a configuração immersive_mode na seção Android do seu arquivo game.project. Isso permite que seu aplicativo ocupe a tela inteira e capture todos os eventos de toque na tela.

P: Por que recebo “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]” ao instalar um jogo Defold no dispositivo?

R: O Android detecta que você está tentando instalar o aplicativo com um novo certificado. Ao empacotar builds de debug, cada build será assinada com um certificado temporário. Desinstale o aplicativo antigo antes de instalar a nova versão:

$ adb uninstall com.defold.examples
Success
$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
      pkg: /data/local/tmp/Defold examples.apk
Success

P: Por que recebo erros sobre propriedades conflitantes em AndroidManifest.xml ao compilar com certas extensões?

R: Isso pode acontecer quando duas ou mais extensões fornecem um stub de Android Manifest que contém a mesma tag de propriedade, mas com valores diferentes. Isso já aconteceu, por exemplo, com Firebase e AdMob. O erro de build se parece com isto:

SEVERE: /tmp/job4531953598647135356/upload/AndroidManifest.xml:32:13-58
Error: Attribute property#android.adservices.AD_SERVICES_CONFIG@resource
value=(@xml/ga_ad_services_config) from AndroidManifest.xml:32:13-58 is also
present at AndroidManifest.xml:92:13-59 value=(@xml/gma_ad_services_config).
Suggestion: add 'tools:replace="android:resource"' to <property> element at
AndroidManifest.xml to override.

Você pode ler mais sobre o problema e a solução alternativa na issue do Defold relatada #9453 e na issue do Google #327696048.