このドキュメントでは、プロジェクトにアノテーション、忠実度パラメータ、設定を定義する方法について説明します。
アノテーションと忠実度パラメータ
アノテーションは、記録されたティックでのゲームの動作に関するコンテキスト情報を提供するものです。忠実度パラメータは、ゲームのパフォーマンスとグラフィックの設定を反映します。これらは、プロトコル バッファという、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
である必要があります。 - メッセージ名は
Annotation
とFidelityParams
に正確に一致している必要があります。 - このファイルでアノテーションの一部として定義された
enums
のみを使用できます。 FidelityParams
フィールドでは、enums
、int32s
、floats
のみを使用できます。- これらの規則は、検証ツールによって遵守が求められます。
設定
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_BASED
、n ティックごとにアップロードする場合は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.cpp
の SetAnnotations()
関数をご覧ください。
この場合、アノテーションはレベル番号のみを指定しています。
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-c
の Android オープンソース プロジェクトに含まれており、gamesdk
ブランチの一部となっています。コードサイズが問題になる場合は、このライブラリをゲームで使用してください。
gamesdk/src/protobuf
には、3 つのバージョンの protobuf の組み込みに使用できる CMake ファイルがあります。このサンプルでは、nanopb と完全版の protobuf の両方を組み合わせて使用しています。