O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

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 LoadingState {
  LOADING_INVALID = 0;
  NOT_LOADING = 1;
  LOADING = 2;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

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).

  • loading_annotation_index: (opcional) índice nos campos de anotação da sinalização LoadingState.

  • 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"
loading_annotation_index: 1
level_annotation_index: 2

Anotações de carregamento

As anotações de carregamento marcam os frames que fazem parte do processo de carregamento de níveis. Use anotações de carregamento para que os frames mais lentos que ocorrem durante o carregamento do jogo não afetem as métricas gerais.

Ao definir o campo loading_annotation_index nas configurações, um significado específico é atribuído à anotação com esse índice. Por exemplo, no app de demonstração, a seguinte anotação é usada:

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

Quando a anotação de carregamento está definida como LOADING, as marcações de frame são ignoradas. Quando ela é redefinida como NOT_LOADING, o tempo gasto no estado LOADING é gravado no histograma dessa anotação. Use essa anotação para monitorar o tempo necessário para carregar um nível no seu jogo. O número do nível é especificado como um valor da enumeração Level.

Nas configurações acima, como loading_annotation_index é 1, a primeira anotação especifica se o jogo carregará a próxima cena ou não. Como level_annotation_index é 2, a segunda anotação especifica o número do nível.

Essas 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.

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.