تحكّم فـ Super Mario Bros. باستعمال TypeSafe Jev وتليمترية منظّمة ديال المحاكي

شنو كيدير TypeSafe Mario

TypeSafe Mario هو متحكّم تجريبي كيخلّي موديل Jev ديال TypeSafe يختار مدخلات المتحكّم للعبة Super Mario Bros. الأصلية. عوض ما يتوصل الموديل بلقطات الشاشة، كيتوصل ببيانات JSON مختصرة ومركّزة على الكائنات، مستخرجة من معطيات المحاكي وذاكرة RAM.

حلقة التحكّم خدامة بهاد البنية:

محاكي NES -> محلّل المعطيات/RAM -> JSON منظّم -> اختيار Jev -> مدخلة المتحكّم

من بعد ما كيختار Jev إجراء قانوني، كيتقدّم المحاكي بعدّة إطارات وكيولّد حالة جديدة. كتعاود هاد العملية طوال الحلقة. شبكة البلاطات المحلية الخام كتبقى متوفّرة فالسجلات ديال تصحيح الأخطاء ولوحة المراقبة، ولكن ما كتتعاودش فالمعطيات الموجّهة للموديل.

إجراءات المتحكّم المتوفّرة

مجال الإجراءات الأول محدود عمداً فسبعة اختصارات ديال المتحكّم:

• noop
• right
• right_jump
• right_run
• right_run_jump
• jump
• left

الخصائص الرئيسية

• مدخلات منظّمة للموديل: المحلّل كيبعث لـ TypeSafe كائنات JSON مفهومة، عوض نص نثري مسطّح ولا لقطات الشاشة.
• أحكام متعدّدة: كل طلب كيقيّم اختيار المتحكّم، وفائدة القفز للأمام، والخطر المباشر.
• توقيت ردّ الفعل مقاس: الحالة كتضم مدة الإجراء والتأخير بين الملاحظة والإجراء.
• لوحة مراقبة مباشرة: العرض الافتراضي كيجمع اللعب مع احتمالات الإجراءات، والثقة، ووقت الاستجابة، والخطر، والمكافأة، والحالة المحلّلة.
• سجلات مفصّلة للجولات: كل قرار كيتحفظ كسجل بصيغة JSON Lines للتحليل أو التصوير من بعد.
• وضوح فالتصحيح: النص المقروء ديال الحالة وشبكة البلاطات المحلية كيبقاو متوفّرين للفحص.

المتطلبات والإعداد القانوني

قبل تثبيت المشروع، تأكّد بلي البيئة ديالك كتستوفي هاد المتطلبات:

• Python 3.13 ولا أحدث
• مفتاح API ديال TypeSafe مخزّن فـ TYPESAFE_API_KEY
• إعداد محلي قانوني للعبة Super Mario Bros.

المستودع ما فيهش ROM ديال Nintendo ولا أي معطيات أخرى محمية بحقوق الطبع والنشر. نتا مسؤول على الحصول على ملفات المحاكي واللعبة واستعمالها بطريقة قانونية.

التثبيت

ملف README كيوفّر أوامر PowerShell لإنشاء بيئة افتراضية، وتثبيت اعتماديات Mario والتطوير، وإعداد مفتاح API.

1. أنشئ بيئة افتراضية ديال Python 3.13.
2. ثبّت المشروع فالوضع القابل للتعديل مع الإضافات المطلوبة.
3. عيّن مفتاح API ديال TypeSafe لجلسة PowerShell الحالية.

py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY = "your-key"

عوّض your-key بمفتاح API الحقيقي ديالك ديال TypeSafe. حيث الأمر كيعيّن متغيّر بيئة ديال PowerShell، نفّذ الأوامر الموالية من نفس البيئة المهيّأة، إلا إلا حفظتي المتغيّر بطريقة منفصلة.

عاين مدخلات الموديل أولاً

قبل ما تشغّل اللعبة، استعمل state-demo باش تعاين JSON والنص بالضبط اللي غادي يبعثهم المشروع لـ TypeSafe:

.venv\Scripts\typesafe-mario state-demo

هاد الأمر ما كيشغّلش اللعبة وما كيتاصلش بـ API. هادي هي الطريقة الأكثر أماناً باش تفهم المخطط الموجّه للموديل وتتأكّد كيفاش كتمثّل ملاحظات المحاكي.

فهم الحالة المنظّمة

الكائن الأساسي كيجمع الملاحظات حسب الغرض ديالها:

• player: الموقع، والسرعة، وحالة ملامسة الأرض، ومرحلة القفز، وزيادة القوة.
• trajectory: مدة البقاء فالهواء، والمسافة من وقت الإقلاع، وواش ماريو ملتازم بعبور فجوة.
• hazard: حتى لثلاثة ديال الأعداء، والمواقع المتوقّعة ديالهم، ووقت التلامس المتوقّع، وآخر أجل للإقلاع.
• terrain: هندسة العوائق والفجوات، وموثوقية الملاحظة، وآخر معاينة من وقت ملامسة الأرض.
• reaction_timing: مدة إجراء المتحكّم والتأخير المقاس بين الملاحظة والإجراء.
• recent_control: الإجراء السابق، ومدتو، والتقدّم اللي تحقق، والنتيجة الملاحظة.
• episode: الأرواح، والوقت، والتقدّم، وحالات التوقّف، وحالة الموت، وإكمال المستوى.

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

شغّل العالم 1-1

بدا بيئة العالم 1-1 وخلي Jev يختار إجراء كل ثمان خطوات ديال المحاكي:

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8

الخيار --env كيحدّد البيئة، بينما --frames-per-decision 8 كيحدّد شحال من خطوة ديال المحاكي كتدوز بين قرارات الموديل. مع العرض الافتراضي، المشروع كيفتح نافذة وحدة قابلة للتسجيل فيها اللعب المباشر ومعطيات الموديل بجوج.

استعمل لوحة المراقبة

لوحة المراقبة كتعرض المعلومات اللي خاصّة لمتابعة سلوك Jev:

• إجراء المتحكّم المختار
• التوزيع الكامل لاحتمالات Choice
• ثقة الموديل
• وقت استجابة طلب Jev
• احتمال القفز للأمام
• نقطة الخطر المباشر
• المكافأة
• حالة اللعبة المحلّلة

ضغط على R ولا كليكي على Restart باش تبدا حلقة جديدة. لوحة القيادة كتبقى محلولة من بعد ما كيموت ماريو ولا كيكمل المستوى. ضغط على Esc ولا Q باش تخرج.

ختار نمط العرض

لوحة القيادة المدموجة الافتراضية مفيدة ملي كتراقب ولا كتسجل جولة. كاينين جوج أنماط إضافية لاستعمالات أضيق.

بيّن غير المحاكي

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display game

نمط العرض game كيبين غير نافذة المحاكي.

شغّل بلا عرض

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display none

نمط العرض none كيشغل بلا واجهة، ومخصص للتنفيذ على طريقة الاختبارات المعيارية.

فهم الأحكام الثلاثة ديال TypeSafe

كل طلب كيقيم ثلاثة ديال الأحكام المستقلة على نفس الحالة المنظمة:

• Choice: كيختار الماكرو القانوني الجاي ديال المتحكم.
• Noul: كيقدّر واش القفزة للقدّام مفيدة فهاد اللحظة.
• Score: كيقيس الخطر المباشر باش يستعملو العرض الحي.

هاد الأحكام عندها أدوار مختلفة. نتيجة Choice هي اللي كتتحكم فماريو، بينما تقدير القفز ونقطة الخطر كيعطيو تفسير وعرض إضافيين.

الحسابات الدقيقة ديال التوقيت باقية فالكود. مثلا، المحلل كيجمع عمر الاستجابة، حركة العدو، وتيرة الأفعال، ومدة تصفية القفزة فحقيقة typed سميتها jump_must_start_this_decision. Jev كيفسر هاد الحقيقة وكيبقى هو المسؤول على اختيار المتحكم؛ والـ harness ما كيطبقش تجاوزا مبرمجا لفعل الاسترجاع.

فحص القرارات المسجلة

كل قرار كيتكتب فملف JSON Lines فيه طابع زمني:

artifacts/run-<timestamp>.jsonl

السجلات فيها:

• المدة ديال استجابة Jev
• احتمالات الأفعال
• الثقة
• الحالة الكانونية ديال النموذج
• الحالة الخام ديال التصحيح
• نتيجة اللعبة

هاد السجلات كتوفر المعطيات اللازمة لفحص الجولة من بعد التنفيذ. وتقدر حتى تكون مدخلا لطبقة عرض حية ولا لمقطع اجتماعي مرندر.

نصائح للاستعمال المتقدم

تحقق من الملاحظات قبل اللعب

شغّل state-demo قبل الجلسة الحية ملي بغيتي تراجع التمثيل اللي كيشوفو النموذج بلا ما تبدا المحاكي ولا تستهلك طلب API. ركز بالخصوص على الفرق بين الحالة المنظمة الكانونية ونص التصحيح الموجه للبشر.

فسّر حقائق التوقيت مع وتيرة الأفعال

المتحكم كيتصرف على فترات فيها عدة إطارات، لذلك توقيت التفاعل جزء من الحالة وماشي افتراض خارجي. ملي كتراجع قرارا، قارن الفعل المختار مع تأخر الاستجابة، مدة الفعل، ملامسة العدو المتوقعة، وأي أجل للإقلاع كيبلغ عليه المحلل.

استعمل العرض المناسب للمهمة

• استعمل لوحة القيادة الافتراضية ملي بغيتي تفحص إشارات استدلال النموذج واللعب بجوج.
• استعمل --display game ملي غير خرج المحاكي هو اللي محتاج.
• استعمل --display none لجولات الاختبار المعياري بلا واجهة.

حلل توزيع الاحتمالات كامل

ما تحصرش التحليل فالفعل المختار. لوحة القيادة وملفات JSONL فيهم توزيع احتمالات Choice كامل والثقة، وهاد الشي يقدر يبين واش Jev كان كيميل بقوة لفعل واحد ولا اختار بين عدة بدائل عندها أوزان متقاربة.

شغّل فحوصات التطوير

المستودع فيه أوامر التنسيق، والفحص، والاختبارات للمساهمين. شغّلهم من البيئة الافتراضية المهيأة:

.venv\Scripts\ruff format --check src tests
.venv\Scripts\ruff check src tests
.venv\Scripts\python -m pytest -q

الأمر الأول كيتحقق من التنسيق، والثاني كيشغل فحوصات Ruff الخاصة بالكود، والثالث كينفذ مجموعة الاختبارات بإخراج مختصر.

الخلاصة

TypeSafe Mario كيبين بديلا منظما للتحكم فاللعبة اعتمادا على لقطات الشاشة. كيحوّل معطيات المحاكي وRAM إلى JSON كانوني متمحور حول الكائنات، وكيطلب من Jev يختار من مجموعة صغيرة ديال الأفعال القانونية، وكيخزن كل قرار للفحص الحي ولا للتحليل من بعد. بدا بـ state-demo، لعب World 1-1 من خلال لوحة القيادة، واستعمل ملفات JSONL اللي تخرجات باش تفهم العلاقة بين الحالة، والتوقيت، والثقة، والنتائج.