VkQuality Unity 引擎外掛程式

Unity 引擎的 VkQuality 外掛程式提供啟動時間建議 圖形 API (Vulkan 或 OpenGL ES) 可用於您的遊戲 裝置。

VkQuality 向 Unity 推薦比 Unity 更加受限制的裝置組合 引擎的預設允許清單使用 VkQuality 取得 Vulkan 同時限制 Vulkan 的使用範圍，僅限於採用較新圖形的較新裝置 。僅限 VkQuality 提供優質建議，而不是保證。 在建議裝置上遇到驅動程式問題VkQuality 支援自訂清單， 讓您新增或移除推薦的裝置 遊戲。

在 Unity 引擎遊戲中啟用 Vulkan

遊戲必須同時具備 OpenGL ES 和 Vulkan 轉譯器，才能使用 VkQuality 功能 可在 Unity 專案設定中啟用使用 Auto 啟用轉譯器 Graphics API 選項，或手動設定圖形 API。

取得 Unity 引擎的 VkQuality 外掛程式

從 GitHub 下載 VkQuality 外掛程式。外掛程式是 支援 Unity 2021 以上版本使用 Unity 2021 LTS 以上版本啟用 Android 上的 Vulkan。外掛程式套件包含基本範例專案，使用 這個外掛程式能在啟動時設定圖形 API，然後顯示 裝置上開啟的圖形 API。

管理 VkQuality Vulkan 推薦清單

VkQuality 包含支援裝置的預設建議清單。適用對象 請參閱使用自訂建議清單 建議清單一節

建議清單包含三個類別：

  • Vulkan 裝置許可清單
  • GPU 建議許可清單
  • GPU 建議拒絕清單

裝置許可清單相符

Vkquality 會先檢查使用中的裝置是否允許 清單，以及應用程式是否執行最低 Android 版本和 Vulkan 驅動程式 裝置的許可清單中指定的版本。如果符合這些條件 VkQuality 建議透過傳回 RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH 列舉值。

裝置是否列在許可清單中，但裝置搭載的是 Android 版本或驅動程式 版本低於許可清單中指定的最低版本，VkQuality 系統會傳回 RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER 來建議 OpenGL ES。

GPU 建議相符項目

如果裝置許可清單中沒有相符的裝置，VkQuality 會評估 根據 GPU 建議允許和拒絕的 GPU 模型和驅動程式版本 清單。如果 GPU 型號和驅動程式版本與 GPU 中的項目相符 VkQuality 建議清單，藉由傳回 RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH 列舉常數。

如果 GPU 型號和驅動程式版本與 GPU 項目相符 建議拒絕清單，VkQuality 建議以 OpenGL ES 傳回 RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH。

不相符的建議

如果找不到相符項目，VkQuality 建議在 Android API 級別 執行中的裝置等於或高於 建議清單預設建議清單的 Future API 級別為 36 (即搭載 API 級別 36 以上版本的不相符裝置，VkQuality) 會傳回 RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID 列舉常數。

如果在裝置許可清單或 GPU 建議清單中找不到相符項目， 且裝置的 API 級別低於 Future API 級別 (VkQuality) 系統會傳回 RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH 來建議 OpenGL ES。

將 VkQuality 封存檔案新增至專案

VkQuality 外掛程式是 VkQuality-1.x.x.aar 檔案，位於 所下載套件封存檔的 Assets/Android/Plugins 目錄。 .aar 檔案的版本號碼與套件的版本號碼相符 封存的名稱如要安裝外掛程式，請按照下列步驟操作：

  1. 將 .aar 檔案複製到您的 Assets/Android/Plugins 目錄 專案。(建立必要的 Android 和 Plugins 子目錄，如果有的話) 不存在。)
，瞭解如何調查及移除這項存取權。
所需專案目錄中的 VkQuality .aar 檔案。
圖 1：必要專案目錄中的 VkQuality .aar 檔案。
  1. 在 Unity「Project」階層中選取 VkQuality-1.x.x 外掛程式檔案 在「Inspector」窗格中，顯示其「Import Settings」。請確認 已勾選 Android 平台，
圖 2. VkQuality 外掛程式平台匯入設定。
圖 2. VkQuality 外掛程式平台匯入設定。

使用自訂活動呼叫 VkQuality

與一般 Unity 引擎外掛程式不同，必須執行 VkQuality 才能取得 在 Unity 引擎初始化前，提供圖形 API 建議。接著，您會使用 使用 Unity 玩家指令列引數功能設定 圖形 API。在 Android 上 指令列引數需要覆寫 建立自訂的 UnityPlayerActivity，並建立自訂元件 活動。

如果您的遊戲已在使用自訂活動，請參閱將 VkQuality 新增至 現有的自訂活動部分。如要為 遊戲中，請參閱接下來的「在 Unity 專案中新增自訂活動」。

將自訂活動新增至 Unity 引擎專案

這個外掛程式中有使用 VkQuality 的自訂活動範例 Assets/Plugins/Android/VkQualityTestActivity.java 中的套件。 如要自訂檔案並在遊戲中使用，請按照下列步驟操作：

  1. 將 VkQualityTestActivity.java 檔案複製到您的 Assets/Plugins/Android 目錄內。
  2. 請重新命名適合遊戲的名稱，例如 MyGameActivity.java)。
  3. 使用文字編輯器開啟檔案。
  4. 將類別名稱從 VkQualityTestActivity 變更為您為專案指定的名稱 檔案 (例如 MyGameActivity.java)。
  5. 將套件名稱從 com.google.android.games.VkQualityTest 變更為 與 Unity 專案設定中「Package Name」欄位的值相符 「Other Settings」下的「Player」類別 (例如 com.mycompany.mygame)。
  6. 儲存並關閉檔案。

新增參照自訂活動的自訂資訊清單檔案，並告知 Unity 使用自訂資訊清單檔案：

  1. 從 Assets/Plugins/Android 複製 AndroidManifest.xml 檔案 將外掛程式套件的目錄複製到專案的 Asset/Plugins/Android 目錄。
  2. 使用文字編輯器開啟檔案。
  3. 將 activity android:name 設定的值從 將 com.google.android.games.VkQualityTest.VkQualityTestActivity 設為 您在先前步驟中使用的套件名稱和活動名稱 (例如 com.mycompany.mygame.MyGameActivity)。
  4. 儲存並關閉檔案。
  5. 開啟 Unity 設定視窗，然後選取「Player」設定。展開 「Publishing Settings」部分，然後勾選「Custom Main Manifest」 核取方塊。
，瞭解如何調查及移除這項存取權。
圖 3. Unity Player 設定中的「Custom Main Manifest」選項。
圖 3：Unity Player 設定中的「Custom Main Manifest」選項。

您的專案設定現已設定，可使用呼叫 VkQuality 的自訂活動 啟動，並根據 VkQuality 建議選擇 Vulkan 或 OpenGL ES。

將 VkQuality 新增至現有自訂活動

如果遊戲已有自訂活動覆寫預設值 UnityPlayerActivity，新增 下列程式碼：

首先，將 VkQuality 匯入陳述式新增至頂端匯入清單 自訂活動檔案：

Kotlin

import com.google.android.games.vkquality.VKQuality;

Java

import com.google.android.games.vkquality.VKQuality;

接下來，請在 Activity 類別的主體中建立一些常數，以供 圖形 API 選擇：

Kotlin

companion object {
  private const val OVERRIDE_NONE = 0
  private const val OVERRIDE_GLES = 1
  private const val OVERRIDE_VULKAN = 2

Java

private static final int OVERRIDE_NONE = 0;
private static final int OVERRIDE_GLES = 1;
private static final int OVERRIDE_VULKAN = 2;

建立變數來追蹤 API 選項：

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

將下列函式新增至 Activity 類別：

Kotlin

private fun CheckVkQuality() {
    val vkQuality = VKQuality(this)
    val startResult = vkQuality.StartVkQuality("")
    if (startResult == VKQuality.INIT_SUCCESS) {
        // In the current release, we can assume GetVkQuality is
        // ready as soon as StartVkQuality has returned success.
        val getResult = vkQuality.GetVkQuality()
        LogVkQualityResult(getResult)
        apiOverride =
            when (getResult) {
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID -> OVERRIDE_VULKAN
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH -> OVERRIDE_GLES
                else -> OVERRIDE_GLES
            }
        vkQuality.StopVkQuality()
    } else {
        Log.e("VKQUALITY", "VkQuality start failed with result: $startResult")
    }
}

Java

private void CheckVkQuality() {
  VKQuality vkQuality = new VKQuality(this);
  // An empty string specifies use of the default
  // built-in device list file.
  int startResult = vkQuality.StartVkQuality("");
  if (startResult == VKQuality.INIT_SUCCESS) {
      // In the current release, we can assume GetVkQuality is
      // ready as soon as StartVkQuality has returned success.
      int getResult = vkQuality.GetVkQuality();

      switch (getResult) {
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID:
              apiOverride = OVERRIDE_VULKAN;
              break;
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH:
          default:
              apiOverride = OVERRIDE_GLES;
              break;
      }
      vkQuality.StopVkQuality();
  } else {
      Log.e("VKQUALITY", "VkQuality start failed with result: " + startResult);
  }
}

從 onCreate() 覆寫的頂端呼叫 CheckVkQuality 函式 函式，再呼叫基本類別實作：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  CheckVkQuality()
  super.onCreate(savedInstanceState)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    CheckVkQuality();
    super.onCreate(savedInstanceState);
}

最後，新增 updateUnityCommandLineArguments() 函式的覆寫值 該函式會使用 apiOverride 的值將指令列引數傳遞至 Unity 引擎，用於指定要使用的圖形 API：

Kotlin

override fun updateUnityCommandLineArguments(cmdLine: String): String {
  if (apiOverride == OVERRIDE_VULKAN) {
      Log.i("VKQUALITY", "Passing -force-vulkan")
      return appendCommandLineArgument(cmdLine, "-force-vulkan")
  } else if (apiOverride == OVERRIDE_GLES) {
      Log.i("VKQUALITY", "Passing -force-gles")
      return appendCommandLineArgument(cmdLine, "-force-gles")
  }
  Log.i("VKQUALITY", "No override passed")
  // let Unity pick the Graphics API based on PlayerSettings
  return cmdLine
}

private fun appendCommandLineArgument(cmdLine: String, arg: String?): String {
    return if (arg == null || arg.isEmpty()) cmdLine
    else if (cmdLine == null || cmdLine.isEmpty()) arg else "$cmdLine $arg"
}

Java

@Override protected String updateUnityCommandLineArguments(String cmdLine)
{
    if (apiOverride == OVERRIDE_VULKAN) {
        Log.i("VKQUALITY", "Passing -force-vulkan");
        return appendCommandLineArgument(cmdLine, "-force-vulkan");
    }
    else if (apiOverride == OVERRIDE_GLES) {
        Log.i("VKQUALITY", "Passing -force-gles");
        return appendCommandLineArgument(cmdLine, "-force-gles");
    }
    Log.i("VKQUALITY", "No override passed");
    // let Unity pick the Graphics API based on PlayerSettings
    return cmdLine;
}

private String appendCommandLineArgument(String cmdLine, String arg) {
    if (arg == null || arg.isEmpty())
        return cmdLine;
    else if (cmdLine == null || cmdLine.isEmpty())
        return arg;
    else
        return cmdLine + " " + arg;
}

您的自訂活動現在會在啟動時呼叫 VkQuality，並選擇 Vulkan 或 OpenGL 根據 VkQuality 建議產生的 ES。

使用自訂推薦清單

傳遞檔案名稱，以指定自訂推薦清單檔案 ，而不是傳送空白字串至 StartVkQuality()：

Kotlin

val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")

Java

int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");

VkQuality 會先在應用程式的內部儲存空間尋找檔案 目錄。如果該檔案不在內部儲存空間中，VkQuality 會嘗試載入 從您的應用程式套件的素材資源中 擷取出適當檔案如果檔案不在上述任一位置 VkQuality 傳回 ERROR_MISSING_DATA_FILE 列舉值。

如要建立自訂推薦清單檔案，請使用 VkQuality 清單編輯器 GitHub 存放區中的工具。 工具位於其 README 中。