Definisci le annotazioni, i parametri di fedeltà e le impostazioni

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 e FidelityParams.
• Puoi utilizzare solo il valore enums definito in questo file come parte delle annotazioni.
• Puoi utilizzare solo enums, int32s o floats nei campi FidelityParams.
• 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 o TICK_BASED per caricare ogni n tick.
  • intervalms_or_count: n per il campo method.
  • max_instrumentation_keys: numero di tasti di strumentazione da utilizzare. Imposta 4 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 in logcat, verifica che la chiave API sia corretta.

• default_fidelity_parameters_filename: il set di parametri di fedeltà utilizzato all'inizializzazione (facoltativo se imposti training_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 e required 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.