تحديد التعليقات التوضيحية ومعلّمات الدقة والإعدادات

يصف هذا المستند كيفية تعيين التعليقات التوضيحية ومعلمات الدقة والإعدادات في مشروعك.

التعليقات التوضيحية ومعلمات الدقّة

تقدّم التعليقات التوضيحية معلومات سياقية حول ما تفعله لعبتك عند تسجيل علامة. تعكس معلمات الدقّة أداء لعبتك والإعدادات الرسومية. يمكنك تحديد هذه باستخدام المخازن الاحتياطية للبروتوكولات، وهي تنسيق تبادل البيانات المهيكلة والمحايد من 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: مفتاح واجهة برمجة التطبيقات لمشروع تطبيقك على السحابة الإلكترونية يتم استخدامه للتحقّق من صحة الطلبات المُرسَلة إلى نقطة النهاية. لإنشاء هذا المفتاح، راجِع تفعيل واجهة برمجة التطبيقات. إذا ظهرت لك أخطاء في الاتصال في logcat، تأكَّد من صحة مفتاح واجهة برمجة التطبيقات.

• 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/.

لمحة عن الموارد الاحتياطية للبروتوكولات

تستخدم مكتبة "الشوكة الرنانة" تنسيق المخزن المؤقت للبروتوكولات من Google للإعدادات والتعليقات التوضيحية ومعلمات الدقة. هذا بروتوكول محدد جيدًا ومتعدد اللغات للبيانات المنظَّمة القابلة للتوسُّع. لمزيد من المعلومات، اطّلِع على مستندات الموارد الاحتياطية للبروتوكول.

Proto2 مقابل Proto3

يتم تحديد إصدار تنسيق المخزن المؤقت للبروتوكولات في السطر الأول من الملف:

syntax="proto2";

Proto2 وproto3 هما إصداران شائعان الاستخدام من المخازن الاحتياطية للبروتوكول. كلتاهما تستخدم نفس تنسيق الأسلاك لكن ملفات التعريف غير متوافقة. وتشمل الاختلافات الرئيسية بين الإصدارين ما يلي:

• لم يعد مسموحًا باستخدام الكلمتين الرئيسيتين optional وrequired في Proto3.
• كل شيء يمثل optional بفعالية في Proto3.
• الإضافات غير متاحة في Proto3.

استخدم Proto3 في ملفات Proto الخاصة بك حيث يمكن تجميعها إلى C#. يعمل Proto2 أيضًا مع مجموعة الميزات المحدودة المستخدمة في مكتبة Tuning Fork.

التمثيلات النصية مقابل التمثيلات الثنائية

تنسيق سلك النموذج الثنائي محدد جيدًا ومستقر عبر إصدارات النموذج الأوّلي المختلفة (الرمز الذي يتم إنشاؤه ليس كذلك). هناك أيضًا تنسيق نصي يمكن للنسخة الكاملة من مكتبة النموذج الأوّلي إنشاؤه وقراءته. هذا التنسيق ليس محدّدًا جيدًا، ولكنه مستقر لمجموعة محدودة من الميزات في مكتبة Tuning Fork. يمكنك التحويل بين التنسيقات الثنائية والتنسيقات النصية باستخدام المحول البرمجي protoc. يقوم الأمر التالي بتحويل نموذج أوّلي نصي إلى ثنائي:

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

يجب تضمين ملفات ثنائية بدلاً من ملفات نصية في حزمة APK لأن مكتبة النموذج الكامل بحجمها يصل إلى عدة ميغابايت، حيث إن جعل مكتبة "الشوكة الرنانة" تعتمد على زيادة حجم اللعبة بمقدار مماثل.

الكامل مقابل Lite مقابل Nano

بالإضافة إلى مكتبة النماذج الأوّلية الكاملة، يتوفّر إصدار مبسّط يقلل من تأثير الرموز البرمجية عن طريق إزالة بعض الميزات، مثل الانعكاس وFileDescriptors والبث من التنسيقات النصية وإليها. لا يزال هذا الإصدار يتطلب عدة ميغابايت من البصمة الإضافية للرموز، ولذلك تستخدم مكتبة Tuning Fork داخليًا مكتبة nanopb. تم تضمين رمز المصدر لهذه المكتبة في مشروع مفتوح المصدر لنظام Android في external/nanopb-c، وهو جزء من فرع gamesdk. استخدِم هذه المكتبة في لعبتك إذا كان حجم التعليمات البرمجية مشكلة.

هناك ملفات CMake المرتبطة في gamesdk/src/protobuf والتي يمكن أن تساعدك في دمج جميع إصدارات النموذج الأوّلي الثلاثة. تستخدم العينات مزيجًا من البروتوكولات النانوبية والنموذج الكامل.