Definir anotações, parâmetros de fidelidade e configurações

Este documento descreve como definir anotações, parâmetros de fidelidade e configurações no projeto.

Anotações e parâmetros de fidelidade

As anotações oferecem informações contextuais sobre o que o jogo está fazendo no momento que uma marcação é registrada. Os parâmetros de fidelidade refletem o desempenho e as configurações gráficas do jogo. Para defini-los, use buffers de protocolo, que são o formato neutro, estruturado e de troca de dados da linguagem do Google. Para ver mais informações sobre o uso de buffers de protocolo no jogo, consulte Sobre buffers de protocolo.

As possíveis anotações e parâmetros de fidelidade do jogo são definidas em um arquivo chamado dev_tuningfork.proto, localizado no diretório assets/tuningfork do projeto. Veja a seguir um exemplo do app de demonstração:

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;
}

Observe o seguinte:

• O pacote precisa ser com.google.tuningfork.
• Os nomes das mensagens precisam ser exatamente Annotation e FidelityParams.
• Só é possível usar enums definidos nesse arquivo como parte de anotações.
• Só é possível usar enums, int32s ou floats em campos FidelityParams.
• A ferramenta de validação aplica essas convenções.

Configurações

A mensagem Settings é definida por tuningfork.proto. Veja um exemplo completo no arquivo a seguir:

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

Defina as configurações do jogo em um arquivo chamado tuningfork_settings.txt, localizado no diretório assets/tuningfork do projeto. Só é necessário especificar os seguintes campos:

• aggregation_strategy: uma mensagem contendo as informações abaixo.

  • method: TIME_BASED para fazer upload a cada n milissegundos ou TICK_BASED para fazer upload a cada n marcações.
  • intervalms_or_count: n para o campo method.
  • max_instrumentation_keys: número de chaves de instrumentação a serem usadas. Defina como 4 se estiver usando a biblioteca Android Frame Pacing.
  • annotation_enum_size: campo opcional, já que o tamanho é calculado na inicialização a partir do descritor.

• api_key: chave da API do projeto na nuvem do seu app, usada para validar solicitações para o endpoint. Para gerar essa chave, consulte Ativar a API. Caso note erros de conexão em logcat, verifique se a chave de API está correta.

• default_fidelity_parameters_filename: o parâmetro de fidelidade definido, usado na inicialização (opcional se você definir training_fidelity_params no código).

• level_annotation_index: (opcional) índice nos campos de anotação do número de nível.

Veja a seguir um exemplo de representação de texto:

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

Como definir anotações

As anotações precisam ser definidas manualmente durante o jogo. É possível ver um exemplo disso no app de demonstração, à medida que ele percorre todos os níveis do jogo de forma automática. Para ver mais informações, consulte a função SetAnnotations() em insightsdemo.cpp.

Nesse caso, a anotação especifica apenas o número do nível do jogo.

message Annotation {
  Level level = 1;
}

Definir níveis de qualidade

Use os níveis de qualidade para anotar sessões para que seja possível determinar se os dispositivos estão executando o app em um nível de qualidade muito alto (o que resulta em desempenho inferior) ou muito baixo (o que resulta em fidelidade desnecessariamente reduzida).

É preciso definir pelo menos um nível de qualidade, e de preferência vários, para o jogo. O nível de qualidade corresponde a uma instância da mensagem FidelityParams. Esses níveis precisam ser apresentados em ordem crescente de fidelidade, com o seguinte formato de nome de arquivo:

dev_tuningfork_fidelityparams_i.txt

em que i é um índice com início em 1 e com valor máximo de 15. Esses arquivos ficam localizados no diretório assets/tuningfork do projeto. O projeto de amostra apresenta um exemplo dessa estrutura no diretório gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Sobre os buffers de protocolo

A biblioteca Tuning Fork usa o formato de buffer de protocolo do Google para configurações, anotações e parâmetros de fidelidade. Esse é um protocolo bem definido e em vários idiomas para dados estruturados e extensíveis. Para ver mais informações, consulte a documentação dos buffers de protocolo.

Proto2 vs. proto3

A versão do formato do buffer de protocolo é definida na primeira linha do arquivo:

syntax="proto2";

Proto2 e proto3 são duas versões de buffers de protocolo usadas com frequência. Ambas usam o mesmo formato de condutor, mas os arquivos de definição não são compatíveis. As principais diferenças entre as duas versões incluem:

• As palavras-chave optional e required não são mais permitidas no proto3.
• Tudo é efetivamente optional no proto3.
• As extensões não são compatíveis com o proto3.

Use proto3 nos arquivos .proto, já que eles podem ser compilados para C#. O Proto2 também funciona com o conjunto limitado de recursos usado na biblioteca Tuning Fork.

Texto vs. representações binárias

O formato de condutor protobuf binário é bem definido e estável em diferentes versões do protobuf (o código gerado não é). Há também um formato de texto que a versão completa da biblioteca protobuf pode gerar e ler. Esse formato não é tão bem definido, mas é estável para o conjunto limitado de recursos na biblioteca Tuning Fork. É possível fazer a conversão entre formatos binários e de texto usando o compilador protoc. O comando a seguir converte uma protobuf de texto em binário:

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

É necessário incluir arquivos binários em vez de arquivos de texto no seu APK, porque a biblioteca protobuf completa tem vários MB de tamanho e fazer com que a biblioteca Tuning Fork dependa dela aumentaria o tamanho do jogo de forma semelhante.

Completa vs. Lite vs. Nano

Além da biblioteca protobuf completa, existe uma versão Lite, que reduz o tamanho da área ocupada pelo código removendo alguns recursos, como reflexão, FileDescriptors e streaming, de formatos de texto. Nessa versão, o código ainda ocupa vários MB. Por esse motivo, a biblioteca Tuning Fork usa a biblioteca nanopb internamente. O código-fonte dessa biblioteca está incluído no Android Open Source Project em external/nanopb-c e faz parte da ramificação gamesdk. Use essa biblioteca no seu jogo se o tamanho do código for um problema.

Há arquivos CMake em gamesdk/src/protobuf que podem ajudar a integrar todas as três versões da protobuf. As amostras usam uma combinação de nanopb e protobuf completa.