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

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

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

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

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

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

تنسيق سلك Protobuf الثنائي محدد جيدًا ومستقر عبر إصدارات Protobuf المختلفة (التعليمة البرمجية التي يتم إنشاؤها ليست كذلك). هناك أيضًا تنسيق نصي يمكن للنسخة الكاملة من مكتبة النماذج الأوّلية إنشاءه وقراءته. هذا التنسيق غير محدد جيدًا، لكنه مستقر لمجموعة محدودة من الميزات في مكتبة 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 يمكنها مساعدتك في دمج النُسخ الثلاثة جميعها من النموذج الأولي. تستخدم العينات خليطًا من كل من نانوب ونموذج كامل.