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

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

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

הערות מספקות מידע הקשרי לגבי מה שהמשחק שלך עושה כאשר תיבת הסימון מתועדת. פרמטרים של איכות משקפים את הביצועים הגדרות המשחק. אתם מגדירים אותם באמצעות מאגרי פרוטוקולים, שהם פורמט של 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: מספר מקשי האינסטרומנטציה שבהם צריך להשתמש. סיום אל 4 אם משתמשים בספרייה של Android Frame Pacing.
  • annotation_enum_size: שדה אופציונלי מאחר שהגודל מחושב בזמן ההפעלה מהמתאר.

• api_key: מפתח ה-API של הפרויקט ב-Cloud של האפליקציה, שמשמש לאימות בקשות אל נקודת הקצה. כדי ליצור את המפתח הזה: מפעילים את ה-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

הגדרת הערות

צריך להגדיר הערות באופן ידני במהלך המשחק. אפשר לראות דוגמה לכך באפליקציית ההדגמה במהלך הסבב של כל השלבים במשחק באופן אוטומטי. לקבלת מידע נוסף, אפשר להיעזר בפונקציה 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 לצורך ההגדרות, ההערות ופרמטרים של דיוק. זוהי מדיניות מוגדרת היטב, פרוטוקול רב-לשוני לנתונים מובנים ניתנים להרחבה. לקבלת מידע נוסף, לראות את מסמכי תיעוד של מאגרי פרוטוקולים

Proto2 לעומת proto3

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

syntax="proto2";

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

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

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

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

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

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

צריך לכלול קבצים בינאריים ולא קובצי טקסט ב-APK כי ספריית Protobuf מלאה היא בגודל של כמהMB; להכין את מזלג הכוונון תלויה בכך, הוא יגדיל את גודל המשחק במידה דומה.

מלא לעומת Lite לעומת נאנו

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

יש קובצי CMake ב-gamesdk/src/protobuf שיכולים לעזור לך לשלב את כל שלוש הגרסאות של הפרוטובוף. בדגימות נעשה שימוש בשילוב של ננו-ביות ומלא ב-Protobuf.