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

W tym dokumencie opisujemy, jak skonfigurować adnotacje, parametry wierności i ustawienia w projekcie.

Adnotacje i parametry wierności

Adnotacje zawierają kontekstowe informacje o tym, co robi gra po zarejestrowaniu sygnału. Parametry wierności odzwierciedlają wydajność i grafikę gry. Definiujesz je za pomocą buforów protokołów, czyli neutralnego pod względem języka, uporządkowanych danych wymiany danych Google. Więcej informacji o korzystaniu z buforów protokołów w grze znajdziesz w artykule Informacje o buforach protokołów.

Możliwe adnotacje i parametry wierności gry są zdefiniowane w pliku dev_tuningfork.proto znajdującym 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ć com.google.tuningfork.
• Nazwy wiadomości muszą mieć dokładnie Annotation i FidelityParams.
• W adnotacjach możesz używać tylko tych elementów (enums), które są zdefiniowane w tym pliku.
• Możesz użyć tylko enums, int32s lub floats w polach FidelityParams.
• Te konwencje egzekwuje narzędzie do weryfikacji.

Ustawienia

Komunikat Settings jest definiowany 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 określić w pliku o nazwie tuningfork_settings.txt w katalogu assets/tuningfork projektu. Musisz wypełnić tylko te pola:

• aggregation_strategy: wiadomość zawierająca następujące informacje:

  • method: TIME_BASED, by przesyłać co n milisekund, lub TICK_BASED, co n.
  • intervalms_or_count: n dla pola method.
  • max_instrumentation_keys: liczba klawiszy instrumentacji, których chcesz użyć. Jeśli używasz biblioteki Android Frame Pacing, ustaw wartość 4.
  • annotation_enum_size: pole opcjonalne, ponieważ rozmiar jest obliczany przy uruchamianiu na podstawie deskryptora.

• api_key: klucz interfejsu API projektu Cloud Twojej aplikacji używany do weryfikacji żądań wysyłanych do punktu końcowego. Aby wygenerować ten klucz, przeczytaj sekcję Włączanie interfejsu API. Jeśli w narzędziu logcat widzisz błędy połączenia, sprawdź, czy klucz interfejsu API jest prawidłowy.

• default_fidelity_parameters_filename: zestaw parametrów wierności użytych podczas inicjowania (opcjonalnie, jeśli w kodzie ustawiono training_fidelity_params).

• level_annotation_index: (opcjonalnie) indeks numeru poziomu w polach adnotacji.

Oto przykładowa reprezentacja tekstu:

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

W trakcie gry musisz ręcznie ustawić adnotacje. Taki przykład możesz zobaczyć w wersji demonstracyjnej, w której automatycznie mija wszystkie poziomy gry. Więcej informacji znajdziesz w opisie funkcji SetAnnotations() w insightsdemo.cpp.

W tym przypadku adnotacja określa tylko numer poziomu.

message Annotation {
  Level level = 1;
}

Definiowanie poziomów jakości

Używaj poziomów jakości do dodawania adnotacji do sesji. Dzięki temu możesz określić, czy urządzenia mają zbyt wysoki poziom jakości (powodujący niższą wydajność) czy zbyt niski (powodujący niepotrzebnie obniżoną jakość).

Musisz zdefiniować co najmniej jeden, a najlepiej kilka poziomów jakości gry. Poziom jakości odpowiada wystąpieniu Twojej wiadomości FidelityParams. Poziomy te muszą być podane w rosnącej kolejności wierności, w tym formacie nazw plików:

dev_tuningfork_fidelityparams_i.txt

gdzie i to indeks zaczynający się od 1, a maksymalna wartość – 15. Pliki te 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łów

Biblioteka Tuning Fork korzysta z formatu bufora protokołu Google do obsługi ustawień, adnotacji i parametrów wierności. Jest to dobrze zdefiniowany, wielojęzyczny protokół do rozszerzania uporządkowanych danych. Więcej informacji znajdziesz w dokumentacji buforów protokołu.

Proto2 a proto3

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

syntax="proto2";

Proto2 i proto3 to 2 powszechnie używane wersje buforów protokołów. Oba korzystają z tego samego formatu przewodów, ale pliki definicji nie są zgodne. Najważniejsze różnice między tymi 2 wersjami:

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

Użyj proto3 w plikach proto, ponieważ można je skompilować do języka C#. Proto2 działa też z ograniczonym zestawem funkcji z biblioteki Tuning Fork.

Reprezentacje tekstowe i binarne

Format przewodu binarnego protokołu jest dobrze zdefiniowany i stabilny w różnych wersjach protokołu (generowany kod nie jest). Istnieje również format tekstowy, który może być generowany i odczytywany w pełnej wersji biblioteki protobuf. Ten format nie jest tak dobrze zdefiniowany, ale działa stabilnie na ograniczonej liczbie funkcji w bibliotece Tuing Fork. Za pomocą kompilatora protoc możesz konwertować formaty binarne i tekstowe. To polecenie konwertuje protobuf tekstowy na plik binarny:

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

W pakiecie APK musisz umieścić pliki binarne, a nie tekstowe, ponieważ biblioteka Protobuf ma kilka MB. Zastosowanie biblioteki Tuning Fork będzie zależało od tego, co spowodowałoby zwiększenie rozmiaru gry.

Pełne vs. uproszczone a nano

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

W gamesdk/src/protobuf znajdują się pliki CMake, które pomogą Ci zintegrować wszystkie 3 wersje protokołu protobuf. Próbki wykorzystują zarówno nanopb, jak i pełne protobufy.