Exemplos

Os exemplos da Android Game Development Extension demonstram como usar os principais recursos da extensão. Neste tópico, descrevemos os exemplos e as configurações necessárias para executá-los.

Os exemplos a seguir estão disponíveis na página de downloads:

  • HelloJNI: um projeto introdutório.
  • Endless Tunnel: um projeto somente para Android.
  • Teapot: um projeto multiplataforma para Windows e Android.
  • AssemblyCode-Link-Objects: um projeto modelo que tem código-fonte assembly.

Antes de começar

  • Instale a Android Game Development Extension e os exemplos. Veja mais detalhes no guia de início rápido. O tópico também descreve como criar e executar um exemplo e usa a versão do Teapot para Android como exemplo.

  • O guia de configuração do projeto descreve como definir as configurações de um projeto que usa a extensão, por exemplo, a adição de uma Plataforma Android e um APK.

HelloJNI

O exemplo HelloJNI é um projeto simples que mostra uma mensagem “Hello From JNI” em uma janela do app. O projeto usa conjuntos diferentes de código-fonte para Windows e Android.

  • Diretório de scripts do build do Gradle e do código-fonte do Android: HelloJNI\AndroidPackaging
  • Diretório de projeto do Visual Studio e do código-fonte do Windows: HelloJNI

Durante a criação do projeto, o Visual Studio transmite as configurações a seguir para o arquivo build.gradle no nível do app. Para mudar essas configurações, modifique os scripts de build do Gradle.

  • MSBUILD_NDK_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Para configurar e executar o exemplo, faça o seguinte:

  1. No Visual Studio, abra e crie o exemplo HelloJNI.
  2. Adicione uma plataforma Android arm64-v8a. Para mais informações, consulte Como adicionar uma Plataforma Android.
  3. Adicione um item do APK do Android à nova plataforma.
  4. Compile o projeto.
  5. Adicione as Plataformas Android abaixo e, depois, adicione um item de APK do Android a cada uma delas: Android-armeabi-v7a, Android-x86 e Android-x86_64.
  6. Crie e execute o exemplo.

Endless-Tunnel

O exemplo Endless-Tunnel é um jogo para Android em que o jogador coleta cubos brancos enquanto tenta chegar ao final de um túnel. Ele foi portado de um exemplo do OpenGL no repositório do Android NDK no GitHub (link em inglês). O exemplo não fornece uma versão do jogo para Windows.

Ele já tem as próprias configurações e as Plataformas Android configuradas. Assim, você pode criar e executar o projeto no Visual Studio sem nenhuma modificação. Quando você abre a solução, o Solution Explorer mostra estes módulos:

  • endless-tunnel: o módulo do app que mostra a lógica do jogo.
  • glm: um snapshot do repositório Math do OpenGL (em inglês) criado como uma biblioteca estática.
  • native_app_glue: um wrapper do NDK que se comunica com o objeto NativeActivity.

Teapot

O exemplo Teapot mostra um bule clássico que é renderizado com o OpenGL ES e portado para a Android Game Development Extension para demonstrar os seguintes recursos:

  • Desenvolvimento de projetos multiplataforma: é possível criar o exemplo Teapot para Windows e Android.
  • Uso de pacotes personalizados do Android: os scripts de build do Gradle foram movidos para o diretório raiz do exemplo, onde o arquivo Teapot.sln está localizado.
  • Integração experimental de build do Ninja, que permite abrir o projeto no Android Studio.
  • Configurações personalizadas do Android que demonstram como usar Limpador de endereços (ASan) e Limpador de endereços de hardware (HWAsan).

A implementação do exemplo Teapot é dividida em várias partes, o que é comum para grandes apps e jogos multiplataforma:

  • Módulo GameApplication: define ações do usuário e estados do app, como um usuário girando o bule ou atualizando estatísticas do app.
  • Módulo GameEngine: implementa o módulo de renderização principal.

Para configurar o exemplo e executá-lo no Android, consulte o guia de início rápido. Para configurar o exemplo e executá-lo no Windows:

  1. Instale a GLEW:
    1. Faça o download da GLEW (link em inglês) e a descompacte.
    2. Copie os arquivos binários de $your-glew-directory\bin\Release\x64 para %SystemRoot%\system32.
  2. Instale o freeglut:
    1. Faça o download do freeglut (link em inglês) e o descompacte.
    2. Copie $your-freeglut-directory\bin\x86\freeglut.dll para %SystemRoot%\system32.
  3. Adicione as dependências do projeto freeglut:
    1. Abra Teapot.sln no Visual Studio.
    2. No menu, clique em Debug > x64 > Local Windows Debugger.
    3. No Solution Explorer, clique com o botão direito do mouse em GameApplication e escolha Properties > C/C++ > General > Additional Include Directories.
    4. Adicione $your-freeglut-dir\include ao caminho.
      Captura de tela da caixa de diálogo "Additional Include Directories".
    5. Clique em Ok.
    6. Selecione Linker > General > Additional Library Directories.
    7. Adicione $your-freeglut-dir\lib\x64 ao caminho. Captura de tela da caixa de diálogo "Additional Library Directories".
    8. Clique em Ok.
    9. Selecione Linker > General > Additional Library Directories.
    10. Adicione freeglut.lib ao caminho.
    11. Clique em Ok.
  4. Adicione as dependências do projeto GLEW:
    1. No painel Solution Explorer, clique com o botão direito do mouse em GameApplication e selecione Properties > C/C++ > General > Additional Include Directories.
    2. Adicione $your-glew-dir\include ao caminho.
    3. Clique em Ok.
    4. Selecione Linker > General > Additional Library Directories.
    5. Adicione $your-glew-dir\lib\Release\x86 ao caminho.
    6. Clique em Ok.
    7. Selecione Linker > General > Additional Library Directories.
    8. Adicione glew32.lib ao caminho.
    9. Clique em OK.
  5. Execute o exemplo no Windows:
    1. Na barra de ferramentas do Visual Studio, clique no botão de execução do Local Windows Debugger.
    2. O exemplo terá esta aparência:
      Captura de tela do exemplo Teapot em execução no Windows.

Este é um projeto de modelo que demonstra como gerar uma biblioteca nativa do Android usando o código-fonte C/C++ e assembly. Estes são os componentes principais:

  • AssemblyCode-Link-Objects: a principal biblioteca nativa do Android criada com base no C++ e no código-fonte assembly.
  • StaticLib: uma biblioteca estática auxiliar que exporta a função from_static_lib_assembly_code_as.

O projeto é compatível com várias arquiteturas. Cada arquitetura compatível tem os próprios arquivos de origem que implementam funções exportadas da StaticLib. Inclua apenas os arquivos de origem assembly das plataformas que você está criando. Esse projeto inclui arquivos assembly em builds usando ferramentas de build personalizadas (link em inglês).

Para configurar e criar o exemplo, faça o seguinte:

  1. No Visual Studio, verifique se as ferramentas de build personalizadas estão configuradas para os arquivos assembly:
    1. No Solution Explorer, clique com o botão direito do mouse no arquivo assembly e clique em Properties. Isso abre a caixa de diálogo Properties Pages do arquivo.
    2. Selecione a configuração e a plataforma, como All configurations para Android-arm64-v8a.
    3. Confira se General > Exclude from Build está definido como No.
    4. Confira se General > Item Type está definido como Custom Build Tool.
    5. Clique em Apply se tiver alguma mudança para aplicar.
    6. Confira se Configuration Properties > Custom Build Tools > Command Line: está definido como $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). O NDK inclui um assembler separado para cada arquitetura de CPU e $(AsToolExe) mapeia para o assembler correto. Esse exemplo usa o conjunto de ferramentas do NDK para criar projetos para o Android x86 e x86_64. Se você quiser usar yasm para a Plataforma Android x86_64, use $(YasmToolExe).
    7. Confira se Configuration Properties > Custom Build Tools > Outputs: está definido como $(IntDir)%(FileName).o. Essa string precisa ser incluída na configuração Command Line.
    8. Confira se Configuration Properties > Custom Build Tools > Link Objects está definido como Yes.

    Por exemplo, as configurações de Android-arm64-v8a precisam ser definidas como nesta captura de tela:

    Captura de tela da página de propriedades das ferramentas de build personalizadas.
  2. Crie o projeto. Isso cria o arquivo libAssmeblyCodeLinkObjects.so:
    1. Abra o arquivo AssemblyCode-Link-Objects.sln.
    2. No menu, clique em Build > Build Solution.
  3. Para confirmar se as funções foram exportadas corretamente para a biblioteca Android, use a ferramenta NDK nm.exe:
    1. Na linha de comando, acesse o diretório de exemplo.
    2. Acesse o local da biblioteca do Android que foi gerado pelo build. O local padrão é parecido com $sample_dir\$solution_configuration\$solution_platform\$platform e $sample_dir\Debug\Android-arm64-v8a\arm64-v8a para a plataforma arm64-v8a.
    3. Execute o seguinte comando para verificar se a seção de símbolo exportada contém as funções: 
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      Na saída, você verá uma lista de símbolos que inclui o seguinte: 

         T from_shared_object_assembly_code_as
   T from_static_lib_assembly_code_as