範例

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-v7aAndroid-x86Android-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 檔案的所在位置。

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這個字串必須包含在 Command Line 設定中。
    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