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 Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  Level level = 1;
}

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).

• 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"
level_annotation_index: 1

Menyetel anotasi

Anda perlu menyetel anotasi 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.

Dalam hal ini, anotasi hanya menentukan nomor level.

message Annotation {
  Level level = 1;
}

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.