Beispiele

Die Beispiele für die Android Game Development Extension zeigen, wie die wichtigsten Funktionen der Erweiterung verwendet werden. In diesem Thema werden die Beispiele und die Einstellungen beschrieben, die für ihre Ausführung erforderlich sind.

Die folgenden Beispiele sind auf der Downloadseite verfügbar:

  • HelloJNI: ein Einführungsprojekt.
  • Endless-Tunnel: ein reines Android-Projekt.
  • Teapot: ein plattformübergreifendes Projekt für Windows und Android
  • AssemblyCode-Link-Objects: ein Vorlagenprojekt mit Assembly-Quellcode.

Vorbereitung

  • Installiere die Android Game Development Extension und die Beispiele. Weitere Informationen finden Sie in der Kurzanleitung. Außerdem wird beschrieben, wie ein Beispiel erstellt und ausgeführt wird. Als Beispiel wird die Android-Version des Beispiels Teapot verwendet.

  • In der Anleitung zur Projektkonfiguration wird beschrieben, wie die Einstellungen für ein Projekt konfiguriert werden, in dem die Erweiterung verwendet wird, z. B. das Hinzufügen einer Android-Plattform und eines APK.

Hallo JNI

Das HelloJNI-Beispiel ist ein einfaches Projekt, das die Nachricht "Hello from JNI" in einem Anwendungsfenster anzeigt. Das Projekt verwendet für Windows und Android unterschiedliche Quellcodes.

  • Android-Quellcode und Gradle-Build-Skriptverzeichnis: HelloJNI\AndroidPackaging
  • Windows-Quellcode und Visual Studio-Projektverzeichnis: HelloJNI

Wenn Sie das Projekt erstellen, übergibt Visual Studio die folgenden Einstellungen an die Datei build.gradle auf App-Ebene. Sie können diese Einstellungen ändern, indem Sie Ihre Gradle-Build-Skripts ändern.

  • MSBUILD_NDK_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

So richten Sie das Beispiel ein und führen es aus:

  1. Öffnen und erstellen Sie das HelloJNI-Beispiel in Visual Studio.
  2. Fügen Sie eine Android arm64-v8a-Plattform hinzu. Weitere Informationen finden Sie unter Android-Plattform hinzufügen.
  3. Füge der neuen Plattform ein Android-APK-Element hinzu.
  4. Kompilieren Sie das Projekt.
  5. Fügen Sie die folgenden Android-Plattformen und dann jeweils ein Android APK-Element hinzu: Android-armeabi-v7a, Android-x86 und Android-x86_64.
  6. Erstellen Sie das Beispiel und führen Sie es aus.

Endlostunnel

Das Beispiel „Endless-Tunnel“ ist ein Android-Spiel, bei dem der Spieler weiße Würfel sammelt, während er versucht, das Ende eines Tunnels zu erreichen. Sie wurde aus einem OpenGL-Beispiel im Android-NDK-Repository auf GitHub portiert. Im Beispiel ist keine Windows-Version des Spiels verfügbar.

Im Beispiel sind die Einstellungen und Android-Plattformen bereits konfiguriert, sodass Sie das Projekt ohne Änderungen in Visual Studio erstellen und ausführen können. Wenn Sie die Lösung öffnen, werden im Projektmappen-Explorer die folgenden Module angezeigt:

  • Endless-Tunnel: das Anwendungsmodul, das die Spielelogik anzeigt
  • glm: Snapshot des OpenGL Math-Repositorys, das als statische Bibliothek erstellt wurde
  • native_app_glue: Ein NDK-Wrapper, der mit dem NativeActivity-Objekt kommuniziert.

Teekanne

Das Teapot-Beispiel zeigt eine klassische Teekanne, die mit OpenGL ES gerendert und in die Android Game Development Extension übertragen wird, um die folgenden Funktionen zu demonstrieren:

  • Plattformübergreifende Projektentwicklung: Sie können das Teapot-Beispiel für Windows und Android erstellen.
  • Benutzerdefinierte Android-Paketerstellung: Die Gradle-Build-Skripts wurden in das Stammverzeichnis des Beispiels verschoben, in dem sich die Datei Teapot.sln befindet.
  • Experimentelle Ninja-Build-Integration, mit der das Projekt in Android Studio geöffnet werden kann
  • Benutzerdefinierte Android-Konfigurationen, die zeigen, wie Address Sanitizer (ASan) und Hardware Address Sanitizer (HWAsan) verwendet werden.

Die Implementierung des Teapot-Beispiels besteht aus mehreren Teilen, was typischerweise für große plattformübergreifende Anwendungen und Spiele ist:

  • Modul GameApplication: definiert Nutzeraktionen und Anwendungsstatus, z. B. wenn ein Nutzer die Teekanne dreht oder App-Statistiken aktualisiert.
  • Modul GameEngine: Implementiert das zentrale Renderingmodul.

Informationen zum Einrichten des Beispiels und Ausführung unter Android finden Sie in der Kurzanleitung. So richten Sie das Beispiel ein und führen es unter Windows aus:

  1. Installieren Sie GLEW:
    1. Laden Sie GLEW herunter und entpacken Sie die App.
    2. Kopieren Sie die Binärdateien von $your-glew-directory\bin\Release\x64 nach %SystemRoot%\system32.
  2. Installieren Sie Freeglut:
    1. Laden Sie freeglut herunter und entpacken Sie es.
    2. $your-freeglut-directory\bin\x86\freeglut.dll in %SystemRoot%\system32 kopieren.
  3. Fügen Sie die Freeglut-Projektabhängigkeiten hinzu:
    1. Öffnen Sie Teapot.sln in Visual Studio.
    2. Klicken Sie im Menü auf Fehlerbehebung > x64 > Lokaler Windows-Debugger.
    3. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf GameApplication und wählen Sie Eigenschaften > C/C++ > Allgemein > Zusätzliche Einschlussverzeichnisse aus.
    4. Fügen Sie dem Pfad $your-freeglut-dir\include hinzu.
      Screenshot des Dialogfelds „Zusätzliche Verzeichnisse einschließen“.
    5. Klicken Sie auf OK.
    6. Wählen Sie Verknüpfung > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
    7. Fügen Sie dem Pfad $your-freeglut-dir\lib\x64 hinzu. Screenshot des Dialogfelds „Zusätzliche Bibliotheksverzeichnisse“.
    8. Klicken Sie auf OK.
    9. Wählen Sie Verknüpfung > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
    10. Fügen Sie dem Pfad freeglut.lib hinzu.
    11. Klicken Sie auf OK.
  4. Fügen Sie die GLEW-Projektabhängigkeiten hinzu:
    1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf GameApplication und wählen Sie Eigenschaften > C/C++ > Allgemein > Zusätzliche Einschlussverzeichnisse aus.
    2. Fügen Sie dem Pfad $your-glew-dir\include hinzu.
    3. Klicken Sie auf OK.
    4. Wählen Sie Verknüpfung > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
    5. Fügen Sie dem Pfad $your-glew-dir\lib\Release\x86 hinzu.
    6. Klicken Sie auf OK.
    7. Wählen Sie Verknüpfung > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
    8. Fügen Sie dem Pfad glew32.lib hinzu.
    9. Klicken Sie auf OK.
  5. Führen Sie das Beispiel unter Windows aus:
    1. Klicken Sie in der Symbolleiste von Visual Studio auf die Ausführungsschaltfläche Lokaler Windows-Debugger.
    2. Das Beispiel sollte so aussehen:
      Screenshot des Teapot-Beispiels, das unter Windows ausgeführt wird

Dies ist ein Vorlagenprojekt, das zeigt, wie eine native Android-Bibliothek aus Assembly und C/C++-Quellcode generiert wird. Dies sind die Hauptkomponenten:

  • AssemblyCode-Link-Objects: Die native Android-Hauptbibliothek, die aus C++- und Assembly-Quellcode erstellt wurde.
  • StaticLib: eine statische Hilfsbibliothek, die die Funktion from_static_lib_assembly_code_as exportiert.

Das Projekt unterstützt mehrere Architekturen. Jede unterstützte Architektur hat ihre eigenen Quelldateien, die Funktionen implementieren, die aus StaticLib exportiert werden. Sie sollten nur die Assembly-Quelldateien für die Plattformen hinzufügen, die Sie erstellen. Dieses Projekt umfasst Assembly-Dateien in Builds mithilfe von benutzerdefinierten Build-Tools.

So richten Sie das Beispiel ein und erstellen es:

  1. Prüfen Sie in Visual Studio, ob benutzerdefinierte Build-Tools für die Assembly-Dateien konfiguriert sind:
    1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Assembly-Datei und dann auf Eigenschaften. Daraufhin wird das Dialogfeld Eigenschaftenseiten für die Datei geöffnet.
    2. Wählen Sie die Konfiguration und Plattform aus, z. B. Alle Konfigurationen für Android-arm64-v8a.
    3. Achten Sie darauf, dass Allgemein > Aus Build ausschließen auf Nein festgelegt ist.
    4. Achten Sie darauf, dass Allgemein > Elementtyp auf Benutzerdefiniertes Build-Tool festgelegt ist.
    5. Klicken Sie auf Übernehmen, wenn Änderungen angewendet werden sollen.
    6. Prüfen Sie, ob unter Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Befehlszeile auf $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath) festgelegt ist. Der NDK enthält für jede CPU-Architektur einen separaten Assembler und $(AsToolExe) wird dem richtigen Assembler zugeordnet. In diesem Beispiel wird die NDK-Toolchain verwendet, um sowohl x86- als auch x86_64-Android-Projekte zu erstellen. Wenn Sie Yasm für die Android-Plattform x86_64 nutzen möchten, verwenden Sie stattdessen $(YasmToolExe).
    7. Achten Sie darauf, dass unter Configuration Properties > Custom Build Tools > Outputs (Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Ausgaben) auf $(IntDir)%(FileName).o festgelegt ist. Dieser String muss in der Einstellung Command Line (Befehlszeile) enthalten sein.
    8. Achten Sie darauf, dass unter Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Objekte verknüpfen auf Yes festgelegt ist.

    Die Einstellungen für Android-arm64-v8a sollten beispielsweise in etwa so aussehen:

    Screenshot der Property-Seite für benutzerdefinierte Build-Tools.
  2. Erstellen Sie das Projekt. Dadurch wird die Datei libAssmeblyCodeLinkObjects.so erstellt:
    1. Öffnen Sie die Datei AssemblyCode-Link-Objects.sln.
    2. Klicken Sie im Menü auf Erstellen > Lösung erstellen.
  3. Prüfen Sie mit dem NDK-Tool „nm.exe“, ob die Funktionen korrekt in die Android-Bibliothek exportiert werden:
    1. Rufen Sie in der Befehlszeile das Beispielverzeichnis auf.
    2. Wechseln Sie zum Speicherort der Android-Bibliothek, der von Ihrem Build generiert wurde. Der Standardspeicherort ähnelt $sample_dir\$solution_configuration\$solution_platform\$platform und $sample_dir\Debug\Android-arm64-v8a\arm64-v8a für die Plattform arm64-v8a.
    3. Prüfen Sie mit dem folgenden Befehl, ob der exportierte Symbolabschnitt die Funktionen enthält:
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      Die Ausgabe sollte eine Liste mit Symbolen wie die folgenden enthalten: 

         T from_shared_object_assembly_code_as
   T from_static_lib_assembly_code_as