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
iFidelityParams
. - 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
lubfloats
w polachFidelityParams
. - 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, lubTICK_BASED
, co n.intervalms_or_count
: n dla polamethod
.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ędziulogcat
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 ustawionotraining_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
irequired
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.