アノテーション、忠実度パラメータ、設定の定義

このドキュメントでは、プロジェクトにアノテーション、忠実度パラメータ、設定を定義する方法について説明します。

アノテーションと忠実度パラメータ

アノテーションは、記録されたティックでのゲームの動作に関するコンテキスト情報を提供するものです。忠実度パラメータは、ゲームのパフォーマンスとグラフィックの設定を反映します。これらは、プロトコル バッファという、Google が開発した言語に依存しない構造化されたデータ交換形式を使用して定義します。ゲーム内でのプロトコル バッファの使用について詳しくは、プロトコル バッファについてをご覧ください。

ゲームで使用できるアノテーションと忠実度パラメータは、プロジェクトの assets/tuningfork ディレクトリにある dev_tuningfork.proto というファイルで定義されます。次のデモアプリの例をご覧ください。

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

次の点に注意してください。

  • パッケージは com.google.tuningfork である必要があります。
  • メッセージ名は AnnotationFidelityParams に正確に一致している必要があります。
  • このファイルでアノテーションの一部として定義された enums のみを使用できます。
  • FidelityParams フィールドでは、enumsint32sfloats のみを使用できます。
  • これらの規則は、検証ツールによって遵守が求められます。

設定

Settings メッセージは tuningfork.proto で定義されます。次のファイルで完全な例をご覧ください。

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

ゲームの設定は、プロジェクトの assets/tuningfork ディレクトリにある tuningfork_settings.txt という名前のファイルで定義する必要があります。次のフィールドのみを指定する必要があります。

  • aggregation_strategy: 次を含むメッセージ

    • method: n ミリ秒ごとにアップロードする場合は TIME_BASEDn ティックごとにアップロードする場合は TICK_BASED
    • intervalms_or_count: method フィールドの n
    • max_instrumentation_keys: 使用するインストルメンテーション キーの数。Android Frame Pacing ライブラリを使用している場合は、4 に設定します。
    • annotation_enum_size: サイズは起動時にディスクリプタから算出されるため、省略可能なフィールドです。
  • api_key: エンドポイントへのリクエストを検証するために使用する、アプリの Cloud プロジェクト API キー。このキーの生成方法については、API を有効にするをご覧ください。logcat に接続エラーが表示される場合は、API キーが正しいことを確認してください。

  • default_fidelity_parameters_filename: 初期化で使用される忠実度パラメータのセット(コードで training_fidelity_params を設定した場合は省略可)。

  • level_annotation_index: (省略可)レベル番号のアノテーション フィールドのインデックス。

テキスト表現の例を次に示します。

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

アノテーションの設定

アノテーションは、ゲーム中に手動で設定する必要があります。その例は、すべてのゲームレベルを自動的に繰り返すデモアプリで確認できます。詳細については、insightsdemo.cppSetAnnotations() 関数をご覧ください。

この場合、アノテーションはレベル番号のみを指定しています。

message Annotation {
  Level level = 1;
}

品質レベルを定義する

品質レベルを使用してセッションにアノテーションを付けると、デバイスが高すぎる品質レベルで動作しているか(その結果パフォーマンスが低下する)、または低すぎる品質レベルで動作しているか(その結果不必要に忠実度が低下する)を判断できます。

ゲームの品質レベルは、少なくとも 1 つ以上定義する必要があります。できれば複数定義することをおすすめします。品質レベルは、FidelityParams メッセージのインスタンスに対応します。各レベルは、次のファイル名形式を使い、忠実度の昇順で指定する必要があります。

dev_tuningfork_fidelityparams_i.txt

ここで、i は 1 から 15 までのインデックスです。各ファイルは、プロジェクトの assets/tuningfork ディレクトリに置く必要があります。サンプル プロジェクトの gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ ディレクトリの構造は、その一例です。

プロトコル バッファについて

Tuning Fork ライブラリは、設定、アノテーション、忠実度パラメータに Google のプロトコル バッファ形式を使用します。これは、拡張可能な構造化データのための明確に定義された複数言語対応のプロトコルです。詳細については、プロトコル バッファのドキュメントをご覧ください。

proto2 と proto3 の違い

プロトコル バッファ形式のバージョンは、次のようにファイルの先頭行で設定されます。

syntax="proto2";

プロトコル バッファには、proto2 と proto3 の 2 つのバージョンが一般的に使用されています。どちらも同じワイヤ形式を使用しますが、定義ファイルには互換性がありません。2 つのバージョンの主な違いは次のとおりです。

  • proto3 では、optional キーワードと required キーワードが使用できなくなりました。
  • proto3 では、実質的にすべてが optional です。
  • proto3 では、拡張機能がサポートされません。

proto3 は C# にコンパイルできるため、proto ファイルでは proto3 を使用します。proto2 は、Tuning Fork ライブラリで使用される限定的な機能セットでも動作します。

テキスト表現とバイナリ表現

バイナリの protobuf ワイヤ形式は、明確に定義されていて、protobuf のバージョンが違っても変わりません(生成されるコードはそうではありません)。protobuf ライブラリの完全なバージョンが生成および読み取り可能なテキスト形式もあります。この形式は、明確に定義されていませんが、Tuning Fork ライブラリの限定的な機能セットに関しては安定しています。protoc コンパイラを使用すれば、バイナリ形式とテキスト形式の間の変換が可能です。次のコマンドは、テキストの protobuf をバイナリに変換します。

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

完全な protobuf ライブラリのサイズは数 MB あるため、APK にはテキスト ファイルではなくバイナリ ファイルを含める必要があります。Tuning Fork ライブラリをそれに依存させると、ゲームのサイズが同じように大きくなってしまいます。

完全版、軽量版、ナノ版

完全な protobuf ライブラリに加えて、リフレクション、FileDescriptors、テキスト形式との間のストリーミングなどの機能を削除してコード量を減らした軽量版も用意されています。このバージョンでも数 MB のコード量が追加となるため、Tuning Fork ライブラリは内部で nanopb ライブラリを使用しています。このライブラリのソースコードは、external/nanopb-cAndroid オープンソース プロジェクトに含まれており、gamesdk ブランチの一部となっています。コードサイズが問題になる場合は、このライブラリをゲームで使用してください。

gamesdk/src/protobuf には、3 つのバージョンの protobuf の組み込みに使用できる CMake ファイルがあります。このサンプルでは、nanopb と完全版の protobuf の両方を組み合わせて使用しています。