範例

Android Game Development Extension 的範例示範如何使用這個擴充功能的主要功能。本主題對於範例以及執行這些功能所需的設定加以說明。

以下是下載頁面上提供的範例：

  • HelloJNI：一款入門專案。
  • Endless-Tunnel：一款僅適用於 Android 的專案。
  • Teapot：一款適用於 Windows 和 Android 的跨平台專案。
  • AssemblyCode-Link-Objects：含有組合原始碼的範本專案。

事前準備

  • 安裝 Android Game Development Extension 和範例。詳情請參閱快速入門導覽課程。該主題也會說明如何建構及執行範例，並以 Android 版本的 Teapot 範例為例。

  • 專案設定指南說明如何針對採用擴充功能的專案調整設定，例如新增 Android 平台和 APK。

HelloJNI

HelloJNI 範例是一個簡單的專案，會在應用程式視窗中顯示「Hello From JNI」訊息。這個專案針對 Windows 和 Android 使用一組不同的原始碼。

  • Android 原始碼和 Gradle 建構指令碼目錄：HelloJNI\AndroidPackaging
  • Windows 原始碼和 Visual Studio 專案目錄：HelloJNI

建構專案時，Visual Studio 會將下列設定傳送至應用程式層級的 build.gradle 檔案。您可以修改 Gradle 建構指令碼來變更這些設定。

  • MSBUILD_NDK_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

如要設定及執行範例，請執行以下操作：

  1. 在 Visual Studio 中，開啟並建構 HelloJNI 範例。
  2. 新增 Android arm64-v8a 平台。詳情請參閱新增 Android 平台。
  3. 在新平台新增 Android APK 項目。
  4. 編譯專案。
  5. 新增下列 Android 平台，然後為每個 Android 平台新增 Android APK 項目：Android-armeabi-v7a、Android-x86 和 Android-x86_64。
  6. 建構並執行範例。

Endless-Tunnel

Endless-Tunnel 範例是一款 Android 遊戲，玩家要努力抵達隧道盡頭，同時收集白色方塊。這個範例是從 GitHub 上的 Android NDK 存放區中的 OpenGL 範例移植而來，且並未提供 Windows 版本的遊戲。

這個範例已完成相關設定和 Android 平台設定，因此您可以在 Visual Studio 中建構並執行專案，無須進行任何修改。開啟解決方案時，Solution Explorer 會顯示下列模組：

  • endless-tunnel：顯示遊戲邏輯的應用程式模組。
  • glm：以靜態資料庫的形式建構的 OpenGL Math 存放區快照。
  • native_app_glue：用來與 NativeActivity 物件通訊的 NDK 包裝函式。

Teapot

Teapot 範例顯示使用 OpenGL ES 轉譯並已移植到 Android Game Development Extension 的經典茶壺，用於展示下列功能：

  • 跨平台專案開發：您可以為 Windows 和 Android 建構 Teapot 範例。
  • 自訂 Android 套件使用情形：Gradle 建構指令碼已移至範例的根目錄，即 Teapot.sln 檔案的所在位置。
  • 實驗性的 Ninja 版本整合作業，可在 Android Studio 中開啟專案。
  • 自訂 Android 設定，示範如何使用 Address Sanitizer (ASan) 和 Hardware Address Sanitizer (HWAsan)。

Teapot 範例的實作可分為多個部分，這對大型跨平台應用程式和遊戲來說很常見：

  • GameApplication 模組：定義使用者動作和應用程式狀態，例如使用者旋轉茶壺或更新應用程式統計資料。
  • GameEngine 模組：導入核心轉譯模組。

如要設定範例並在 Android 上執行，請參閱快速入門導覽課程。如要設定範例並在 Windows 上執行：

  1. 安裝 GLEW：
    1. 下載並解壓縮 GLEW。
    2. 將二進位檔案從 $your-glew-directory\bin\Release\x64 複製到 %SystemRoot%\system32。
  2. 安裝 freeglut：
    1. 下載並解壓縮 freeglut。
    2. 將 $your-freeglut-directory\bin\x86\freeglut.dll 複製到 %SystemRoot%\system32。
  3. 新增 freeglut 專案依附元件：
    1. 在 Visual Studio 中開啟 Teapot.sln。
    2. 在選單中依序點選「Debug」>「x64」>「Local Windows Debugger」。
    3. 在 Solution Explorer 中，於「GameApplication」上按一下滑鼠右鍵，然後依序選擇「Properties」>「C/C++」>「General」>「Additional Include Directories」。
    4. 將 $your-freeglut-dir\include 加入路徑中。
      「Additional Include Directories」對話方塊的螢幕截圖。
    5. 按一下「OK」。
    6. 依序選擇「Linker」>「General」>「Additional Library Directories」。
    7. 將 $your-freeglut-dir\lib\x64 新增至路徑。「Additional Library Directories」對話方塊的螢幕截圖。
    8. 按一下「OK」。
    9. 依序選擇「Linker」>「General」>「Additional Library Directories」。
    10. 將 freeglut.lib 加入路徑中。
    11. 按一下「OK」。
  4. 新增 GLEW 專案依附元件：
    1. 在 Solution Explorer 窗格中，於「GameApplication」上按一下滑鼠右鍵，然後依序選擇「Properties」>「C/C++」>「General」>「Additional Include Directories」。
    2. 將 $your-glew-dir\include 加入路徑中。
    3. 按一下「OK」。
    4. 依序選擇「Linker」>「General」>「Additional Library Directories」。
    5. 將 $your-glew-dir\lib\Release\x86 加入路徑中。
    6. 按一下「OK」。
    7. 依序選擇「Linker」>「General」>「Additional Library Directories」。
    8. 將 glew32.lib 加入路徑中。
    9. 按一下「OK」。
  5. 在 Windows 上執行範例：
    1. 在 Visual Studio 工具列中，按一下「Local Windows Debugger」按鈕。
    2. 範例應如下所示：
      在 Windows 上執行的 Teapot 範例螢幕截圖。

這是一個範本專案，示範如何透過組合和 C/C++ 原始碼產生 Android 原生資料庫。以下是主要元件：

  • AssemblyCode-Link-Objects：使用 C++ 和組合原始碼建構的主要 Android 原生資料庫。
  • StaticLib：匯出 from_static_lib_assembly_code_as 函式的輔助靜態資料庫。

這個專案支援多個架構。每個支援的架構都有自己的來源檔案，可導入從 StaticLib 匯出的函式。對於正在建構的平台，只應納入組合來源檔案。這個專案使用自訂建構工具在建構作業中納入組合檔案。

如要設定及建構範例，請執行以下操作：

  1. 在 Visual Studio 中，確認是否已為組合檔案設定自訂建構工具：
    1. 在 Solution Explorer 中，在組合檔案上按一下滑鼠右鍵，然後按一下「Properties」。系統隨即會開啟檔案的「Properties Pages」對話方塊。
    2. 選取設定和平台，例如為 Android-arm64-v8a 選擇「All configurations」。
    3. 確認「General」>「Exclude from Build」已設定為「No」。
    4. 確認「General」>「Item Type」已設為「Custom Build Tool」。
    5. 按一下「Apply」即可套用變更。
    6. 確認「Configuration Properties」>「Custom Build Tools」>「Command Line」已設為 $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath)。NDK 會為每個 CPU 架構納入個別組合器，且 $(AsToolExe) 會對應到正確的組合器。這個範例使用 NDK 工具鍊同時建構 x86 和 x86_64 Android 專案。如要在 x86_64 Android 平台中使用 yasm，請改用 $(YasmToolExe)。
    7. 確認「Configuration Properties」>「Custom Build Tools」>「Outputs」已設為 $(IntDir)%(FileName).o。這個字串必須包含在指令列設定中。
    8. 確認「Configuration Properties」>「Custom Build Tools」>「Link Objects」已設為 Yes。

    舉例來說，Android-arm64-v8a 設定應如以下螢幕截圖所示：

    「Property Page」上的「Custom Build Tools」螢幕截圖。
  2. 建構專案。這項操作會建構 libAssmeblyCodeLinkObjects.so 檔案：
    1. 開啟 AssemblyCode-Link-Objects.sln 檔案。
    2. 在選單中依序點選「Build」>「Build Solution」。
  3. 如要確認函式是否已正確匯出至 Android 程式庫，請使用 nm.exe NDK 工具：
    1. 在指令列中，前往範例目錄。
    2. 前往版本產生的 Android 程式庫位置。預設位置與 arm64-v8a 平台的 $sample_dir\$solution_configuration\$solution_platform\$platform 和 $sample_dir\Debug\Android-arm64-v8a\arm64-v8a 類似。
    3. 執行下列指令，確認匯出的符號部分包含函式：
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      輸出內容應會列出符號清單，包括：

         T from_shared_object_assembly_code_as
   T from_static_lib_assembly_code_as