Plugin VkQuality untuk mesin Unity memberikan rekomendasi waktu peluncuran API grafis—Vulkan atau OpenGL ES—untuk digunakan bagi game Anda di perangkat tertentu.
VkQuality merekomendasikan Vulkan di kumpulan perangkat yang lebih terbatas daripada daftar yang diizinkan default mesin Unity. Gunakan VkQuality untuk mendapatkan manfaat performa Vulkan sekaligus membatasi penggunaan Vulkan ke perangkat yang lebih baru dengan driver grafis yang lebih baru, yang membatasi eksposur game Anda terhadap masalah driver. VkQuality hanya memberikan rekomendasi kualitas, bukan jaminan, karena masih mungkin menemukan masalah driver pada perangkat yang direkomendasikan. VkQuality mendukung daftar kustom, yang memberi Anda kemampuan untuk menambahkan atau menghapus rekomendasi perangkat untuk game.
Mengaktifkan Vulkan di game mesin Unity Anda
VkQuality mengharuskan game Anda mengaktifkan perender OpenGL ES dan Vulkan di setelan project Unity. Aktifkan perender dengan menggunakan opsi Auto Graphics API atau dengan menyetel API grafis secara manual.
Mendapatkan plugin VkQuality untuk mesin Unity
Download plugin VkQuality dari GitHub. Plugin ini kompatibel dengan Unity 2021 dan yang lebih baru. Gunakan LTS 2021 Unity atau yang lebih baru untuk mengaktifkan Vulkan di Android. Paket plugin berisi project contoh dasar yang menggunakan plugin untuk menyetel API grafis saat memulai, lalu menampilkan string yang disetel ke API grafis aktif perangkat.
Mengelola daftar rekomendasi VkQuality Vulkan
VkQuality menyertakan daftar rekomendasi default dari perangkat yang didukung. Untuk mengetahui informasi tentang penggunaan daftar rekomendasi kustom, lihat bagian Menggunakan daftar rekomendasi kustom.
Daftar rekomendasi mencakup tiga kategori:
- Daftar yang diizinkan perangkat Vulkan
- Daftar yang diizinkan untuk rekomendasi GPU
- Daftar tolak rekomendasi GPU
Kecocokan daftar yang diizinkan perangkat
VkQuality terlebih dahulu akan memeriksa apakah perangkat aktif disertakan dalam daftar yang diizinkan
perangkat, dan apakah menjalankan versi Android minimum dan versi driver Vulkan
yang ditentukan dalam daftar yang diizinkan untuk perangkat tersebut. Jika kriteria ini terpenuhi,
VkQuality akan merekomendasikan Vulkan dengan menampilkan
nilai enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH
.
Jika perangkat berada dalam daftar yang diizinkan, tetapi menjalankan versi Android atau versi driver
di bawah batas minimum yang ditentukan dalam daftar yang diizinkan, VkQuality
akan merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER
.
Rekomendasi GPU cocok
Jika tidak ada kecocokan perangkat yang ditemukan dalam daftar yang diizinkan perangkat, VkQuality akan
mengevaluasi model GPU dan versi driver terhadap daftar izin dan tolak
rekomendasi GPU. Jika model GPU dan versi driver cocok dengan entri dalam daftar yang diizinkan
rekomendasi GPU, VkQuality akan merekomendasikan Vulkan dengan menampilkan
konstanta enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH
.
Jika model GPU dan versi driver cocok dengan entri dalam daftar tolak
rekomendasi GPU, VkQuality akan merekomendasikan OpenGL ES dengan menampilkan
RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH
.
Rekomendasi tanpa kecocokan
Jika tidak ada kecocokan yang ditemukan, VkQuality akan merekomendasikan Vulkan jika level API Android
dari perangkat yang berjalan sama dengan atau lebih tinggi dari Future API level dalam
daftar rekomendasi. Daftar rekomendasi default memiliki Future API level 36, yang berarti pada perangkat tidak cocok yang menjalankan API level 36 atau yang lebih tinggi, VkQuality
akan menampilkan konstanta enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID
.
Jika tidak ada kecocokan yang ditemukan di daftar yang diizinkan perangkat atau daftar rekomendasi GPU,
dan level API perangkat di bawah Future API level, VkQuality
akan merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH
.
Menambahkan file arsip VkQuality ke project Anda
Plugin VkQuality adalah file VkQuality-1.x.x.aar
yang berada di
direktori Assets/Android/Plugins
dari arsip paket yang didownload. Nomor versi
file .aar sebenarnya cocok dengan nomor versi nama arsip
paket. Untuk menginstal plugin, lakukan langkah-langkah berikut:
- Salin file .aar ke direktori
Assets/Android/Plugins
project Anda. (Buat subdirektoriAndroid
danPlugins
yang diperlukan jika tidak ada.)
![File .aar VkQuality di direktori project yang diperlukan.](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unityassets.png?authuser=19&hl=id)
- Pilih file plugin
VkQuality-1.x.x
dalam hierarki Project Unity untuk memunculkan Import Settings di panel Inspector. Pastikan platform Android dicentang.
![Gambar 2. Setelan impor platform plugin VkQuality.](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unityplugin.png?authuser=19&hl=id)
Menggunakan aktivitas kustom untuk memanggil VkQuality
Tidak seperti plugin mesin Unity standar, VkQuality harus dieksekusi untuk mendapatkan rekomendasi API grafis sebelum mesin Unity diinisialisasi. Anda kemudian menggunakan fitur argumen command line pemain Unity untuk menetapkan API grafis berdasarkan rekomendasi VkQuality. Di Android, meneruskan argumen command line mengharuskan penggantian perilaku default UnityPlayerActivity dengan membuat aktivitas kustom.
Jika game Anda sudah menggunakan aktivitas kustom, lihat bagian Menambahkan VkQuality ke aktivitas kustom yang ada. Untuk membuat aktivitas kustom baru untuk game Anda, lihat Menambahkan aktivitas kustom ke project Unity Anda, yang akan ditampilkan nanti.
Menambahkan aktivitas kustom ke project mesin Unity Anda
Contoh aktivitas kustom yang menggunakan VkQuality disertakan dalam paket
plugin di Assets/Plugins/Android/VkQualityTestActivity.java
.
Untuk menyesuaikan file dan menggunakannya di game Anda, lakukan langkah-langkah berikut:
- Salin file
VkQualityTestActivity.java
ke direktoriAssets/Plugins/Android
Anda. - Ganti namanya dengan nama yang sesuai untuk game Anda (misalnya,
MyGameActivity.java
). - Buka file di editor teks.
- Ubah nama class dari
VkQualityTestActivity
menjadi nama yang Anda berikan pada file (misalnya,MyGameActivity.java
). - Ubah nama paket dari
com.google.android.games.VkQualityTest
agar cocok dengan nilai kolom Package Name di kategori Player Unity Project Settings di bagian Other Settings (misalnya,com.mycompany.mygame
). - Simpan dan tutup file tersebut.
Tambahkan file manifes kustom yang mereferensikan aktivitas kustom Anda, dan beri tahu Unity untuk menggunakan file manifes kustom Anda:
- Salin file
AndroidManifest.xml
dari direktoriAssets/Plugins/Android
paket plugin ke direktoriAsset/Plugins/Android
project Anda. - Buka file di editor teks.
- Ubah nilai setelan
activity android:name
daricom.google.android.games.VkQualityTest.VkQualityTestActivity
menjadi nama paket dan aktivitas yang Anda gunakan di langkah sebelumnya (misalnya,com.mycompany.mygame.MyGameActivity
). - Simpan dan tutup file tersebut.
- Buka jendela setelan Unity, lalu pilih setelan Player. Luaskan bagian Publishing Settings, dan centang kotak Custom Main Manifest.
![Gambar 3.Opsi Manifes Utama Kustom di setelan Unity Player.](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unitymanifest.png?authuser=19&hl=id)
Project Anda kini disiapkan untuk menggunakan aktivitas kustom yang memanggil VkQuality saat memulai dan memilih Vulkan atau OpenGL ES berdasarkan rekomendasi VkQuality.
Menambahkan VkQuality ke aktivitas kustom yang ada
Jika game Anda sudah memiliki aktivitas kustom yang menggantikan UnityPlayerActivity
default, integrasikan rekomendasi VkQuality dengan menambahkan
kode berikut:
Pertama, tambahkan pernyataan impor VkQuality ke daftar impor di bagian atas file aktivitas kustom:
Kotlin
import com.google.android.games.vkquality.VKQuality;
Java
import com.google.android.games.vkquality.VKQuality;
Selanjutnya, buat beberapa konstanta dalam isi class Activity
untuk
pilihan API grafis:
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;
Buat variabel untuk melacak pilihan API:
Kotlin
private var apiOverride = OVERRIDE_NONE
Java
private int apiOverride = OVERRIDE_NONE;
Tambahkan fungsi berikut ke class Activity
Anda:
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); } }
Panggil fungsi CheckVkQuality
dari bagian atas fungsi penggantian onCreate()
sebelum memanggil implementasi class dasar:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { CheckVkQuality() super.onCreate(savedInstanceState) }
Java
@Override protected void onCreate(Bundle savedInstanceState) { CheckVkQuality(); super.onCreate(savedInstanceState); }
Terakhir, tambahkan penggantian fungsi updateUnityCommandLineArguments()
yang menggunakan nilai apiOverride
untuk meneruskan argumen command line ke
mesin Unity yang menentukan API grafis mana yang akan digunakan:
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; }
Aktivitas kustom Anda kini memanggil VkQuality saat startup dan memilih Vulkan atau OpenGL ES berdasarkan rekomendasi VkQuality.
Menggunakan daftar rekomendasi kustom
Tentukan file daftar rekomendasi kustom dengan meneruskan nama file
yang berisi daftar tersebut ke StartVkQuality()
, bukan meneruskan string kosong:
Kotlin
val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")
Java
int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");
VkQuality terlebih dahulu akan mencari file di direktori penyimpanan internal
aplikasi Anda. Jika file tidak ada di penyimpanan internal, VkQuality akan mencoba memuat
file dari aset app bundle Anda. Jika file tidak ada di kedua lokasi tersebut,
VkQuality akan menampilkan nilai enum ERROR_MISSING_DATA_FILE
.
Untuk membuat file daftar rekomendasi kustom, gunakan alat VkQuality List Editor yang ada di repositori GitHub. Dokumentasi untuk alat ini terdapat di README.