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

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

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

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

Proto2 مقابل Proto3

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

syntax="proto2";

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

• لم يعد من الممكن استخدام الكلمتَين الرئيسيتَين optional وrequired في Proto3.
• كل شيء هو optional بشكل فعال في Proto3.
• لا تتوفّر الإضافات في Proto3.

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

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

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

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

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

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

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

هناك ملفات CMake في gamesdk/src/protobuf يمكن أن تساعدك على الدمج جميع النسخ الثلاثة من Protobuf. تستخدم العينات مزيجًا من نانوب (nanopb) ونموذج كامل Protobuf.