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

Questo documento descrive come impostare annotazioni, parametri di fedeltà e impostazioni nel progetto.

Annotazioni e parametri di fedeltà

Le annotazioni forniscono informazioni contestuali su ciò che sta facendo il gioco quando viene registrato un tick. I parametri di fedeltà riflettono le prestazioni e le impostazioni grafiche del tuo gioco. Questi vengono definiti utilizzando i buffer di protocollo, che sono il formato di interscambio di dati strutturati e indipendenti dal linguaggio di Google. Per saperne di più sull'utilizzo dei buffer di protocollo all'interno del gioco, consulta Informazioni sui buffer di protocollo.

Le possibili annotazioni e i parametri di fedeltà per il tuo gioco sono definiti in un file denominato dev_tuningfork.proto, che si trova nella directory assets/tuningfork del tuo 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;
}

Tieni presente quanto segue:

  • 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.
  • Lo strumento di convalida applica queste convenzioni.

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 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: il numero di chiavi di instrumentazione da utilizzare. Imposta su 4 se utilizzi la libreria Android Frame Pacing.
    • annotation_enum_size: un campo facoltativo, poiché la dimensione viene calcolata all'avvio dal descrittore.
  • api_key: la chiave API del progetto cloud della tua app, utilizzata per convalidare le richieste all'endpoint. Per generare questa chiave, consulta Abilita l'API. Se visualizzi errori di connessione in logcat, verifica che la chiave API sia corretta.

  • default_fidelity_parameters_filename: il set di parametri di fedeltà utilizzato durante l'inizializzazione (facoltativo se imposti training_fidelity_params nel codice).

  • level_annotation_index: (facoltativo) l'indice nei campi di annotazione del numero di livello.

Di seguito è riportato un esempio di rappresentazione testuale:

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 vedere un esempio di questo nell'app demo, che scorre automaticamente tutti i livelli di gioco. Per saperne di più, consulta la funzione SetAnnotations() in insightsdemo.cpp.

In questo caso, l'annotazione specifica solo il numero del livello.

message Annotation {
  Level level = 1;
}

Definisci i livelli di qualità

Utilizza i livelli di qualità per annotare le sessioni in modo da poter determinare se i dispositivi sono in esecuzione su un livello di qualità troppo elevato (con conseguente riduzione delle prestazioni) o troppo basso (con conseguente riduzione non necessaria della fedeltà).

Devi definire almeno un livello di qualità per il tuo gioco, preferibilmente più di uno. Un livello di qualità corrisponde a un'istanza del messaggio FidelityParams. Questi livelli devono essere forniti in ordine di fedeltà crescente con il seguente formato del 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 Tuning Fork utilizza il formato buffer di protocollo di Google per impostazioni, annotazioni e parametri di fedeltà. Si tratta di un protocollo multilingue ben definito per dati strutturati ed estensibili. Per saperne di più, consulta la documentazione dei buffer di protocollo.

Proto2 e proto3

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

syntax="proto2";

Proto2 e proto3 sono due versioni di buffer di protocollo comunemente utilizzate. Entrambi utilizzano lo stesso formato di rete, ma i file di definizione non sono compatibili. Le principali differenze tra le due versioni includono:

  • Le parole chiave optional e required non sono più consentite in proto3.
  • In proto3, tutto è effettivamente optional.
  • Le estensioni non sono supportate in proto3.

Utilizza proto3 nei file proto, poiché possono essere compilati in C#. Anche Proto2 funziona con l'insieme limitato di funzionalità utilizzato nella libreria Tuning Fork.

Rappresentazioni di testo e binarie a confronto

Il formato di rete binario di protobuf è ben definito e stabile tra le diverse versioni di 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 è così ben definito, ma è stabile per l'insieme limitato di funzionalità della libreria Tuning Fork. Puoi convertire i formati binari e 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 file binari anziché file di testo nell'APK perché la libreria protobuf completa ha una dimensione di diversi MB. Se la libreria Tuning Fork dipendesse da questa, le dimensioni del gioco aumenterebbero di una quantità simile.

Full, Lite e Nano a confronto

Oltre alla libreria protobuf completa, esiste una versione lite che riduce l'impatto del codice rimuovendo alcune funzionalità come la riflessione, FileDescriptors e lo streaming da e verso i formati di testo. Questa versione richiede comunque diversi MB di spazio aggiuntivo per il codice, pertanto la libreria Tuning Fork utilizza internamente la libreria nanopb. Il codice sorgente di questa libreria è incluso nell'Android Open Source Project in external/nanopb-c e fa parte del branch gamesdk. Utilizza 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.