Guia de início rápido

Configure a Android Game Development Extension em um computador Windows e execute um projeto de exemplo do Visual Studio C++ em um dispositivo ou emulador Android.

Pré-requisitos

Siga as etapas nesta seção para preparar o computador Windows para a instalação da extensão:

1. Faça o download de uma das versões compatíveis do Visual Studio e instale-a:

   • Visual Studio 2017 versão 15.4.0 (9 de outubro de 2017) ou mais recente.
   • Visual Studio 2019 versão 16.0.0 ou mais recente
   • Visual Studio 2022 versão 17.0.0 ou mais recente

2. Faça o download do SDK .NET Core 2.2 e instale-o.

3. O Android Studio 3.5 ou versões mais recentes é opcional, mas pode ser usado no lugar da Android Game Development Extension para instalar o NDK e SDK do Android.

4. Faça o download e instale o JDK 17 para AGDE 23.1.82 ou mais recente ou JDK 11 para até AGDE 22.2.71 e defina sua variável de ambiente JAVA_HOME.

Instalar a extensão

Siga as etapas desta seção para fazer o download da Android Game Development Extension e instalá-la:

1. Feche todas as instâncias do Visual Studio.

2. Faça o download do instalador e dos exemplos mais recentes da extensão na página Downloads.

3. No local de download, clique duas vezes no instalador, que pode levar vários minutos para ser concluído.

4. Se você tiver mais de uma versão do Visual Studio instalada, selecione as versões em que quer que a extensão seja instalada.

5. Clique em Concluir para concluir a instalação.

Instalar o NDK e o SDK do Android

É possível instalar o SDK do Android e o Android Native Development Kit (NDK) com o Android Studio ou a Android Game Development Extension. Para instalar o SDK e o NDK pela extensão, use o SDK Manager, localizado na barra de ferramentas de extensão do Visual Studio.

Ao instalar o NDK, use a caixa de seleção NDK (Side by side) para que a extensão possa localizá-lo. É necessário instalar uma versão do NDK que seja compatível com a extensão (consulte o Histórico de revisões do NDK):

Para instalar o SDK em um local diferente do padrão, defina a variável de ambiente ANDROID_SDK_ROOT no seu computador:

1. Verifique se o Visual Studio está fechado.
2. Na Pesquisa do Windows, pesquise por Environment Variables.
3. Selecione Editar as variáveis de ambiente do sistema.
4. Clique em Variáveis de ambiente.
5. Em Variáveis de usuário, clique em Nova.
6. Na caixa Nome da variável, digite ANDROID_SDK_ROOT.
7. Na caixa Valor da variável, insira o caminho do SDK do Android.
8. Reinicialize o computador.

Não é possível modificar o local do SDK usando a janela do SDK Manager, já que essa variável de ambiente é a única fonte de verdade para o local do SDK.

Executar o exemplo

Siga as etapas desta seção para executar um exemplo fornecido em um emulador e, em seguida, em um dispositivo Android físico.

Configurar a plataforma

1. Descompacte o arquivo ZIP de exemplo em um diretório da sua escolha. Os exemplos a seguir estão incluídos:

   • endless-tunnel
   • HelloJNI
   • Teapot (usa integração experimental de build do Ninja)

2. Inicie o Visual Studio se ainda não tiver feito isso.

3. Abra o diretório de exemplos. Selecione File > Open > Project/Solution e navegue até o arquivo .sln.

4. Selecione uma Plataforma Android:

   1. Selecione Compilação > Configuration Manager.
   2. Em Plataforma de solução ativa, selecione Android-x86_64.

   As plataformas Android já estão configuradas nos exemplos. Consulte Adicionar mais plataformas Android para adicionar plataformas.

   Observação: imagens típicas do emulador usam as ABIs x86 ou x86_64.

5. Verifique se as propriedades do NDK e do SDK do Android do projeto de exemplo estão configuradas:

   

   Figura 1. Propriedades da Plataforma Android.

   • No Solution Explorer, clique com o botão direito do mouse no projeto e selecione Properties.

   • Selecione a guia de propriedades Geral e localize as propriedades da Plataforma para Android.

   Observação: selecione um NDK instalado.

6. Selecione a guia de propriedades Empacotamento do Android.

   

   Figura 2. Propriedades de empacotamento do Android.

   É possível alterar a saída do nome e do diretório do APK nessa guia. Algumas das propriedades de configuração do Android são definidas nas páginas de propriedades e transmitidas ao Gradle. Por exemplo, a propriedade de nome do APK MSBUILD_ANDROID_OUTPUT_APK_NAME transmite esse nome para o arquivo build.gradle do app.

Configurar o emulador

1. Inicie o AVD Manager na barra de ferramentas da extensão no Visual Studio. Configure um dispositivo virtual e execute-o no Android Emulator.

   1. Na janela Android Virtual Device Manager, clique em Create Virtual Device.
   2. Escolha uma definição de dispositivo (por exemplo, Pixel 2).
   3. Selecione uma imagem do sistema. Selecione uma ABI x86_64 porque essa arquitetura é executada mais rapidamente no emulador.
   4. Verifique a configuração e clique em Finish.

2. Inicie o dispositivo virtual clicando no botão Run na ferramenta Android Virtual Device Manager.

3. No Visual Studio, o dispositivo virtual aparece ao lado do botão Iniciar depuração da barra de ferramentas. Clique em Iniciar depuração para iniciar o app de exemplo no dispositivo. Pode levar alguns instantes para o depurador ser conectado ao app. Se você estiver executando o exemplo Teapot, poderá girar o bule arrastando o cursor do mouse sobre ele.

   
   Figura 3. Exemplo do Teapot em execução no Android Emulator.

Configurar o dispositivo

1. Para executar o exemplo em um dispositivo Android físico, talvez seja necessário criar uma nova Plataforma Android no projeto. Essa plataforma precisa usar a mesma arquitetura do dispositivo. Para criar uma nova plataforma, faça o seguinte no Visual Studio:

   1. Selecione Compilação > Configuration Manager.
   2. Em Plataforma de solução ativa, selecione <Nova>.

   3. Digite uma das seguintes opções para a nova plataforma:

      • Android-armeabi-v7a (link em inglês)
      • Android-arm64-v8a
      • Android x86
      • Android-x86_64 (link em inglês)

   4. Na caixa Copiar configurações de, selecione outra plataforma Android (ou Nenhuma se você ainda não tiver nenhuma Plataforma Android). Verifique se você ativou a opção Criar novas plataformas de projeto.

2. Conecte um dispositivo Android ao computador usando um cabo USB. O tipo de dispositivo precisa ser exibido ao lado do botão Iniciar depuração.

   
   Figura 4. Dispositivo Android conectado mostrado ao lado do botão Iniciar depuração da barra de ferramentas.

   Se o dispositivo não for exibido, verifique o seguinte:

   • a plataforma selecionada corresponde à ABI do dispositivo.
   • você ativou as Opções do desenvolvedor e a depuração USB no dispositivo;
   • o dispositivo está conectado ao computador com o cabo USB;
   • o cabo USB é compatível com uma conexão de dados e não apenas de energia;

3. Clique no botão Iniciar depuração da barra de ferramentas para iniciar o app de exemplo no dispositivo. Pode levar alguns instantes para o depurador ser conectado ao app. Depois disso, você poderá interagir com o app no seu dispositivo.

Perguntas frequentes

Veja a seguir algumas perguntas frequentes sobre a Android Game Development Extension.

Em que local os registros do plug-in são armazenados?

É possível abrir o arquivo de registros do plug-in usando o ícone Open Logs na barra de ferramentas Android Game Development Extension.

Quais variáveis de ambiente são usadas pelo plug-in?

O plug-in usa as seguintes variáveis de ambiente:

• ANDROID_SDK_ROOT
• ANDROID_SDK_HOME
• TEMP
• GOOGLE_ANDROID_LOG_DIR

Próxima etapa

Para usar seu próprio projeto com a extensão, é preciso configurá-lo de acordo com o guia de configuração de projeto.