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 su cosa sta facendo il gioco quando viene registrato un tick. I parametri di fedeltà riflettono le impostazioni di prestazioni e grafica del gioco. Questi vengono definiti utilizzando i buffer di protocollo, che sono il formato di interscambio di dati strutturati e indipendenti dalla lingua di Google. Per maggiori informazioni sull'utilizzo dei buffer di protocollo nel gioco, consulta la sezione 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;
}

Nota:

• Il pacchetto deve essere com.google.tuningfork.
• I nomi dei messaggi devono essere esattamente Annotation e FidelityParams.
• Puoi utilizzare solo enums definiti 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 per il tuo gioco in un file chiamato tuningfork_settings.txt che si trova nella directory assets/tuningfork del tuo 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 chiavi di strumentazione da utilizzare. Imposta su 4 se utilizzi la libreria Android Frame Pacing.
  • annotation_enum_size: Un campo facoltativo, poiché le dimensioni vengono calcolate 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, vedi Abilitare 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 all'inizializzazione (facoltativo se imposti training_fidelity_params nel codice).

• level_annotation_index: (facoltativo) l'indice nei campi delle annotazioni del numero di 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

Impostare le annotazioni

Devi impostare manualmente le annotazioni durante la partita. Puoi vedere un esempio di questo nell'app demo, che scorre automaticamente tutti i livelli del 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 qualitativi

Utilizza i livelli qualitativi per annotare le sessioni in modo da poter determinare se i dispositivi stanno funzionando a un livello qualitativo troppo alto (con conseguente riduzione delle prestazioni) o troppo basso (con conseguente riduzione non necessaria della fedeltà).

Devi definire almeno uno e preferibilmente diversi livelli di qualità per il tuo gioco. Un livello di qualità corrisponde a un'istanza del tuo 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 tuo 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 del buffer di protocollo di Google per impostazioni, annotazioni e parametri di fedeltà. Si tratta di un protocollo multilingue ben definito per dati strutturati estensibili. Per saperne di più, consulta la documentazione di Protocol Buffers.

Proto2 e proto3

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

syntax="proto2";

Proto2 e proto3 sono due versioni di protocol buffer di uso comune. Entrambi utilizzano lo stesso formato di cablaggio, 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.
• Tutto è effettivamente optional in proto3.
• Le estensioni non sono supportate in proto3.

Utilizza proto3 nei file proto, in quanto possono essere compilati in C#. Proto2 funziona anche con il set di funzionalità limitato utilizzato nella libreria Tuning Fork.

Rappresentazioni testuali e binarie

Il formato di trasmissione binario protobuf è ben definito e stabile in 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 è ben definito, ma è stabile per il set limitato di funzionalità della libreria Tuning Fork. Puoi eseguire la conversione tra 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 nel tuo APK perché l'intera libreria protobuf ha dimensioni di diversi MB; se la libreria Tuning Fork dipendesse da essa, le dimensioni del tuo gioco aumenterebbero di un importo simile.

Full, Lite e Nano

Oltre alla libreria protobuf completa, esiste una versione lite che riduce l'impronta del codice rimuovendo alcune funzionalità come la reflection, FileDescriptors e lo streaming da e verso i formati di testo. Questa versione richiede ancora diversi MB di codice aggiuntivo e, pertanto, la libreria Tuning Fork utilizza internamente la libreria nanopb. Il codice sorgente di questa libreria è incluso in Android Open Source Project in external/nanopb-c ed è parte del ramo 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 un mix di nanopb e protobuf completo.