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

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

Annotazioni e parametri di fedeltà

Le annotazioni forniscono informazioni contestuali su ciò che sta facendo il tuo gioco quando il segno di spunta viene registrato. I parametri di fedeltà riflettono le prestazioni e i dati impostazioni del gioco. Li definisci utilizzando i buffer di protocollo, che sono Il formato di interscambio dati, strutturato e indipendente dal linguaggio di Google. Per ulteriori informazioni informazioni sull'uso dei buffer di protocollo all'interno del gioco, vedi Informazioni sui buffer di protocollo.

Le annotazioni possibili e i parametri di fedeltà per il tuo gioco sono definiti in un denominato dev_tuningfork.proto, che si trova nell'area assets/tuningfork del tuo progetto. Di seguito è riportato un esempio tratto 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 enums definito in questo file come parte delle annotazioni.
• Puoi utilizzare solo enums, int32s o floats nei campi FidelityParams.
• La strumento di convalida applicano queste convenzioni.

Impostazioni

Il messaggio Settings è definito da tuningfork.proto. Consulta un esempio completo nella 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 situato nella directory assets/tuningfork del tuo progetto. Devi specificare solo i seguenti campi:

• aggregation_strategy: un messaggio contenente quanto segue:

  • method: TIME_BASED da 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 a 4 se utilizzi la libreria di pacing del frame Android.
  • annotation_enum_size: un campo facoltativo perché la dimensione viene calcolata all'avvio dal descrittore.

• api_key: la chiave API del progetto Cloud dell'app, utilizzata per convalidare le richieste per l'endpoint. Per generare questa chiave, consulta Abilita 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 in sull'inizializzazione (facoltativa se imposti training_fidelity_params nel codice).

• level_annotation_index: (facoltativo) l'indice nei campi di annotazione di il numero del 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 esempio nell'app demo che scorre tutti i livelli del gioco automaticamente. 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 sono esecuzione a un livello qualitativo troppo elevato (con conseguente riduzione delle prestazioni) oppure troppo basso (con conseguente riduzione inutilmente della fedeltà).

Devi definire almeno uno e preferibilmente diversi livelli qualitativi per il tuo per giocare. Un livello qualitativo corrisponde a un'istanza di FidelityParams . Questi livelli devono essere indicati in crescente ordine di fedeltà con la 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 gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ .

Informazioni sui buffer di protocollo

La libreria Tuning Fork utilizza il formato di buffer del protocollo di Google per impostazioni, annotazioni e parametri di fedeltà. Si tratta di una definizione protocollo multilingue per dati strutturati estensibili. Per ulteriori informazioni, vedi il Documentazione relativa ai buffer di protocollo.

Proto2 e proto3

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

syntax="proto2";

Proto2 e proto3 sono due versioni di buffer di protocollo di uso comune. Entrambi utilizzano lo stesso formato per i cavi, ma i file di definizione non sono compatibili. Legenda le differenze tra le due versioni includono quanto segue:

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

Usa proto3 nei tuoi file proto poiché possono essere compilati in C#. Proto2 funziona nonché con il limitato set di funzionalità utilizzato nella libreria Tuning Fork.

Rappresentazioni di testo e binarie

Il formato filo protobuf binario è ben definito e stabile in diverse le versioni protobuf (non lo è il codice generato). Esiste anche un formato di testo la versione completa della libreria protobuf può generare e leggere. Questo formato è non ben definito, ma è stabile per l'insieme limitato di funzionalità del nella libreria di Tuning Fork. Puoi convertire i formati binari e di testo usando 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é il la libreria protobuf completa ha una dimensione di diversi MB; realizzare il diapason nella raccolta dipendono da ciò aumentano le dimensioni del gioco di un valore simile.

Full, Lite e Nano

Oltre alla libreria completa di protobuf, c'è una versione Lite che riduce il codice tracciante rimuovendo alcune funzionalità come riflesso, FileDescriptors e da e verso formati di testo. Questa versione richiede ancora diversi MB di di codice in più, perciò la libreria Tuning Fork utilizza internamente libreria nanopb. Il codice sorgente per questa libreria è incluso nel Android Open Source Project in external/nanopb-c e fa parte del ramo gamesdk. Usa questa raccolta nel tuo gioco se le dimensioni del codice è un problema.

In gamesdk/src/protobuf esistono file CMake che possono aiutarti per l'integrazione tutte e tre le versioni di protobuf. I campioni utilizzano un mix di nanopb e full protobuf.