يوضّح هذا المستند كيفية ضبط التعليقات التوضيحية ومَعلمات الدقة والإعدادات في مشروعك.
التعليقات التوضيحية ومَعلَمات الدقة
توفّر التعليقات التوضيحية معلومات سياقية عن لقطة معيَّنة في لعبتك عند تسجيل علامة اختيار. تعكس مَعلَمات الدقّة إعدادات الأداء والرسومات في لعبتك. يمكنك تحديد هذه الخدمات باستخدام Protocol Buffers، وهي تنسيق Google لتبادل البيانات المنظَّمة وغير المرتبطة بلغة معيّنة. لمزيد من المعلومات حول استخدام Protocol Buffers في لعبتك، يُرجى الاطّلاع على لمحة عن Protocol Buffers.
يتم تحديد التعليقات التوضيحية ومَعلمات الدقة المحتمَلة للعبتك في ملف باسم 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/.
لمحة عن Protocol Buffers
تستخدم مكتبة Tuning Fork تنسيق Protocol Buffers من Google للإعدادات وعلامات التوضيح ومَعلمات الدقة. هذا بروتوكول محدّد جيدًا ومتعدّد اللغات للبيانات المنظَّمة القابلة للتوسيع. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Protocol Buffers.
Proto2 مقابل proto3
يتم ضبط إصدار تنسيق Protocol Buffers في السطر الأول من الملف:
syntax="proto2";
Proto2 وproto3 هما إصداران شائعان من Protocol Buffers. يستخدم كلاهما تنسيق النقل نفسه، ولكن ملفات التعريف غير متوافقة. تشمل الاختلافات الرئيسية بين الإصدارَين ما يلي:
- لم يعُد مسموحًا باستخدام الكلمتَين الرئيسيَّتين
optionalوrequiredفي proto3. - كل شيء هو
optionalبشكل فعّال في proto3. - لا تتوفّر الإضافات في proto3.
استخدِم proto3 في ملفات proto لأنّه يمكن تجميعها في C#. تعمل Proto2 أيضًا مع مجموعة الخصائص المحدودة المستخدَمة في مكتبة Tuning Fork.
التمثيلات النصية مقابل التمثيلات الثنائية
إنّ تنسيق protobuf الثنائي السلكي محدّد بشكل جيد ومستقر في مختلف إصدارات protobuf (الرمز الذي يتم إنشاؤه ليس كذلك). هناك أيضًا تنسيق نصي يمكن للنسخة الكاملة من مكتبة protobuf إنشاؤه وقراءته. هذا التنسيق ليس محدّدًا بشكل جيد، ولكنه ثابت لمجموعة محدودة من الميزات في مكتبة Tuning Fork. يمكنك التحويل بين التنسيقات الثنائية والنصية
باستخدام برنامج التجميع protoc. يحوّل الأمر التالي ملف protobuf نصي إلى
ملف ثنائي:
protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin
يجب تضمين ملفات ثنائية بدلاً من الملفات النصية في حزمة APK لأنّ حجم مكتبة protobuf الكاملة يبلغ عدة ميغابايت، وسيؤدي جعل مكتبة Tuning Fork تعتمد عليها إلى زيادة حجم لعبتك بمقدار مماثل.
الإصدار الكامل مقابل الإصدار Lite مقابل الإصدار Nano
بالإضافة إلى مكتبة protobuf الكاملة، هناك نسخة مخفّفة تقلّل من حجم الرمز البرمجي من خلال إزالة بعض الميزات مثل الانعكاس وFileDescriptors والبث من وإلى التنسيقات النصية. لا يزال هذا الإصدار يتطلّب عدة ميغابايت من
الرمز البرمجي الإضافي، وبالتالي تستخدم مكتبة Tuning Fork
مكتبة nanopb داخليًا. يتوفّر الرمز المصدر لهذه المكتبة
في مشروع مفتوح المصدر لنظام Android في external/nanopb-c وهو جزء من الفرع
gamesdk. يمكنك استخدام هذه المكتبة في لعبتك إذا كان حجم الرمز البرمجي يمثّل مشكلة.
هناك ملفات CMake في gamesdk/src/protobuf يمكن أن تساعدك في دمج
جميع الإصدارات الثلاثة من protobuf. تستخدم النماذج مزيجًا من nanopb وprotobuf
الكامل.