Muestras

En las muestras de Android Game Development Extension, se explica cómo usar las funciones clave de la extensión. En este tema, se describen las muestras y los parámetros de configuración necesarios para ejecutarlas.

Las siguientes muestras están disponibles en la página de descargas:

  • HelloJNI: Un proyecto introductorio
  • Endless-Tunnel: Un proyecto solo para Android
  • Teapot: Un proyecto multiplataforma para Windows y Android
  • AssemblyCode-Link-Objects: Un proyecto de plantillas con código fuente de ensamblado

Antes de comenzar

  • Instala Android Game Development Extension y las muestras. Consulta la guía de inicio rápido para obtener más detalles. En el tema, también se describe cómo compilar y ejecutar una muestra. Como ejemplo, se usa la versión de Android de la muestra de Teapot.

  • En la guía de configuración de proyecto, se describe cómo establecer la configuración de un proyecto que usa la extensión, como agregar una plataforma de Android y un APK.

HelloJNI

HelloJNI es un proyecto simple que muestra un mensaje "Hello from JNI" en la ventana de una app. El proyecto usa un conjunto diferente de código fuente para Windows y Android.

  • Código fuente de Android y directorio de secuencias de comandos de compilación de Gradle: HelloJNI\AndroidPackaging
  • Código fuente de Windows y directorio del proyecto de Visual Studio: HelloJNI

Cuando creas el proyecto, Visual Studio pasa los siguientes parámetros de configuración al archivo build.gradle al nivel de la app. Puedes cambiar esta configuración si modificas las secuencias de comandos de compilación de 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 y ejecutar la muestra, haz lo siguiente:

  1. En Visual Studio, abre y compila la muestra de HelloJNI.
  2. Agrega una plataforma Android arm64-v8a. Para obtener más información, consulta Cómo agregar una plataforma de Android.
  3. Agrega un elemento de APK de Android a la nueva plataforma.
  4. Compila el proyecto.
  5. Agrega las siguientes plataformas de Android y, luego, un elemento de APK de Android a cada una de ellas: Android-armeabi-v7a, Android-x86 y Android-x86_64.
  6. Compila y ejecuta la muestra.

Endless-Tunnel

La muestra de Endless-Tunnel es un juego para Android en el que el jugador recolecta cubos blancos mientras intenta llegar al final de un túnel. Se transfirió de una muestra de OpenGL en el repositorio del NDK de Android en GitHub. La muestra no proporciona una versión para Windows del juego.

La muestra ya cuenta con sus propios parámetros y plataformas de Android configurados, por lo que puedes compilar y ejecutar el proyecto en Visual Studio sin realizar modificaciones. Cuando abras la solución, Solution Explorer mostrará los siguientes módulos:

  • endless-tunnel: El módulo de aplicación que muestra la lógica del juego
  • glm: Un resumen del OpenGL Math repo que se compiló como biblioteca estática
  • native_app_glue: Un wrapper del NDK que se comunica con el objeto NativeActivity

Teapot

En la muestra de Teapot, se observa una tetera clásica que se renderiza con OpenGL ES y se transfiere a Android Game Development Extension para demostrar las siguientes funciones:

  • Desarrollo de proyectos multiplataforma: Puedes compilar la muestra de Teapot para Windows y Android.
  • Uso personalizado de paquetes de Android: Las secuencias de comandos de compilación de Gradle se movieron al directorio raíz de la muestra, en la que se encuentra el archivo Teapot.sln.
  • Integración de compilación de Ninja experimental que permite abrir el proyecto en Android Studio.
  • Configuraciones personalizadas de Android que demuestran el uso de Address Sanitizer (ASan) y Hardware Address Sanitizer (HWAsan).

La implementación de la muestra de Teapot se divide en varias partes, lo que es común en aplicaciones y juegos multiplataforma grandes:

  • Módulo GameApplication: Define las acciones del usuario y los estados de la aplicación, por ejemplo, un usuario que rota la tetera o actualiza las estadísticas de la aplicación.
  • Módulo GameEngine: Implementa el módulo de renderización principal.

Para configurar la muestra y ejecutarla en Android, consulta la guía de inicio rápido. Para configurar la muestra y ejecutarla en Windows, haz lo siguiente:

  1. Instala GLEW:
    1. Descarga y descomprime GLEW.
    2. Copia los archivos binarios de $your-glew-directory\bin\Release\x64 a %SystemRoot%\system32.
  2. Instala freeglut:
    1. Descarga y descomprime freeglut.
    2. Copia $your-freeglut-directory\bin\x86\freeglut.dll en %SystemRoot%\system32.
  3. Agrega las dependencias del proyecto freeglut:
    1. Abre Teapot.sln en Visual Studio.
    2. En el menú, haz clic en Debug > x64 > Local Windows Debugger.
    3. En Solution Explorer, haz clic con el botón derecho en GameApplication y elige Properties > C/C++ > General > Additional Include Directories.
    4. Agrega $your-freeglut-dir\include a la ruta.
      Captura de pantalla del diálogo de Additional Include Directories.
    5. Haz clic en Ok.
    6. Selecciona Linker > General > Additional Library Directories.
    7. Agrega $your-freeglut-dir\lib\x64 a la ruta. Captura de pantalla del diálogo de Additional Library Directories.
    8. Haz clic en Ok.
    9. Selecciona Linker > General > Additional Library Directories.
    10. Agrega freeglut.lib a la ruta.
    11. Haz clic en Ok.
  4. Agrega las dependencias del proyecto de GLEW:
    1. En el panel Solution Explorer, haz clic con el botón derecho en GameApplication y elige Properties > C/C++ > General > Additional Include Directories.
    2. Agrega $your-glew-dir\include a la ruta.
    3. Haz clic en Ok.
    4. Selecciona Linker > General > Additional Library Directories.
    5. Agrega $your-glew-dir\lib\Release\x86 a la ruta.
    6. Haz clic en Ok.
    7. Selecciona Linker > General > Additional Library Directories.
    8. Agrega glew32.lib a la ruta.
    9. Haz clic en Ok.
  5. Ejecuta el ejemplo en Windows:
    1. En la barra de herramientas de Visual Studio, haz clic en el botón de ejecución Local Windows Debugger.
    2. La muestra debe verse de la siguiente manera:
      Captura de pantalla de la muestra de Teapot que se ejecuta en Windows

Este es un proyecto de plantilla que muestra cómo generar una biblioteca nativa de Android a partir del ensamblaje y el código fuente de C/C++. Estos son los componentes principales:

  • AssemblyCode-Link-Objects: Es la biblioteca nativa de Android principal compilada a partir de C++ y el código fuente de ensamblado.
  • StaticLib: Es una biblioteca estática de ayuda que exporta la función from_static_lib_assembly_code_as.

El proyecto admite varias arquitecturas. Cada arquitectura compatible tiene sus propios archivos de origen que implementan funciones que se exportan desde StaticLib. Solo debes incluir los archivos fuente de ensamblado para las plataformas que estés compilando. Este proyecto incluye archivos de ensamblado en compilaciones con herramientas de compilación personalizadas.

Para configurar y compilar la muestra, haz lo siguiente:

  1. En Visual Studio, verifica que las herramientas de compilación personalizadas estén configuradas para los archivos ensamblados:
    1. En Solution Explorer, haz clic con el botón derecho en el archivo de ensamblado y selecciona Properties. Se abrirá el diálogo Properties Pages del archivo.
    2. Selecciona la configuración y plataforma, como All configurations para Android-arm64-v8a.
    3. Asegúrate de que General > Exclude from Build esté configurado en No.
    4. Asegúrate de que General > Item Type esté configurado en Custom Build Tool.
    5. Haz clic en Apply si hay cambios para aplicar.
    6. Asegúrate de que Configuration Properties > Custom Build Tools > Command Line esté configurado en $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). El NDK incluye un ensamblador independiente para cada arquitectura de CPU, y $(AsToolExe) se asigna al ensamblador correcto. En esta muestra, se usa la cadena de herramientas del NDK para compilar proyectos de Android x86 y x86_64. Si quieres usar yasm para la plataforma de Android x86_64, usa $(YasmToolExe).
    7. Asegúrate de que Configuration Properties > Custom Build Tools > Outputs esté configurado en $(IntDir)%(FileName).o. Esta cadena se debe incluir en el parámetro de configuración de Command Line.
    8. Asegúrate de que Configuration Properties > Custom Build Tools > Link Objects esté configurado en Yes.

    Por ejemplo, la configuración de Android-arm64-v8a debería ser similar a la siguiente captura de pantalla:

    Captura de pantalla de Property Page para Custom Build Tools.
  2. Compila el proyecto. Esto compila el archivo libAssmeblyCodeLinkObjects.so:
    1. Abre el archivo AssemblyCode-Link-Objects.sln.
    2. En el menú, haz clic en Build > Build Solution.
  3. Para confirmar que las funciones se hayan exportado correctamente a la biblioteca de Android, usa la herramienta NDK nm.exe:
    1. En la línea de comandos, ve al directorio de la muestra.
    2. Ve a la ubicación de la biblioteca de Android que generó tu compilación. La ubicación predeterminada es similar a $sample_dir\$solution_configuration\$solution_platform\$platform y $sample_dir\Debug\Android-arm64-v8a\arm64-v8a para la plataforma arm64-v8a.
    3. Ejecuta el siguiente comando para verificar que la sección de símbolos exportados contenga las funciones:
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so
      

      En el resultado, deberías ver una lista de símbolos en la que se incluye lo siguiente:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as