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

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

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

تقدّم التعليقات التوضيحية معلومات سياقية عن ما تفعله لعبتك عند تسجيل وحدة قياس. تعكس مَعلَمات الدقّة إعدادات الأداء والرسومات في لعبتك. يمكنك تحديد هذه البيانات باستخدام مخازن البروتوكول، وهي تنسيق تبادل بيانات منظَّم ومحايد للغة من 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/.

لمحة عن آليات سَلسلة البيانات المنظّمة

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

Proto2 مقابل proto3

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

syntax="proto2";

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

• لم يعُد يُسمح باستخدام الكلمتَين الرئيسيتَين optional وrequired في proto3.
• كل شيء optional في الإصدار 3 من البروتوكول.
• لا تتوافق الإضافات مع الإصدار proto3.

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

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

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

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

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

مقارنة بين الإصدارات الكاملة وLite وNano

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

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