الوسوم الذكية

بالإضافة إلى حقول إدخال المستخدم، يمكن لوسوم meta أيضًا استرداد البيانات من SignalRGB API. وتُعرف هذه باسم العدّادات (meters)، وهي مختلفة عن صنف Meter الذي نوقش في قسم المقتطفات (Snippets). هناك أربعة أنواع من العدّادات المرئية المتاحة: linear وarea وocr_textmatch وocr_numeric.

بالإضافة إلى ذلك، توفر واجهة API سبع خصائص للمحتوى: مستوى الصوت، وعرض الصوت، وكثافة الصوت، وتردد الصوت، ودرجة لون المنطقة، وتشبّع المنطقة، وإضاءة المنطقة.

العدّادات

تشترك جميع العدّادات في أربع سمات أساسية:

السمات	الوصف
Meter	تحدد اسم المتغير، ويمكن الوصول إليه عبر engine.vision.meter، حيث meter هو الاسم الذي اخترته.
Type	تحدد نوع العدّاد: linear أو area أو ocr_textmatch أو ocr_numeric
X	الإحداثي X، بالصيغة المُسوّاة. يُرسم العدّاد بدءًا من زاويته العلوية اليسرى.
Y	الإحداثي Y، بالصيغة المُسوّاة.

الإحداثيات المُسوّاة

يجب إدخال الإحداثيين X وY، بالإضافة إلى الارتفاع والعرض، كقيم مُسوّاة. على سبيل المثال، إذا كنت ألعب لعبة بدقة 1920x1080 وأريد وضع عدّاد صغير في منتصف الجانب الأيسر من الشاشة تقريبًا، فأحدد نقطة أصل العدّاد (الزاوية العلوية اليسرى) على أنها 50 بكسل من اليسار و500 بكسل نزولًا من الزاوية العلوية اليسرى للشاشة.

وهذا يعطيني:

x = 50, y = 500.

لتحويل هذه القيم إلى إحداثيات مُسوّاة، أقسم x على عرض الشاشة (1920) وy على ارتفاع الشاشة (1080)، فتكون النتيجة (مقرّبة وبالتنسيق الصحيح):

x = “.026”, y = “.463”

على الرغم من أن هذا التحويل يُفترض نظريًا أن يتيح للعدّاد العمل بأي دقة ذات نسبة عرض إلى ارتفاع 16:9، فإن كثيرًا من الألعاب تشهد تغييرات صغيرة في واجهة المستخدم بين الدقات المختلفة. سيتم تناول كيفية تنسيق العدّادات للدقات المختلفة في قسم استكشاف الأخطاء وإصلاحها أسفل هذه الصفحة.

العدّاد الخطي

يُرجع العدّاد الخطي نسبة البكسلات على طول خط أفقي التي تطابق نطاق HSL محددًا، بقيمة من 0.0 إلى 1.0. على سبيل المثال، سيُرجع عدّاد خطي يغطي العرض الكامل لشريط صحة أخضر القيمة 0.5 عندما تكون الصحة في منتصفها.

<meta meter="myLinear" type="linear" x=".1729" y=".9740" width=".0390" h="0-360" s="0-10" l="90-100">

تتطلب العدّادات الخطية أربع سمات إضافية:

السمة	الوصف
Width	قيمة العرض، معبَّرًا عنها بالصيغة المُسوّاة
H	مكوّن درجة اللون في HSL، ويتراوح من 0 إلى 360
S	مكوّن التشبع في HSL، من 0% إلى 100%
L	مكوّن الإضاءة في HSL، من 0% إلى 100%

عدّاد المساحة

يُرجع عدّاد المساحة نسبة البكسلات داخل منطقة مستطيلة التي تقع ضمن نطاق HSL محدد، بقيم من 0.0 إلى 1.0. ويمكن استخدام هذا النوع من العدّادات لاكتشاف عناصر واجهة المستخدم الأكبر حجمًا مثل مربعات النص أو مناطق الخريطة المصغرة.

<meta meter="myArea" type="area" x=".1729" y=".9740" width=".0390" height=".02" h="0-360" s="0-10" l="90-100">

تتطلب عدّادات المساحة خمس سمات إضافية:

السمة	الوصف
Width	قيمة العرض، معبَّرًا عنها بالصيغة المُسوّاة
Height	قيمة الارتفاع، معبَّرًا عنها بالصيغة المُسوّاة
H	مكوّن درجة اللون في HSL، ويتراوح من 0 إلى 360
S	مكوّن التشبع في HSL، من 0% إلى 100%
L	مكوّن الإضاءة في HSL، من 0% إلى 100%

عدّاد مطابقة نص OCR

يستخدم هذا العدّاد التعرف الضوئي على الحروف (OCR) للبحث عن سلسلة نصية محددة داخل منطقة مستطيلة محددة على الشاشة. إذا عُثر على السلسلة، فإنه يُرجع 1؛ وإذا لم يُعثر عليها، فإنه يُرجع 0؛ وإذا لم يكن متأكدًا، فإنه يُرجع -1.

<meta meter="myTextOCR" type="ocr_textmatch" x=".1729" y=".9740" width=".0390" height=".02" string="my string" confidence="70">

تتطلب عدّادات مطابقة نص OCR أربع سمات إضافية:

السمة	الوصف
Width	العرض، بالصيغة المُسوّاة.
Height	الارتفاع، بالصيغة المُسوّاة.
String	السلسلة النصية المراد البحث عنها. حساسة لحالة الأحرف.
Confidence	قيمة من 0 إلى 100 تحدد مدى تأكد العدّاد المطلوب من وجود تطابق. القيمة الافتراضية 70 إذا لم تُحدَّد.

عدّاد OCR الرقمي

يستخدم هذا العدّاد التعرف الضوئي على الحروف (OCR) لاكتشاف القيم الرقمية داخل منطقة مستطيلة على الشاشة. إذا نجح، فإنه يُرجع الرقم كعدد صحيح؛ وإذا فشل، فإنه يُرجع -1.

<meta meter="myNumOCR" type="ocr_numeric" x=".1729" y=".9740" width=".0390" height=".02" confidence="70">

تتطلب عدّادات OCR الرقمية ثلاث سمات إضافية:

السمة	الوصف
Width	العرض، بالصيغة المُسوّاة.
Height	الارتفاع، بالصيغة المُسوّاة.
Confidence	قيمة من 0 إلى 100 تحدد مدى تأكد العدّاد المطلوب من وجود تطابق. القيمة الافتراضية 70 إذا لم تُحدَّد.

خصائص المحتوى

خصائص المحتوى هي عدّادات عالية الكثافة تأتي مباشرة من واجهة API.

خصائص الصوت

تُرجع engine.audio.level مستوى الصوت الحالي بالديسيبل.
تعطي engine.audio.width عرض الاستريو المُدرَك للصوت الوارد، كنسبة من 0 إلى 1.
توفر engine.audio.density كثافة التردد للصوت الوارد، أيضًا كنسبة من 0 إلى 1 - فالضجيج الأبيض ينتج قيمًا قريبة من 1.0، بينما تُرجع النغمات النقية قيمًا أقرب إلى 0.
تُرجع engine.audio.freq مصفوفة من 200 عنصر، يمثل كل منها المستوى الحالي لنطاق تردد محدد.

خصائص الشاشة

تُرجع engine.zone.hue مصفوفة من 560 عنصرًا، يمثل كل منها قيمة درجة اللون لنقطة على الشاشة. وتُؤخذ عينات هذه النقاط من شبكة بحجم 28 x 20.
تُرجع engine.zone.saturation مصفوفة من 560 عنصرًا، يمثل كل منها التشبع عند نقطة على الشاشة، مأخوذة من الشبكة نفسها بحجم 28 x 20.
تُرجع engine.zone.lightness مصفوفة من 560 عنصرًا، يشير كل منها إلى قيمة الإضاءة عند نقطة على الشاشة، مأخوذة أيضًا من الشبكة بحجم 28 x 20.

استكشاف الأخطاء وإصلاحها

عند كتابة الشيفرة، قد تحدث مشكلات. فيما يلي بعض المشكلات الشائعة المتعلقة بالعدّادات وكيفية إصلاحها:

“العدّاد أو عنصر التحكم الخاص بي لا يظهر في التطبيق”
- جرّب إغلاق التطبيق بالكامل وإعادة تشغيله. إذا استمرت المشكلة، فقد يكون العدّاد منسّقًا بشكل غير صحيح. تحقق مجددًا من الإملاء وعلامات الترقيم.
“التطبيق أو LightScript يستمر في التعطل”
- غالبًا ما يكون سبب ذلك عدّادًا مشوّه الصياغة. فالسمات المفقودة أو الزائدة يمكن أن تتسبب في تعطل التطبيق أو الشيفرة. إذا كانت عدّاداتك صحيحة، فابحث عن مشكلات مثل الحلقات اللانهائية أو المتغيرات غير المُعرَّفة.
“العدّاد يظهر لكنه لا يتتبع المنطقة الصحيحة من الشاشة”
- قد تكون الإحداثيات المُسوّاة غير صحيحة. تذكّر: المعادلة هي x / عرض الشاشة، وy / ارتفاع الشاشة. إذا لم تكن الرياضيات نقطة قوتك، فجرّب زيادة عرض العدّاد أو ارتفاعه للمساعدة في تحديد منطقة الشاشة الصحيحة. لكن ضع في اعتبارك أن العدّادات المستطيلة ستبدو مضغوطة عموديًا في أداة الفحص.
“العدّاد يعمل على دقة واحدة، لكن ليس على الدقات الأخرى”
- لحسن الحظ، لن تحتاج إلى عدّادات متعددة لواجهة المستخدم الديناميكية. انظر أدناه للاطلاع على مثال لعدّاد خطي مُكيَّف لدقات متعددة.

<meta meter="health" tags="vlc,fortnite" x= ".05"  y=".9" width=".189" h="70-140" s="40-100" l="40-100" type="linear">
    <resolution size="3440x1440" x="0.1666" y="0.8993" width="0.1541"/>
    <resolution size="2560x1080" x="0.1666" y="0.8993" width="0.1541"/>
    <resolution size="1920x1080" x="0.0557" y="0.9083" width="0.199"/>
</meta>

كما ترى، لقد ضبطت العدّاد خصيصًا للدقتين 3840x2160 و2560x1080. وستستخدم جميع الدقات الأخرى العدّاد الأصلي افتراضيًا.

“العدّاد في موضعه الصحيح لكنه لا يُشغِّل التأثير”
- بصفتك مطوّر LightScript، ستكون هذه مشكلة شائعة. فعدّادات المساحة والعدّادات الخطية قد تكون حساسة جدًا مع التدرجات اللونية أو واجهات المستخدم الشفافة. افتح منزلق HSL (مثل هذا) وراقب شاشتك حتى تتطابق الألوان. ابدأ بنطاقات واسعة في درجة اللون والتشبع والإضاءة حتى يعمل العدّاد باستمرار، ثم ضيّقها. بالنسبة لعدّادات OCR، تأكد من تضمين الكلمة أو الرقم المستهدف بالكامل داخل العدّاد، مع أقل قدر ممكن من المحتوى الإضافي. هناك حد لحجم النص أو دقة الشاشة التي تعمل عليها عدّادات OCR. وضع عدّاد OCR على نص “VICTORY” كبير يملأ شاشة بدقة 1920x1080؟ لا مشكلة. لكن جرّبه على مربع دردشة بدقة 1280x720 وسترى نتائج محدودة. كذلك، فإن التباين العالي بين النص والخلفية مثالي لـ OCR – فلن تُقرأ نصوص بيضاء على خلفية بيضاء.
“العدّاد يُشغِّل التأثير بسرعة كبيرة أو طوال الوقت”
- تهانينا، عدّادك يعمل، لكن تشغيله ثلاث مرات في الثانية ليس على الأرجح ما تريده. فواجهات المستخدم الشفافة، والبيئات الملونة، والانفجارات، وحتى المشاهد السينمائية يمكن أن تتسبب في تفعيل خاطئ أو متسارع لعدّاداتك. وسيظل هذا تحديًا دائمًا. ومن الحلول البسيطة استخدام صنف Meter، كما هو موضح في القسم التالي، المقتطفات.