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 tick. I parametri di fedeltà riflettono le prestazioni e le impostazioni grafiche del gioco. Puoi definire questi valori mediante 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 tuo gioco vengono definiti in un file chiamato dev_tuningfork.proto, che si trova nella directory assets/tuningfork del progetto. Di seguito è riportato un esempio dell'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 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 file seguente:

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

Devi definire le impostazioni del gioco in un file denominato 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. Impostalo su 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 è riportata una rappresentazione testuale di esempio:

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 annotazioni

Devi impostare manualmente le annotazioni durante il gioco. Puoi vederne un esempio nell'app demo in quanto 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 (che comporta prestazioni inferiori) o troppo basso (con una conseguente riduzione inutilmente della fedeltà).

Devi definire almeno uno e preferibilmente più livelli qualitativi per il gioco. Un livello qualitativo corrisponde a un'istanza del messaggio FidelityParams. Questi livelli devono essere indicati in ordine di fedeltà crescente 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 sui buffer di protocollo.

Proto2 e proto3

La versione del formato del buffer del protocollo viene impostata nella prima riga del file:

syntax="proto2";

Proto2 e proto3 sono due versioni comunemente utilizzate dei buffer di protocollo. Utilizzano entrambi lo stesso formato di cablaggio, ma i file di definizione non sono compatibili. Le differenze chiave tra le due versioni includono:

  • Le parole chiave optional e required non sono più consentite nel proto3.
  • Tutto è efficacemente optional in proto3.
  • Le estensioni non sono supportate in proto3.

Utilizza proto3 nei file proto perché possono essere compilati in C#. Proto2 funziona bene con il set limitato di funzionalità usato nella libreria di Tuning Diapason.

Confronto tra rappresentazioni di testo e binarie

Il formato binario protobuf filo è ben definito e stabile tra diverse versioni protobuf (il codice generato non lo è). Esiste anche un formato di testo che la versione completa della libreria protobuf può generare e leggere. Questo formato non è molto ben definito, ma è stabile per l'insieme limitato di funzionalità nella libreria diapason. Puoi convertire tra formati binari e di testo utilizzando il compilatore protoc. Il seguente comando converte un testo protobuf in binario:

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

Devi includere file binari anziché file di testo nell'APK perché la libreria protobuf completa ha una dimensione di diversi MB; in questo modo la libreria di Tuning Fork dipende da quest'ultima aumenterà le dimensioni del tuo gioco di una quantità simile.

Confronto tra modalità Full, Lite e Nano

Oltre alla libreria protobuf completa, è 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 spazio di codice extra, pertanto la libreria Tuning Fork utilizza internamente la libreria nanopb. Il codice sorgente per 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 le dimensioni del codice sono un problema.

In gamesdk/src/protobuf sono presenti file CMake che possono aiutarti a integrare tutte e tre le versioni di protobuf. Gli esempi utilizzano una combinazione di nanopb e protobuf completo.