Como desenvolver com o emulador de desenvolvedor do Google Play Games no PC

Esse emulador é focado em desenvolvedores para Google Play Games no PC. Diferentemente da experiência para jogadores, ele permite instalar e depurar seus próprios pacotes. Também é possível simular várias configurações de jogador, como proporção, emulação de mouse e back-end gráfico, para ajudar a garantir que o jogo tenha o desempenho esperado em várias configurações de PC.

Como iniciar o emulador

Após a instalação, você terá um elemento de menu inicial chamado "Emulador de desenvolvedor do Google Play Games" e um atalho na área de trabalho para iniciar o emulador. O emulador vai permanecer na bandeja do sistema quando você fechar a janela.

Observação: não é possível executar os emuladores de desenvolvedor e de consumidor do Google Play Games no PC ao mesmo tempo. É necessário sair da bandeja do sistema antes de iniciar a outra.

Fazer login

Na primeira execução do emulador, será necessário fazer login na sua Conta do Google. Use as mesmas credenciais de login que você planeja usar para o desenvolvimento.

Para sair, clique com o botão direito do mouse no ícone da bandeja do sistema, selecione Opções do desenvolvedor e clique em Forçar saída. Quando você faz isso, o emulador é reiniciado imediatamente e pede para você fazer login de novo.

Cuidado: a imagem do dispositivo local, incluindo os jogos instalados, é limpa quando você sai.

Navegação

Após a inicialização, uma tela inicial típica do Android será mostrada. Os cliques com o botão esquerdo do mouse são convertidos diretamente em toques com o dedo, como no modo de emulação do mouse. Os jogos transferidos por sideload para desenvolvimento aparecem na lista de aplicativos, que você pode acessar clicando na área de trabalho e arrastando para cima. Isso emula um gesto de deslizar para cima em um smartphone ou tablet.

Além da conversão do mouse, o emulador de desenvolvedor do Google Play Games no PC oferece atalhos de teclado para melhorar a navegação:

• Ctrl + h: pressionar o botão home.
• Ctrl + b: pressionar o botão "Voltar".
• F11 ou Alt + Enter: alternar entre o modo de tela cheia e de janela.
• Shift + Tab: abrir a sobreposição do Google Play Games no PC, incluindo os mapeamentos de teclas atuais para o SDK de entrada.

Observação: Ctrl + h e Ctrl + b são fornecidos apenas para fins de desenvolvimento. Não dependa desses atalhos para a versão final do seu jogo.

Como instalar um jogo

O emulador de desenvolvedor do Google Play Games no PC usa o Android Debug Bridge (adb) para instalar pacotes.

Compatibilidade com adb

As versões atuais do adb são compatíveis com o emulador de desenvolvedor do Google Play Games no PC. Além disso, uma versão compatível é instalada em C:\Program Files\Google\Play Games Developer Emulator\current\emulator quando você instala o emulador.

Para seguir estas instruções, o adb precisa estar disponível no seu $PATH. Use o comando adb devices para verificar se o adb está configurado corretamente.

adb devices
List of devices attached
localhost:6520  device

Observação :se preferir não modificar a variável $PATH, execute o terminal em C:\Program Files\Google\Play Games Developer Emulator\current\emulator. Alguns shells vão exigir que você digite ./adb em vez do adb, dependendo de quando fizer isso.

Instalar o jogo

• Abra o Google Play Games for PC Emulator.

• Digite adb devices no prompt de comando. O seguinte será mostrado:

  adb devices
  List of devices attached
  localhost:6520 device
  

• Solução de problemas:

  • Se você receber um erro, verifique se seguiu as instruções mostradas na seção Compatibilidade com adb.
  • Se um dispositivo não for mostrado, tente se reconectar pela porta 6520:

  adb connect localhost:6520
  

• Digite adb install path\to\your\game.apk para instalar o jogo. Se você tiver gerado um Android App Bundle (AAB), consulte as instruções da bundletool e use bundletool install-apks.

• Para executar seu jogo, siga uma destas instruções:

  • Digite adb shell monkey -p your.package.name 1, substituindo your.package.name pelo nome do pacote.
  • No emulador de desenvolvedor do Google Play Games no PC, clique no ícone para executar o jogo. Assim como em um smartphone Android, você precisa "deslizar para cima" na tela inicial para acessar a lista de jogos instalados.

Como depurar um jogo

Use o Android Debug Bridge (adb) para depurar, assim como faz com qualquer outro jogo. O emulador aparece como um dispositivo conectado via localhost:6520.

O adb logcat funciona como esperado, assim como as ferramentas que ajudam a melhorar ou filtrar a saída do Logcat, incluindo o Android Studio.

Além do adb, os registros podem ser acessados no diretório %LOCALAPPDATA%\Google\Play Games Developer Emulator\Logs. O mais útil aqui é AndroidSerial.log, que representa tudo o que o adb logcat ecoaria a partir do momento em que o emulador for iniciado.

Observação: %LOCALAPPDATA% normalmente se expande para C:\Users\<username>\AppData\Local

Configurações do desenvolvedor

O emulador de desenvolvedor do Google Play Games no PC se concentra na eficiência do desenvolvedor, não na experiência do usuário final. Isso significa que você tem acesso livre ao sistema Android, incluindo o uso da tela de início padrão do Android em vez da experiência do Google Play Games no PC. Além disso, você tem controle sobre os recursos que são ativados e desativados automaticamente para os jogadores.

Como testar a entrada do mouse

Durante o desenvolvimento, o emulador de desenvolvedor do Google Play Games no PC usa a emulação de toque por padrão, em vez de oferecer a entrada direta pelo mouse. É possível ativar essa entrada clicando com o botão direito do mouse no ícone da bandeja do sistema, selecionando Opções do desenvolvedor e depois Modo PC (KiwiMouse).

O Google Play Games no PC tem dois modos de mouse: um emulado que converte cliques do mouse em toques únicos e um "modo PC" de passagem, que permite aos jogos processar ações do mouse de forma nativa e realizar captura de ponteiro. Para detalhes sobre a entrada do mouse no Google Play Games no PC, consulte Configurar a entrada do mouse.

No cliente do jogador, a emulação é desativada pela adição dela ao manifesto:

<manifest ...>
  <uses-feature
      android:name="android.hardware.type.pc"
      android:required="false" />
  ...
</manifest>

Essa flag de recurso não tem efeito no ambiente de desenvolvimento.

Como testar proporções

O emulador do desenvolvedor é iniciado em uma proporção de 16:9, ao contrário do cliente do jogador, que deriva a proporção da tela principal. Ao clicar com o botão direito do mouse no ícone da bandeja do sistema, selecionar Opções do desenvolvedor e, em seguida, qualquer opção na seção Proporção da tela, você poderá testar a aparência do jogo em diferentes telas do player.

O método preferido para configurar a proporção é usar android:minAspectRatio e android:maxAspectRatio.

Por exemplo, um jogo em modo retrato teria uma proporção de 9/16 ou 0.5625, então seria recomendável definir uma proporção máxima de 1 para evitar que ele fique mais largo do que quadrado:

<activity android:maxAspectRatio="1">
 ...
</activity>

Da mesma forma, um jogo em modo paisagem teria uma proporção de 16/9 ou aproximadamente 1.778, então você poderia definir uma proporção mínima de 1 para evitar que ele fique mais fino do que quadrado:

<activity android:minAspectRatio="1">
 ...
</activity>

Observação: na prática, os jogos não funcionam bem quando se aproximam de proporções quadradas. Encontre um valor que faça sentido nos seus testes em dispositivos Android.

O que testar

Se o jogo só oferece suporte ao modo retrato no manifesto, selecione 9:16 (retrato) no menu suspenso para conferir a aparência dele em PCs de jogadores. Caso contrário, verifique se o jogo funciona nas proporções mais largas e mais estreitas com suporte no manifesto. Lembre-se de que a opção 16:9 (padrão), ou 9:16 (retrato) se o jogo for destinado apenas ao modo retrato, é necessária para a certificação completa.

Como testar back-ends de renderização

O Google Play Games no PC usa o ANGLE como camada de compatibilidade para garantir que as chamadas do OpenGL ES sejam processadas corretamente pelo PC host usando um back-end DirectX ou Vulkan. O emulador também oferece suporte diretamente ao Vulkan, mas não ao DirectX. Essa camada também converte formatos de textura compactados somente para dispositivos móveis em formatos compatíveis com PC. Ao clicar com o botão direito do mouse no ícone da bandeja do sistema e selecionar Graphics Stack Override, é possível definir essa opção como padrão do sistema ou forçar a ativação ou desativação do Vulkan para testes de compatibilidade.

O que testar

Há pequenas variações nos formatos de textura disponíveis e nas etapas necessárias para emular vários recursos para dispositivos móveis no computador. Ao criar perfis e otimizar seu jogo, é recomendável verificar cada back-end.

Como criar o perfil do jogo para PC

Como o emulador usa a mesma tecnologia do cliente do consumidor, esse é um ambiente adequado para a criação de perfis de performance.

O Perfetto é uma ferramenta para analisar a performance no Android. É possível coletar e visualizar um rastro do Perfetto seguindo estas etapas:

1. Em um prompt do PowerShell, inicie um rastro usando adb.

   adb shell perfetto --time 10s gfx wm sched --out /data/misc/perfetto-traces/example.trace
   

   1. A flag --time especifica a duração do rastro a ser coletado. Neste exemplo, o rastro tem 10 segundos.
   2. Os argumentos após a flag --time indicam quais eventos serão rastreados. Neste exemplo, gfx indica gráficos, gerenciamento de janelas wm e informações de programação de processos sched. Essas são flags comuns para caracterizar os perfis de jogos, e há uma referência completa disponível.
   3. A flag --out especifica o arquivo de saída, que é extraído do emulador para a máquina host na próxima etapa.

2. Extrair o rastro do host

   adb pull /data/misc/perfetto-traces/example.trace $HOME/Downloads/example.trace
   

3. Abrir o rastro na interface do Perfetto

   1. Abra ui.perfetto.dev (link em inglês).
   2. Selecione Open trace file no canto superior esquerdo em Navigation.
   3. Abra o arquivo example.trace que você salvou na etapa anterior no diretório Downloads/.

4. Inspecione o rastro na interface do Perfetto. Confira algumas dicas:

   1. Cada processo tem a própria linha, que pode ser expandida para mostrar todas as linhas de execução nesse processo. Se você estiver criando um perfil para um jogo, esse processo provavelmente será a primeira linha.
   2. Para aumentar e diminuir o zoom, mantenha a tecla Control pressionada e use a roda de rolagem.
   3. Ao usar o evento sched, há uma fileira para cada linha de execução que aparece quando o estado dela está em execução, executável, em suspensão ou bloqueada.
   4. Ao ativar um evento como gfx, você pode conferir as diversas chamadas gráficas feitas por diferentes linhas de execução. Você pode selecionar "fatias" individuais para saber quanto tempo elas levaram. Também pode arrastar ao longo de uma fileira fazendo com que uma seção de "fatias" abra na parte de baixo e mostre quanto tempo todas as fatias levaram na janela de tempo selecionada.

Caracterização de perfil gráfico

Cuidado: a anexação do RenderDoc só funciona no emulador do desenvolvedor e não é oficialmente compatível.

É possível executar a caracterização de perfil gráfico com o RenderDoc.

Observação: o Renderdoc só pode detectar a saída do emulador depois que as instruções do jogo são traduzidas do convidado para o sistema operacional do host.

1. Defina a variável de ambiente ANDROID_EMU_RENDERDOC como uma string não vazia (por exemplo, "1").

2. Defina a variável de ambiente TMP como %USERPROFILE%\AppData\LocalLow. Isso instrui o RenderDoc a colocar os arquivos de registro em algum lugar acessível no sandbox do emulador.

   Observação: talvez seja necessário sair e fazer login novamente.

3. Se você estiver usando o back-end Vulkan. Selecione Graphics Settings > Vulkan Instance Implicit Layers e verifique se VKLAYER_RENDERDOC_Capture está marcada.

   Observação: as mudanças nas configurações gráficas exigem que o emulador seja reiniciado para entrar em vigor.

4. Inicie o emulador de desenvolvedor do Google Play Games no PC. Uma sobreposição do RenderDoc é desenhada na parte superior, desde que seja compatível.

5. Inicie o RenderDoc a qualquer momento antes ou depois de iniciar o emulador de desenvolvedor do Google Play Games no PC.

6. Clique em Arquivo > Anexar à instância em execução e selecione crosvm.

Especificar variáveis de ambiente

Para que o RenderDoc funcione, adicione ou altere as variáveis de ambiente no Windows. É possível alterar as variáveis de ambiente usando a interface, o PowerShell ou cmd.exe.

Usar a interface

• Pressione Win+R para abrir a caixa de diálogo Run.
• Digite sysdm.cpl para abrir a janela Propriedades do sistema.
• Selecione a guia Avançado se ela ainda não estiver ativa.
• Clique no botão Variáveis de ambiente.

Aqui, você pode clicar no botão Nova para criar uma nova variável de ambiente ou selecionar uma variável e clicar no botão Editar para editá-la.

Usar o PowerShell

Em uma janela do PowerShell, digite:

$Env:VARIABLE_NAME=VALUE

Substitua VARIABLE_NAME e VALUE pelos valores que você quer definir. Por exemplo, para definir ANDROID_EMU_RENDERDOC como "1":

$Env:ANDROID_EMU_RENDERDOC="1"

Usar cmd.exe

Em uma janela cmd.exe, digite:

set VARIABLE_NAME=VALUE

Substitua VARIABLE_NAME e VALUE pelos valores que você quer definir. Por exemplo, para definir ANDROID_EMU_RENDERDOC como "1":

set ANDROID_EMU_RENDERDOC="1"

Dicas para o Android 11 (nível 30 da API) ou versões mais recentes

O Google Play Games no PC está atualizado com as versões mais recentes do Android. Confira algumas dicas para trabalhar com a versão mais recente do Android.

Manter as ferramentas atualizadas

O Android Studio instala uma versão do adb compatível com o emulador de desenvolvedor. No entanto, alguns mecanismos de jogo incluem uma versão mais antiga. Nesse caso, depois de instalar o emulador, você pode encontrar uma versão compatível do adb em C:\Program Files\Google\Play Games Developer Emulator\current\emulator.

Se você iniciar uma versão do adb, a outra será encerrada. Isso significa que, se o mecanismo de jogo iniciar automaticamente a própria instância do adb, talvez seja necessário reiniciar e reconectar a versão do adb que acompanha o emulador sempre que você fizer uma implantação.

Se você estiver usando o Android App Bundle, precisará instalar a versão mais recente da bundletool no repositório do GitHub.

Armazenamento com escopo

O Android 11 (nível 30 da API) ou versões mais recentes incluem o armazenamento com escopo, que oferece mais proteção para dados de apps e de usuários no armazenamento externo. Além de tornar seu jogo compatível com requisitos de armazenamento com escopo, é preciso executar etapas extras para carregar arquivos de expansão do APK (OBB) ou dados de recursos ao emulador de desenvolvedor do Google Play Games no PC. Siga as etapas abaixo se tiver problemas para acessar esses arquivos no seu jogo:

1. Crie um diretório que seu app possa ler.
2. Envie os arquivos de expansão para o emulador.

adb shell mkdir /sdcard/Android/obb/com.example.game
adb push main.com.example.game.obb /sdcard/Android/obb/com.example.game

Visibilidade do pacote

Devido às novas regras de visibilidade do pacote, os apps direcionados ao Android 11 (nível 30 da API) ou versões mais recentes não podem mais consultar informações sobre os outros apps instalados em um dispositivo. Isso significa que seu jogo não poderá acessar o Google Play Services quando transferido por sideload pelo adb em vez de ser instalado pela Play Store. Para testar sua compra no app com um jogo transferido por sideload, adicione uma consulta ao pacote "com.android.vending" no arquivo AndroidManifest.xml da seguinte maneira:

<manifest>
    <queries>
        <package android:name="com.android.vending" />
    </queries>
</manifest>

Observação: não é necessário adicionar isso na versão de lançamento do jogo distribuída pela Play Store.

Como instalar o jogo no cliente do consumidor

Não é possível instalar um jogo no cliente do consumidor até que ele esteja listado no catálogo dos serviços relacionados a jogos do Google Play. Depois que seu jogo tiver uma única versão, você poderá criar uma faixa de teste interno para validar as atualizações futuras antes do lançamento.

O cliente do jogador não tem suporte aos recursos focados no desenvolvedor do emulador do Google Play Games no PC. Ele é mais recomendado para fazer o controle de qualidade do jogo antes do lançamento e testar a experiência completa do jogador após o lançamento inicial.