Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Menentukan anotasi, parameter fidelitas, dan setelan

Dokumen ini menjelaskan cara menyetel anotasi, parameter fidelitas, dan setelan dalam project Anda.

Anotasi dan parameter fidelitas

Anotasi memberikan informasi kontekstual tentang apa yang dilakukan game Anda saat tick direkam. Parameter fidelitas mencerminkan setelan performa dan grafis game. Anda menentukan hal ini menggunakan buffering protokol, yang merupakan format pertukaran data terstruktur dan netral bahasa dari Google. Untuk informasi selengkapnya cara menggunakan buffering protokol dalam game, lihat Tentang buffering protokol.

Anotasi yang memungkinkan dan parameter fidelitas untuk game Anda ditentukan dalam file bernama dev_tuningfork.proto, yang terletak di direktori assets/tuningfork project Anda. Berikut adalah contoh dari aplikasi demo:

syntax = "proto3";

package com.google.tuningfork;

enum InstrumentKey {
  CPU = 0;
  GPU = 1;
  SWAPPY_WAIT = 2;
  SWAPPY_SWAP = 3;
  CHOREOGRAPHER = 4;
}

enum LoadingState {
  LOADING_INVALID = 0;
  NOT_LOADING = 1;
  LOADING = 2;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

message FidelityParams {
  int32 num_spheres = 1;
  float tesselation_percent = 2;
}

Perhatikan hal berikut:

  • Paket harus com.google.tuningfork.
  • Nama pesan harus tepat Annotation dan FidelityParams.
  • Anda hanya dapat menggunakan enums yang ditentukan dalam file ini sebagai bagian dari anotasi.
  • Anda hanya dapat menggunakan enums, int32s, atau floats di kolom FidelityParams.
  • Alat validasi memberlakukan konvensi ini.

Setelan

Pesan Settings ditentukan oleh tuningfork.proto. Lihat contoh lengkap dalam file berikut:

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

Anda harus menentukan setelan untuk game dalam file bernama tuningfork_settings.txt yang ada di direktori assets/tuningfork project Anda. Anda hanya perlu menentukan kolom berikut:

  • aggregation_strategy: Pesan yang berisi hal berikut:

    • method: TIME_BASED untuk mengupload setiap n milidetik atau TICK_BASED untuk mengupload setiap n tick.
    • intervalms_or_count: n untuk kolom method.
    • max_instrumentation_keys: Jumlah kunci instrumentasi yang digunakan. Setel ke 4 jika menggunakan library Android Frame Pacing.
    • annotation_enum_size: Kolom opsional karena ukurannya dihitung saat memulai dari deskriptor.
  • api_key: Kunci API project Cloud aplikasi Anda, digunakan untuk memvalidasi permintaan ke endpoint. Untuk membuat kunci ini, lihat Mengaktifkan API. Jika Anda melihat error koneksi dalam logcat, pastikan kunci API sudah benar.

  • default_fidelity_parameters_filename: Kumpulan parameter fidelitas yang digunakan saat inisialisasi (opsional jika Anda menyetel training_fidelity_params dalam kode Anda).

  • loading_annotation_index: (Opsional) Indeks di kolom anotasi Anda dari tanda LoadingState.

  • level_annotation_index: (Opsional) Indeks dalam kolom anotasi nomor level.

Berikut adalah contoh representasi teks:

aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
  max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
loading_annotation_index: 1
level_annotation_index: 2

Anotasi pemuatan

Anotasi pemuatan menandai frame yang merupakan bagian dari proses pemuatan level. Anda harus menggunakan anotasi pemuatan sehingga frame yang lebih lambat yang terjadi saat game dimuat tidak memengaruhi keseluruhan metrik.

Saat menyetel kolom loading_annotation_index di setelan, arti khusus diberikan pada anotasi dengan indeks tersebut. Misalnya, pada aplikasi demo, anotasi berikut digunakan:

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

Saat anotasi pemuatan ditetapkan ke LOADING, tick frame akan diabaikan. Saat anotasi pemuatan direset ke NOT_LOADING, waktu yang dihabiskan dalam status LOADING direkam dalam histogram untuk anotasi tersebut. Gunakan anotasi ini untuk melacak waktu yang diperlukan untuk memuat level dalam game Anda. Anda menentukan nomor level sebagai nilai dari enum Level.

Pada setelan di atas, karena loading_annotation_index adalah 1, anotasi pertama menentukan apakah game memuat scene berikutnya atau tidak. Karena level_annotation_index adalah 2, anotasi kedua menentukan nomor level.

Anda perlu menyetel anotasi ini secara manual selama game. Anda dapat melihat contohnya dalam aplikasi demo saat otomatis bertransisi melalui semua level game. Untuk informasi selengkapnya, lihat fungsi SetAnnotations() dalam insightsdemo.cpp.

Menentukan tingkat kualitas

Gunakan level kualitas untuk memberikan anotasi pada sesi sehingga Anda dapat menentukan apakah perangkat berjalan pada tingkat kualitas yang terlalu tinggi (yang mengakibatkan performa lebih rendah) atau terlalu rendah (mengakibatkan berkurangnya fidelitas yang tidak perlu).

Anda harus menentukan tingkat kualitas setidaknya satu, dan sebaiknya beberapa, untuk game Anda. Tingkat kualitas sesuai dengan instance pesan FidelityParams Anda. Tingkat ini harus diberikan dalam peningkatan urutan fidelitas dengan format nama file berikut:

dev_tuningfork_fidelityparams_i.txt

dengan i adalah indeks yang dimulai pada 1 dengan nilai maksimum 15. File ini harus berada di direktori assets/tuningfork project Anda. Project contoh menunjukkan contoh struktur ini dalam direktori gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Tentang buffering protokol

Library Tuning Fork menggunakan format buffering protokol Google untuk setelan, anotasi, dan parameter fidelitas. Ini adalah protokol multibahasa yang terdefinisi dengan baik untuk data terstruktur yang dapat diperluas. Untuk informasi selengkapnya, lihat dokumentasi Buffering Protokol.

Proto2 vs proto3

Versi format buffering protokol disetel pada baris pertama file:

syntax="proto2";

Proto2 dan proto3 adalah dua versi buffering protokol yang umum digunakan. Keduanya menggunakan format berkabel yang sama tetapi file definisinya tidak kompatibel. Perbedaan utama antara kedua versi tersebut meliputi:

  • Kata kunci optional dan required tidak lagi diizinkan di proto3.
  • Semuanya sebenarnya optional di proto3.
  • Ekstensi tidak didukung di proto3.

Gunakan proto3 di file proto Anda karena dapat dikompilasi ke C#. Proto2 berfungsi dengan baik dengan rangkaian fitur terbatas yang digunakan di library Tuning Fork.

Representasi teks versus biner

Format berkabel protobuf biner didefinisikan dengan baik dan stabil di seluruh versi protobuf yang berbeda (kode yang dihasilkan tidak). Ada juga format teks yang dapat dibuat dan dibaca oleh library protobuf versi lengkap. Format ini tidak ditentukan dengan baik, tetapi stabil untuk rangkaian fitur terbatas dalam library Tuning Fork. Anda dapat melakukan konversi antara format biner dan teks menggunakan compiler protoc. Perintah berikut mengonversi protobuf teks menjadi biner:

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

Anda harus menyertakan file biner, bukan file teks di APK karena library protobuf lengkap berukuran beberapa MB; membuat library Tuning Fork bergantung pada hal tersebut akan meningkatkan ukuran game Anda dengan jumlah yang sama.

Full versus Lite versus Nano

Selain library protobuf lengkap, terdapat versi ringan yang mengurangi jejak kode dengan menghapus beberapa fitur seperti refleksi, FileDescriptors, dan streaming ke dan dari format teks. Versi ini masih memerlukan beberapa MB jejak kode tambahan, sehingga library Tuning Fork secara internal menggunakan library nanopb. Kode sumber untuk library ini disertakan dalam Proyek Open Source Android di external/nanopb-c dan merupakan bagian dari cabang gamesdk. Gunakan library ini dalam game Anda jika ukuran kode menjadi masalah.

Terdapat file CMake di gamesdk/src/protobuf yang dapat membantu Anda mengintegrasikan ketiga versi protobuf. Sampel menggunakan gabungan nanopb dan protobuf lengkap.