Exemples

Les exemples de l'extension Android Game Development montrent comment utiliser les principales fonctionnalités de l'extension. Cet article décrit les exemples et les paramètres nécessaires à leur exécution.

Les exemples suivants sont disponibles sur la page des téléchargements :

  • HelloJNI : projet d'introduction.
  • Endless-Tunnel : projet Android uniquement.
  • Teapot : projet multiplate-forme pour Windows et Android.
  • AssemblyCode-Link-Objects : modèle de projet contenant le code source de l'assembly.

Avant de commencer

  • Installez l'extension Android Game Development et les exemples. Pour en savoir plus, consultez le guide de démarrage rapide. Cette rubrique explique également comment compiler et exécuter un exemple, et utilise la version Android de l'exemple Teapot.

  • Le guide de configuration du projet explique comment configurer les paramètres d'un projet qui utilise l'extension, comme l'ajout d'une plate-forme Android et d'un APK.

HelloJNI

L'exemple HelloJNI est un projet simple qui affiche le message "Hello From JNI" dans une fenêtre d'application. Le projet utilise des ensembles de code source différents pour Windows et Android.

  • Répertoire du code source Android et des scripts de compilation Gradle : HelloJNI\AndroidPackaging
  • Répertoire du code source Windows et du projet Visual Studio : HelloJNI

Lorsque vous compilez le projet, Visual Studio transmet les paramètres suivants au fichier build.gradle au niveau de l'application. Vous pouvez changer ces paramètres en modifiant vos scripts de compilation Gradle.

  • MSBUILD_NDK_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Pour configurer et exécuter l'exemple :

  1. Dans Visual Studio, ouvrez et compilez l'exemple HelloJNI.
  2. Ajoutez une plate-forme Android arm64-v8a. Pour en savoir plus, consultez Ajouter une plate-forme Android.
  3. Ajoutez un élément APK Android à la nouvelle plate-forme.
  4. Compilez le projet.
  5. Ajoutez les plates-formes Android suivantes, puis ajoutez un élément APK Android à chacune d'elles : Android-armeabi-v7a, Android-x86 et Android-x86_64.
  6. Compilez et exécutez l'exemple.

Endless-Tunnel

L'exemple Endless-Tunnel est un jeu Android dans lequel le joueur collecte des cubes blancs tout en essayant d'atteindre le bout d'un tunnel. Il a été transféré à partir d'un exemple OpenGL du dépôt NDK Android de GitHub. L'exemple ne fournit pas de version Windows du jeu.

Les paramètres et les plates-formes Android de l'exemple sont déjà configurés. Vous pouvez donc compiler et exécuter le projet dans Visual Studio sans aucune modification. Lorsque vous ouvrez la solution, l'Explorateur de solutions affiche les modules suivants :

  • endless-tunnel : module d'application qui présente la logique du jeu.
  • glm: instantané du dépôt OpenGL Math compilé sous la forme d'une bibliothèque statique.
  • native_app_glue : wrapper NDK qui communique avec l'objet NativeActivity.

Teapot

L'exemple Teapot présente une théière classique rendue avec OpenGL ES et transmise à l'extension Android Game Development pour illustrer les fonctionnalités suivantes :

  • Développement de projets multiplates-formes : vous pouvez compiler l'exemple Teapot pour Windows et Android.
  • Utilisation d'un packaging Android personnalisé : les scripts de compilation Gradle ont été déplacés vers le répertoire racine de l'exemple, où se trouve le fichier Teapot.sln.
  • Intégration du système de compilation Ninja (expérimental) : permet d'ouvrir le projet dans Android Studio.
  • Configurations Android personnalisées qui montrent comment utiliser Address Sanitizer (ASan) et Hardware Address Sanitizer (HWAsan).

L'implémentation de l'exemple Teapot est divisée en plusieurs parties, ce qui est courant pour les applications et jeux multiplates-formes volumineux :

  • Module GameApplication : définit les actions de l'utilisateur et les états de l'application, comme la rotation de la théière ou la mise à jour des statistiques de l'application.
  • Module GameEngine : implémente le module de rendu principal.

Pour configurer l'exemple et l'exécuter sous Android, consultez le guide de démarrage rapide. Pour configurer l'exemple et l'exécuter sous Windows :

  1. Installez GLEW :
    1. Téléchargez et décompressez GLEW.
    2. Copiez les fichiers binaires de $your-glew-directory\bin\Release\x64 vers %SystemRoot%\system32.
  2. Installez freeglut :
    1. Téléchargez et décompressez freeglut.
    2. Copiez $your-freeglut-directory\bin\x86\freeglut.dll dans le répertoire %SystemRoot%\system32.
  3. Ajoutez les dépendances du projet freeglut :
    1. Ouvrez Teapot.sln dans Visual Studio.
    2. Dans le menu, cliquez sur Debug > x64 > Local Windows Debugger (Débogage > x64 > Débogueur Windows local).
    3. Dans Solution Explorer (Explorateur de solutions), effectuez un clic droit sur GameApplication, puis sélectionnez Properties > C/C++ > General > Additional Include Directories (Propriétés > C/C++ > Général > Autres répertoires "Include").
    4. Ajoutez $your-freeglut-dir\include au chemin.
      Capture d'écran de la boîte de dialogue "Autres répertoires 'Include'".
    5. Cliquez sur OK.
    6. Sélectionnez Linker > General > Additional Library Directories (Éditeur de liens > Général > Répertoires de bibliothèques supplémentaires).
    7. Ajoutez $your-freeglut-dir\lib\x64 au chemin. Capture d'écran de la boîte de dialogue "Additional Library Directories" (Répertoires de bibliothèques supplémentaires).
    8. Cliquez sur OK.
    9. Sélectionnez Linker > General > Additional Library Directories (Éditeur de liens > Général > Répertoires de bibliothèques supplémentaires).
    10. Ajoutez freeglut.lib au chemin.
    11. Cliquez sur OK.
  4. Ajoutez les dépendances du projet GLEW :
    1. Dans le volet Solution Explorer (Explorateur de solutions), effectuez un clic droit sur GameApplication, puis sélectionnez Properties > C/C++ > General > Additional Include Directories (Propriétés > C/C++ > Général > Autres répertoires "Include").
    2. Ajoutez $your-glew-dir\include au chemin.
    3. Cliquez sur OK.
    4. Sélectionnez Linker > General > Additional Library Directories (Éditeur de liens > Général > Répertoires de bibliothèques supplémentaires).
    5. Ajoutez $your-glew-dir\lib\Release\x86 au chemin.
    6. Cliquez sur OK.
    7. Sélectionnez Linker > General > Additional Library Directories (Éditeur de liens > Général > Répertoires de bibliothèques supplémentaires).
    8. Ajoutez glew32.lib au chemin.
    9. Cliquez sur OK.
  5. Exécutez l'exemple sous Windows :
    1. Sur la barre d'outils de Visual Studio, cliquez sur le bouton d'exécution Local Windows Debugger (Débogueur Windows local).
    2. L'exemple doit se présenter comme suit :
      Capture d'écran de l'exemple Teapot exécuté sous Windows.

Il s'agit d'un modèle de projet qui montre comment générer une bibliothèque native Android à partir du code source de l'assembly et du code source C++. Les principaux composants sont les suivants :

  • AssemblyCode-Link-Objects : bibliothèque native principale d'Android créée à partir du code source C++ et du code source de l'assembly.
  • StaticLib : bibliothèque statique d'assistance qui exporte la fonction from_static_lib_assembly_code_as.

Le projet accepte différentes architectures. Chaque architecture compatible possède ses propres fichiers sources qui implémentent les fonctions exportées à partir de StaticLib. Vous ne devez inclure que les fichiers sources d'assembly des plates-formes que vous créez. Ce projet inclut les fichiers d'assembly dans des builds à l'aide d'outils de compilation personnalisés.

Pour configurer et compiler l'exemple :

  1. Dans Visual Studio, vérifiez que les outils de compilation personnalisés sont configurés pour les fichiers d'assembly :
    1. Dans Solution Explorer, effectuez un clic droit sur le fichier d'assembly, puis cliquez sur Properties (Propriétés). La boîte de dialogue Properties Pages (Pages des propriétés) du fichier s'ouvre.
    2. Sélectionnez la configuration et la plate-forme, par exemple All configurations (Toutes les configurations) pour Android-arm64-v8a.
    3. Assurez-vous que General > Exclude from Build (Général > Exclure de la compilation) est défini sur No (Non).
    4. Assurez-vous que General > Item Type (Général > Type d'élément) est défini sur Custom Build Tool (Outil de compilation personnalisé).
    5. Cliquez sur Apply (Appliquer) si des modifications sont nécessaires.
    6. Assurez-vous que Configuration Properties > Custom Build Tools > Command Line (Propriétés de la configuration > Outils de compilation personnalisés > Ligne de commande) est défini sur $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). Le NDK comprend un assembleur distinct pour chaque architecture de processeur, et $(AsToolExe) assure la mise en correspondance avec l'assembleur approprié. Cet exemple utilise la chaîne d'outils NDK pour compiler les projets Android x86 et x86_64. Si vous souhaitez utiliser yasm pour la plate-forme Android x86_64, utilisez plutôt $(YasmToolExe).
    7. Assurez-vous que Configuration Properties > Custom Build Tools > Outputs (Propriétés de la configuration > Outils de compilation personnalisés > Sorties) est défini sur $(IntDir)%(FileName).o. Cette chaîne doit être incluse dans le paramètre Command Line (Ligne de commande).
    8. Assurez-vous que Configuration Properties > Custom Build Tools > Link Objects (Propriétés de la configuration > Outils de compilation personnalisés > Lier les objets) est défini sur Yes.

    Par exemple, les paramètres d'Android-arm64-v8a doivent être semblables à ceux présentés dans la capture d'écran suivante :

    Capture d'écran de la page des propriétés des outils de compilation personnalisés.
  2. Compilez le projet. Cette action crée le fichier libAssmeblyCodeLinkObjects.so :
    1. Ouvrez le fichier AssemblyCode-Link-Objects.sln.
    2. Dans le menu, cliquez sur Build > Build Solution (Créer > Générer la solution).
  3. Pour vérifier que les fonctions sont correctement exportées vers la bibliothèque Android, utilisez l'outil NDK nm.exe :
    1. Sur la ligne de commande, accédez à l'exemple de répertoire.
    2. Accédez à l'emplacement de la bibliothèque Android générée par votre build. L'emplacement par défaut est semblable à $sample_dir\$solution_configuration\$solution_platform\$platform et $sample_dir\Debug\Android-arm64-v8a\arm64-v8a pour la plate-forme arm64-v8a.
    3. Vérifiez que la section des symboles exportés contient les fonctions en exécutant la commande suivante : 
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      La sortie doit afficher une liste de symboles contenant les éléments suivants : 

         T from_shared_object_assembly_code_as
   T from_static_lib_assembly_code_as