הגדרת הערות, פרמטרים של איכות והגדרות

במאמר הזה מוסבר איך להגדיר הערות, פרמטרים של אמינות (Fidelity) והגדרות בפרויקט.

הערות ופרמטרים של אמינות (Fidelity)

ההערות מספקות מידע לפי ההקשר על מה שקורה במשחק כשנרשם טיק. פרמטרים של אמינות (Fidelity) משקפים את הביצועים ואת ההגדרות הגרפיות של המשחק. אתם מגדירים את השירותים האלה באמצעות מאגרי אחסון לפרוטוקולים, שהם פורמט חילופי הנתונים המובְנים של Google, שאינו תלוי שפה. מידע נוסף על השימוש במאגרי אחסון לפרוטוקולים במשחק זמין במאמר מידע על מאגרי אחסון לפרוטוקולים.

ההערות ופרמטרי האמינות האפשריים של המשחק מוגדרים בקובץ שנקרא dev_tuningfork.proto, שנמצא בספרייה assets/tuningfork של הפרויקט. הנה דוגמה מאפליקציית ההדגמה:

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 שמוגדרים בקובץ הזה כחלק מההערות.
  • אפשר להשתמש רק ב-enums, ב-int32s או ב-floats בשדות של FidelityParams.
  • כלי האימות אוכף את המוסכמות האלה.

הגדרות

ההודעה Settings מוגדרת על ידי tuningfork.proto. דוגמה מלאה בקובץ הבא:

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

אתם צריכים להגדיר את המשחק בקובץ בשם tuningfork_settings.txt שנמצא בספרייה assets/tuningfork של הפרויקט. צריך לציין רק את השדות הבאים:

  • ‫aggregation_strategy: הודעה שמכילה את הפרטים הבאים:

    • ‫method: הערך TIME_BASED כדי להעלות כל n אלפיות השנייה, או הערך TICK_BASED כדי להעלות כל n טיקים.
    • ‫intervalms_or_count: ‏n בשדה method.
    • ‫max_instrumentation_keys: מספר המפתחות לציון מקום שבהם רוצים להשתמש. אם משתמשים בספריית Android Frame Pacing, צריך להגדיר את הערך 4.
    • annotation_enum_size: שדה אופציונלי, כי הגודל מחושב בזמן ההפעלה מהמתאר.
  • ‫api_key: מפתח ה-API של הפרויקט בענן של האפליקציה, שמשמש לאימות בקשות לנקודת הקצה. כדי ליצור את המפתח הזה, קראו את המאמר הפעלת ה-API. אם מופיעות שגיאות חיבור ב-logcat, צריך לוודא שמפתח ה-API נכון.

  • ‫default_fidelity_parameters_filename: קבוצת פרמטרים של אמינות (Fidelity) שמשמשת לאתחול (אופציונלי אם מגדירים את 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

הגדרת הערות

אתם צריכים להגדיר הערות באופן ידני במהלך המשחק. אפשר לראות דוגמה לכך באפליקציית ההדגמה, שבה המערכת עוברת באופן אוטומטי בין כל השלבים במשחק. מידע נוסף זמין בפונקציה SetAnnotations() במאמר insightsdemo.cpp.

במקרה כזה, ההערה מציינת רק את מספר הרמה.

message Annotation {
  Level level = 1;
}

הגדרת רמות איכות

אתם יכולים להשתמש ברמות איכות כדי להוסיף הערות לסשנים, וכך לקבוע אם המכשירים פועלים ברמת איכות גבוהה מדי (מה שמוביל לביצועים נמוכים יותר) או נמוכה מדי (מה שמוביל להפחתה מיותרת של רמת הדיוק).

צריך להגדיר לפחות רמת איכות אחת למשחק, ועדיף כמה. רמת איכות תואמת למופע של הודעת FidelityParams. צריך לתת את הרמות האלה בסדר עולה של רמת הפירוט, בפורמט הבא של שם הקובץ:

dev_tuningfork_fidelityparams_i.txt

כאשר i הוא אינדקס שמתחיל ב-1 עם ערך מקסימלי של 15. הקבצים האלה חייבים להיות בספרייה assets/tuningfork של הפרויקט. בפרויקט לדוגמה מוצגת דוגמה למבנה הזה בספרייה gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

מידע על מאגרי אחסון לפרוטוקולים

ספריית Tuning Fork משתמשת בפורמט מאגר האחסון לפרוטוקולים של Google להגדרות, להערות ולפרמטרים של אמינות (Fidelity). זהו פרוטוקול מוגדר היטב, שפועל בכמה שפות, לנתונים מובְנים שניתנים להרחבה. מידע נוסף זמין במאמרי העזרה בנושא מאגרי אחסון לפרוטוקולים.

‫Proto2 לעומת proto3

הגרסה של פורמט מאגר האחסון לפרוטוקולים מוגדרת בשורה הראשונה של הקובץ:

syntax="proto2";

‫Proto2 ו-proto3 הן שתי גרסאות נפוצות של מאגרי אחסון לפרוטוקולים. שניהם משתמשים באותו פורמט wire, אבל קובצי ההגדרה לא תואמים. אלה ההבדלים העיקריים בין שתי הגרסאות:

  • מילות המפתח optional ו-required כבר לא מותרות ב-proto3.
  • ב-proto3, כל השדות הם למעשה optional.
  • תוספים לא נתמכים ב-proto3.

השתמשו ב-proto3 בקובצי ה-proto, כי אפשר לקמפל אותם ל-C#‎. גם Proto2 פועל עם קבוצת התכונות המוגבלת שבה נעשה שימוש בספריית Tuning Fork.

ייצוגים של טקסט לעומת ייצוגים בינאריים

הפורמט הבינארי של protobuf מוגדר היטב ויציב בגרסאות שונות של protobuf (הקוד שנוצר לא יציב). יש גם פורמט טקסט שהגרסה המלאה של ספריית protobuf יכולה ליצור ולקרוא. הפורמט הזה פחות מוגדר, אבל הוא יציב עבור קבוצת התכונות המוגבלת בספריית Tuning Fork. אפשר להמיר בין פורמטים בינאריים לפורמטים של טקסט באמצעות המהדר protoc. הפקודה הבאה ממירה protobuf של טקסט לבינארי:

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

אתם צריכים לכלול קבצים בינאריים ולא קובצי טקסט ב-APK, כי ספריית protobuf המלאה היא בגודל של כמה מגה-בייטים. אם ספריית Tuning Fork תהיה תלויה בה, גודל המשחק יגדל בכמות דומה.

‫Full לעומת Lite לעומת Nano

בנוסף לספריית protobuf המלאה, יש גרסת Lite שמקטינה את טביעת הרגל של הקוד על ידי הסרת תכונות מסוימות כמו השתקפות, FileDescriptors וסטרימינג אל פורמטים של טקסט ומפורמטים של טקסט. הגרסה הזו עדיין דורשת כמה מגה בייט של קוד נוסף, ולכן ספריית Tuning Fork משתמשת באופן פנימי בספריית nanopb. קוד המקור של הספרייה הזו כלול בפרויקט הקוד הפתוח של Android ב-external/nanopb-c, והוא חלק מההסתעפות gamesdk. אם גודל הקוד הוא בעיה, כדאי להשתמש בספרייה הזו במשחק.

יש קובצי CMake ב-gamesdk/src/protobuf שיכולים לעזור לכם לשלב את כל שלוש הגרסאות של protobuf. הדוגמאות משתמשות בשילוב של nanopb ו-protobuf מלא.