Questo documento descrive come impostare annotazioni, parametri di fedeltà e impostazioni nel tuo progetto.
Annotazioni e parametri di fedeltà
Le annotazioni forniscono informazioni contestuali sull'attività del gioco quando viene registrato un segno di spunta. I parametri di fedeltà riflettono le prestazioni e le impostazioni grafiche del gioco. Li definisci utilizzando i buffer di protocollo, il formato di interscambio dati, strutturato e indipendente dal linguaggio di Google. Per scoprire di più sull'utilizzo dei buffer di protocollo all'interno del gioco, consulta Informazioni sui buffer di protocollo.
Le possibili annotazioni e parametri di fedeltà per il gioco sono definiti in un file chiamato dev_tuningfork.proto
, che si trova nella directory assets/tuningfork
del progetto. Ecco un esempio dall'app 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;
}
Nota:
- Il pacchetto deve essere
com.google.tuningfork
. - I nomi dei messaggi devono essere esattamente
Annotation
eFidelityParams
. - Puoi utilizzare solo il valore
enums
definito in questo file come parte delle annotazioni. - Puoi utilizzare solo
enums
,int32s
ofloats
nei campiFidelityParams
. - Queste convenzioni vengono applicate dallo strumento di convalida.
Impostazioni
Il messaggio Settings
è definito da tuningfork.proto
. Vedi un esempio completo nel seguente file:
gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt
Devi definire le impostazioni del gioco in un file chiamato tuningfork_settings.txt
che si trova nella directory assets/tuningfork
del progetto. Devi specificare solo i seguenti campi:
aggregation_strategy
: un messaggio contenente quanto segue:method
:TIME_BASED
per caricare ogni n millisecondi oTICK_BASED
per caricare ogni n tick.intervalms_or_count
: n per il campomethod
.max_instrumentation_keys
: numero di tasti di strumentazione da utilizzare. Imposta4
se usi la libreria di pacing dei frame Android.annotation_enum_size
: un campo facoltativo poiché le dimensioni vengono calcolate all'avvio dal descrittore.
api_key
: la chiave API del progetto Cloud dell'app, utilizzata per convalidare le richieste all'endpoint. Per generare questa chiave, consulta Abilitare l'API. Se vedi errori di connessione inlogcat
, verifica che la chiave API sia corretta.default_fidelity_parameters_filename
: il set di parametri di fedeltà utilizzato all'inizializzazione (facoltativo se impostitraining_fidelity_params
nel codice).level_annotation_index
: (facoltativo) l'indice nei campi di annotazione del numero del livello.
Di seguito è riportato un esempio di rappresentazione di testo:
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
Impostazione delle annotazioni
Devi impostare manualmente le annotazioni durante il gioco. Puoi vederne un esempio nell'app demo mentre scorre automaticamente tutti i livelli del gioco. Per ulteriori informazioni, consulta la funzione SetAnnotations()
in insightsdemo.cpp
.
In questo caso, l'annotazione specifica solo il numero del livello.
message Annotation {
Level level = 1;
}
Definire i livelli qualitativi
Utilizza i livelli qualitativi per annotare le sessioni in modo da poter determinare se i dispositivi funzionano a un livello qualitativo troppo alto (con un conseguente peggioramento delle prestazioni) o troppo basso (con una conseguente riduzione inutilmente della fedeltà).
Devi definire almeno uno e, preferibilmente, diversi livelli qualitativi per il tuo gioco. Un livello qualitativo corrisponde a un'istanza del tuo messaggio FidelityParams
. Questi livelli devono essere specificati in ordine crescente di fedeltà con il seguente formato di nome file:
dev_tuningfork_fidelityparams_i.txt
dove i
è un indice che inizia da 1 con un valore massimo di 15. Questi file devono trovarsi nella directory assets/tuningfork
del progetto. Il progetto di esempio mostra un esempio di questa struttura nella directory gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/
.
Informazioni sui buffer di protocollo
La libreria di Tuning Fork utilizza il formato di buffer del protocollo di Google per impostazioni, annotazioni e parametri di fedeltà. Si tratta di un protocollo multilingue ben definito per dati strutturati estensibili. Per ulteriori informazioni, consulta la documentazione relativa ai buffer di protocollo.
Proto2 e proto3
La versione del formato del buffer di protocollo viene impostata nella prima riga del file:
syntax="proto2";
Proto2 e proto3 sono due versioni di uso comune dei buffer di protocollo. Utilizzano entrambi lo stesso formato di cavo, ma i file di definizione non sono compatibili. Le differenze chiave tra le due versioni includono quanto segue:
- Le parole chiave
optional
erequired
non sono più consentite in proto3. - In proto3 tutto è
optional
. - Le estensioni non sono supportate in proto3.
Usa proto3 nei file proto, poiché possono essere compilati in C#. Proto2 funziona bene con il set limitato di funzionalità usato nella libreria di Diapason.
Confronto tra testo e rappresentazioni binarie
Il formato binario protobuf è ben definito e stabile nelle diverse versioni di protobuf (il codice generato no). C'è anche un formato di testo
che la versione completa della libreria protobuf può generare. Questo formato
non è così ben definito, ma è stabile per l'insieme limitato di funzionalità
nella libreria di Diapason. Puoi convertire il formato binario e quello di testo
utilizzando il compilatore protoc
. Il seguente comando converte un protobuf di testo in binario:
protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin
Devi includere nell'APK file binari anziché file di testo perché la libreria protobuf completa ha dimensioni di diversi MB; rendere la libreria di Tuning Fork dipendere da questa, aumenterebbe le dimensioni del tuo gioco di una quantità simile.
Completa, Lite e nano
Oltre alla libreria completa di protobuf, è disponibile una versione Lite che riduce l'impronta di codice rimuovendo alcune funzionalità come il riflesso, FileDescriptors
e lo streaming da e verso i formati di testo. Questa versione richiede ancora diversi MB di codice aggiuntivo, perciò la libreria di Tuning Fork utilizza internamente la libreria nanopb. Il codice sorgente di questa libreria è incluso nel progetto open source Android in external/nanopb-c
e fa parte del ramo gamesdk
. Usa questa libreria nel tuo gioco se
è un problema di dimensione del codice.
In gamesdk/src/protobuf
sono disponibili file CMake che possono aiutarti a integrare tutte e tre le versioni di protobuf. Gli esempi utilizzano una combinazione di nanopb
e protobuf completo.