Definiowanie adnotacji, parametrów wierności i ustawień

Z tego dokumentu dowiesz się, jak ustawiać w projekcie adnotacje, parametry wierności i ustawienia.

Adnotacje i parametry wierności

Adnotacje zawierają kontekstowe informacje o tym, co gra robi, gdy rejestrowany jest znacznik. Parametry wierności odzwierciedlają wydajność i ustawienia graficzne gry. Definiujesz je za pomocą buforów protokołu, które są niezależnym od języka, uporządkowanym formatem wymiany danych Google. Więcej informacji o używaniu buforów protokołów w grze znajdziesz w artykule Bufor protokołów.

Możliwe adnotacje i parametry wierności dla Twojej gry są zdefiniowane w pliku o nazwie dev_tuningfork.proto, który znajduje się w katalogu assets/tuningfork projektu. Oto przykład z aplikacji demonstracyjnej:

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

Uwaga:

• Pakiet musi mieć wartość com.google.tuningfork.
• Nazwy wiadomości muszą być dokładnie takie same jak Annotation i FidelityParams.
• W adnotacjach możesz używać tylko enums zdefiniowanych w tym pliku.
• W polach FidelityParams możesz używać tylko znaków enums, int32s lub floats.
• Narzędzie do weryfikacji wymusza przestrzeganie tych konwencji.

Ustawienia

Wiadomość Settings jest zdefiniowana przez tuningfork.proto. Pełny przykład znajdziesz w tym pliku:

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

Ustawienia gry musisz zdefiniować w pliku o nazwie tuningfork_settings.txt znajdującym się w katalogu assets/tuningfork projektu. Musisz podać tylko te pola:

• aggregation_strategy: wiadomość zawierająca:

  • method: TIME_BASED, aby przesyłać dane co n milisekund, lub TICK_BASED, aby przesyłać dane co n tyknięć.
  • intervalms_or_count: n w przypadku pola method.
  • max_instrumentation_keys: liczba kluczy instrumentacji do użycia. Ustaw wartość 4, jeśli używasz biblioteki Android Frame Pacing.
  • annotation_enum_size: pole opcjonalne, ponieważ rozmiar jest obliczany przy uruchamianiu na podstawie deskryptora.

• api_key: klucz interfejsu API projektu Cloud Twojej aplikacji, który służy do weryfikowania żądań wysyłanych do punktu końcowego. Aby wygenerować ten klucz, zapoznaj się z artykułem Włączanie interfejsu API. Jeśli w logcat widzisz błędy połączenia, sprawdź, czy klucz interfejsu API jest prawidłowy.

• default_fidelity_parameters_filename: zestaw parametrów wierności używany podczas inicjowania (opcjonalny, jeśli w kodzie ustawisz parametr training_fidelity_params).

• level_annotation_index: (Opcjonalnie) Indeks w polach adnotacji numeru poziomu.

Oto przykład reprezentacji tekstowej:

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

Ustawianie adnotacji

Adnotacje musisz ustawiać ręcznie w trakcie gry. Przykład tego możesz zobaczyć w aplikacji demonstracyjnej, która automatycznie przechodzi przez wszystkie poziomy gry. Więcej informacji znajdziesz w artykule o funkcji SetAnnotations() w insightsdemo.cpp.

W tym przypadku adnotacja określa tylko numer poziomu.

message Annotation {
  Level level = 1;
}

Określanie poziomów jakości

Poziomy jakości służą do oznaczania sesji, dzięki czemu możesz sprawdzić, czy urządzenia działają na zbyt wysokim poziomie jakości (co skutkuje niższą wydajnością) lub zbyt niskim poziomie jakości (co skutkuje niepotrzebnie obniżoną wiernością).

Musisz zdefiniować co najmniej 1, a najlepiej kilka poziomów jakości gry. Poziom jakości odpowiada instancji Twojej wiadomości FidelityParams. Poziomy te muszą być podane w kolejności rosnącej wierności w formacie nazwy pliku:

dev_tuningfork_fidelityparams_i.txt

gdzie i to indeks zaczynający się od 1 i mający maksymalną wartość 15. Te pliki muszą znajdować się w katalogu assets/tuningfork projektu. Przykładowy projekt pokazuje przykład tej struktury w katalogu gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Informacje o buforach protokołu

Biblioteka Tuning Fork używa formatu bufora protokołu Google do ustawień, adnotacji i parametrów wierności. Jest to dobrze zdefiniowany, wielojęzyczny protokół do rozszerzalnych danych strukturalnych. Więcej informacji znajdziesz w dokumentacji buforów protokołu.

Proto2 a proto3

Wersja formatu bufora protokołu jest ustawiona w pierwszym wierszu pliku:

syntax="proto2";

Proto2 i proto3 to 2 najczęściej używane wersje buforów protokołu. Oba formaty używają tego samego formatu przesyłania, ale pliki definicji nie są ze sobą zgodne. Najważniejsze różnice między tymi 2 wersjami to:

• Słowa kluczowe optional i required nie są już dozwolone w proto3.
• Wszystko jest w proto3 optional.
• Rozszerzenia nie są obsługiwane w proto3.

W plikach proto używaj proto3, ponieważ można je skompilować do C#. Proto2 działa również z ograniczonym zestawem funkcji używanym w bibliotece Tuning Fork.

Tekstowe i binarne reprezentacje

Binarny format przesyłania protobuf jest dobrze zdefiniowany i stabilny w różnych wersjach protobuf (wygenerowany kod nie jest). Istnieje też format tekstowy, który może generować i odczytywać pełna wersja biblioteki protokołów buforowanych. Ten format nie jest tak dobrze zdefiniowany, ale jest stabilny w przypadku ograniczonego zestawu funkcji w bibliotece Tuning Fork. Za pomocą kompilatora protoc możesz konwertować formaty binarne na tekstowe i odwrotnie. To polecenie przekształca tekstowy protokół buforowany na binarny:

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

W pliku APK musisz umieścić pliki binarne, a nie tekstowe, ponieważ pełna biblioteka protobuf ma kilka megabajtów. Uzależnienie od niej biblioteki Tuning Fork zwiększyłoby rozmiar gry o podobną wartość.

Wersja pełna, Lite i Nano

Oprócz pełnej biblioteki buforów protokołu dostępna jest też wersja uproszczona, która zmniejsza rozmiar kodu przez usunięcie niektórych funkcji, takich jak odbicie, FileDescriptors oraz przesyłanie strumieniowe do i z formatów tekstowych. Ta wersja nadal wymaga kilku MB dodatkowego kodu, dlatego biblioteka Tuning Fork wewnętrznie korzysta z biblioteki nanopb. Kod źródłowy tej biblioteki jest dostępny w Android Open Source Project w external/nanopb-c i jest częścią gałęzi gamesdk. Użyj tej biblioteki w grze, jeśli rozmiar kodu jest problemem.

W folderze gamesdk/src/protobuf znajdują się pliki CMake, które pomogą Ci zintegrować wszystkie 3 wersje protokołu buforów. Przykłady korzystają z nanopb i pełnego protokołu protobuf.