VkQuality Unity エンジン プラグイン

Unity エンジン用の VkQuality プラグインは、特定のデバイスでゲームに使用するグラフィック API（Vulkan または OpenGL ES）の起動時の推奨事項を提供します。

VkQuality は、Unity エンジンのデフォルトの許可リストよりも制限されたデバイスセットで Vulkan を推奨します。VkQuality を使用すると、Vulkan のパフォーマンス上のメリットを得ることができますが、Vulkan の使用は新しいグラフィック ドライバを搭載した新しいデバイスに制限されるため、ゲームでドライバの問題が生じるリスクを抑えることができます。推奨デバイスでドライバの問題が発生する可能性があるため、VkQuality は品質を推奨するだけであり、保証するものではありません。VkQuality はカスタムリストをサポートしています。これにより、ゲームに適したデバイスのおすすめを追加または削除できます。

Unity エンジンのゲームで Vulkan を有効にする

VkQuality では、Unity プロジェクトの設定で OpenGL ES と Vulkan の両方のレンダラを有効にする必要があります。レンダラを有効にするには、Auto Graphics API オプションを使用するか、グラフィック API を手動で設定します。

Unity エンジン用 VkQuality プラグインを入手する

GitHub から VkQuality プラグインをダウンロードします。このプラグインは Unity 2021 以降と互換性があります。Android で Vulkan を有効にするには、Unity 2021 LTS 以降を使用してください。このプラグイン パッケージには、プラグインを使用して起動時にグラフィック API を設定し、デバイスのアクティブなグラフィック API に設定された文字列を表示する基本的なサンプル プロジェクトが含まれています。

VkQuality Vulkan の推奨事項リストを管理する

VkQuality には、対応デバイスのデフォルトの推奨リストが含まれています。カスタム推奨事項リストの使用方法については、カスタム推奨事項リストを使用するをご覧ください。

推奨事項のリストには、次の 3 つのカテゴリがあります。

• Vulkan デバイスの許可リスト
• GPU 推奨事項の許可リスト
• GPU の推奨事項の拒否リスト

デバイスの許可リストの一致

VkQuality はまず、アクティブなデバイスがデバイスの許可リストに含まれているかどうかと、そのデバイスの許可リストで指定されている最小 Android バージョンと Vulkan ドライバ バージョンを実行しているかどうかを確認します。これらの条件が満たされている場合、VkQuality は RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH 列挙値を返すことで Vulkan を推奨します。

デバイスが許可リストに登録されているものの、動作している Android バージョンまたはドライバのバージョンが許可リストで指定されている最小値より低い場合、VkQuality は RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER を返して OpenGL ES を推奨します。

GPU の推奨事項の一致

デバイスの許可リストに一致するデバイスがない場合、VkQuality は GPU の推奨許可リストと拒否リストと照らし合わせて GPU モデルとドライバ バージョンを評価します。GPU モデルとドライバ バージョンが GPU 推奨事項許可リストのエントリと一致する場合、VkQuality は RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH 列挙定数を返して Vulkan を推奨します。

GPU モデルとドライバ バージョンが GPU 推奨事項拒否リストのエントリと一致する場合、VkQuality は RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH を返して OpenGL ES を推奨します。

一致のないおすすめ

一致するものが見つからない場合、VkQuality は、実行中のデバイスの Android API レベルが推奨リストにある Future API レベル以上である場合に Vulkan を推奨します。デフォルトの推奨事項リストの 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 プラグインは、ダウンロードしたパッケージ アーカイブの Assets/Android/Plugins ディレクトリにある VkQuality-1.x.x.aar ファイルです。.aar ファイルの実際のバージョン番号は、パッケージ アーカイブ名のバージョン番号と一致します。プラグインをインストールするには、次の手順を行います。

1. .aar ファイルをプロジェクトの Assets/Android/Plugins ディレクトリにコピーします。（必要な Android サブディレクトリと Plugins サブディレクトリが存在しない場合は作成します）。

1. Unity の [Project] 階層で VkQuality-1.x.x プラグイン ファイルを選択すると、[Inspector] ペインに [Import Settings] が表示されます。[Android] プラットフォームがオンになっていることを確認します。

カスタム アクティビティを使用して VkQuality を呼び出す

一般的な Unity エンジン プラグインとは異なり、グラフィック API の推奨事項を取得するには、Unity エンジンの初期化前に VkQuality を実行する必要があります。次に、Unity プレーヤーのコマンドライン引数機能を使用して、VkQuality の推奨事項に基づいてグラフィック 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 プロジェクト設定の [Player] カテゴリの [Package Name] フィールドの値と一致するようにします（例: 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] チェックボックスをオンにします。

これで、起動時に VkQuality を呼び出し、VkQuality の推奨事項に基づいて Vulkan または OpenGL ES を選択するカスタム アクティビティを使用するようにプロジェクトが設定されました。

VkQuality を既存のカスタム アクティビティに追加する

デフォルトの UnityPlayerActivity をオーバーライドするカスタム アクティビティがゲームにすでにある場合は、次のコードを追加して VkQuality の推奨事項を統合します。

まず、カスタム アクティビティ ファイルの先頭にあるインポート リストに VkQuality のインポート ステートメントを追加します。

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

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

次に、Activity クラスの本体で、グラフィック API の選択に使用する定数を作成します。

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

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

API の選択を追跡する変数を作成します。

private var apiOverride = OVERRIDE_NONE

private int apiOverride = OVERRIDE_NONE;

次の関数を Activity クラスに追加します。

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")
    }
}

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 関数を呼び出します。

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

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

最後に、apiOverride の値を使用して、使用するグラフィック API を指定するコマンドライン引数を Unity エンジンに渡す updateUnityCommandLineArguments() 関数のオーバーライドを追加します。

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"
}

@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 を呼び出し、VkQuality の推奨値に基づいて Vulkan または OpenGL ES を選択するようになりました。

カスタム推奨事項リストを使用する

空の文字列を渡す代わりに、リストを含むファイルの名前を StartVkQuality() に渡して、カスタム推奨事項リストファイルを指定します。

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

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

VkQuality はまず、アプリケーションの内部ストレージ ディレクトリでファイルを検索します。ファイルが内部ストレージにない場合、VkQuality は App Bundle のアセットからファイルを読み込もうとします。ファイルがどちらの場所にもない場合、VkQuality は ERROR_MISSING_DATA_FILE 列挙値を返します。

カスタム推奨事項リストファイルを作成するには、GitHub リポジトリにある VkQuality List Editor ツールを使用します。このツールのドキュメントは、README にあります。