Structured Emulator Telemetry کے ساتھ TypeSafe Jev سے Super Mario Bros. کنٹرول کریں

TypeSafe Mario کیا کرتا ہے

TypeSafe Mario ایک تجرباتی کنٹرولر ہے جو TypeSafe کے Jev ماڈل کو اصل Super Mario Bros. کے لیے کنٹرولر ان پٹس منتخب کرنے دیتا ہے۔ اسکرین شاٹس موصول کرنے کے بجائے ماڈل کو ایمولیٹر ٹیلی میٹری اور RAM سے اخذ کردہ مختصر، آبجیکٹ پر مبنی JSON موصول ہوتا ہے۔

کنٹرول لوپ کا ڈھانچہ یہ ہے:

NES emulator -> telemetry/RAM parser -> structured JSON -> Jev Choice -> controller input

Jev کے قانونی ایکشن منتخب کرنے کے بعد ایمولیٹر کئی فریم آگے بڑھتا ہے اور نئی حالت تیار کرتا ہے۔ یہ عمل پورے ایپی سوڈ کے دوران دہرایا جاتا ہے۔ خام مقامی ٹائل گرڈ ڈیبگ لاگز اور ڈیش بورڈ میں دستیاب رہتا ہے، لیکن ماڈل کو بھیجے جانے والے ان پٹ میں اسے دوبارہ شامل نہیں کیا جاتا۔

دستیاب کنٹرولر ایکشنز

ابتدائی ایکشن اسپیس کو جان بوجھ کر سات کنٹرولر میکروز تک محدود رکھا گیا ہے:

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

اہم خصوصیات

• منظم ماڈل ان پٹ: پارسر TypeSafe کو فلیٹ تحریر یا اسکرین شاٹس کے بجائے بامعنی JSON آبجیکٹس بھیجتا ہے۔
• متعدد فیصلے: ہر درخواست کنٹرولر کے انتخاب، آگے چھلانگ لگانے کی افادیت، اور فوری خطرے کا جائزہ لیتی ہے۔
• ردعمل کے وقت کی پیمائش: حالت میں ایکشن کا دورانیہ اور مشاہدے سے ایکشن تک کا وقفہ شامل ہوتا ہے۔
• لائیو ڈیش بورڈ: طے شدہ ڈسپلے گیم پلے کو ایکشن کے امکانات، اعتماد، تاخیر، خطرے، انعام، اور پارس شدہ حالت کے ساتھ دکھاتا ہے۔
• تفصیلی رَن ریکارڈز: ہر فیصلہ بعد کے تجزیے یا ویژولائزیشن کے لیے JSON Lines ریکارڈ کے طور پر محفوظ کیا جاتا ہے۔
• ڈیبگ کی سہولت: انسانی فہم کے قابل حالت کی تحریر اور مقامی ٹائل گرڈ معائنے کے لیے دستیاب رہتے ہیں۔

تقاضے اور قانونی سیٹ اپ

پروجیکٹ انسٹال کرنے سے پہلے یقینی بنائیں کہ آپ کا ماحول ان تقاضوں پر پورا اترتا ہے:

• Python 3.13 یا اس کے بعد کا ورژن
• TYPESAFE_API_KEY میں محفوظ TypeSafe API key
• Super Mario Bros. کے لیے قانونی مقامی سیٹ اپ

ریپوزٹری میں Nintendo ROM یا دیگر کاپی رائٹ شدہ گیم ڈیٹا شامل نہیں ہے۔ اپنے ایمولیٹر اور گیم فائلز قانونی طور پر حاصل کرنا اور استعمال کرنا آپ کی ذمہ داری ہے۔

انسٹالیشن

README میں ورچوئل ماحول بنانے، Mario اور ڈیولپمنٹ کی dependencies انسٹال کرنے، اور API key ترتیب دینے کے لیے PowerShell کمانڈز فراہم کی گئی ہیں۔

1. Python 3.13 کا ورچوئل ماحول بنائیں۔
2. ضروری extras کے ساتھ پروجیکٹ کو editable mode میں انسٹال کریں۔
3. موجودہ PowerShell سیشن کے لیے TypeSafe API key سیٹ کریں۔

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

your-key کو اپنی اصل TypeSafe API key سے تبدیل کریں۔ چونکہ یہ کمانڈ PowerShell کا environment variable سیٹ کرتی ہے، اس لیے بعد کی کمانڈز اسی ترتیب دیے گئے ماحول سے چلائیں، الا یہ کہ آپ variable کو الگ سے مستقل محفوظ کر دیں۔

پہلے ماڈل ان پٹ کا معائنہ کریں

گیم شروع کرنے سے پہلے state-demo استعمال کر کے وہ عین JSON اور تحریر دیکھیں جو پروجیکٹ TypeSafe کو بھیجے گا:

.venv\Scripts\typesafe-mario state-demo

یہ کمانڈ گیم شروع نہیں کرتی اور API کو کال نہیں کرتی۔ یہ ماڈل کو بھیجے جانے والے schema کو سمجھنے اور ایمولیٹر کے مشاہدات کی نمائندگی کی تصدیق کرنے کا محفوظ ترین طریقہ ہے۔

منظم حالت کو سمجھنا

معیاری آبجیکٹ مشاہدات کو ان کے مقصد کے مطابق گروپ کرتا ہے:

• player: پوزیشن، رفتار، زمین پر ہونے کی حالت، چھلانگ کا مرحلہ، اور power-up۔
• trajectory: ہوا میں رہنے کا وقت، ٹیک آف کے بعد طے کیا گیا فاصلہ، اور آیا Mario کسی خلا کو پار کرنے کے لیے پابند ہو چکا ہے۔
• hazard: زیادہ سے زیادہ تین دشمن، ان کی متوقع پوزیشنیں، ممکنہ ٹکراؤ کا وقت، اور ٹیک آف کی آخری مہلت۔
• terrain: رکاوٹ اور خلا کی جیومیٹری، مشاہدے کی قابلِ اعتمادیت، اور آخری بار زمین پر ہونے کا پیشگی جائزہ۔
• reaction_timing: کنٹرولر ایکشن کا دورانیہ اور مشاہدے سے ایکشن تک کی پیمائش شدہ تاخیر۔
• recent_control: پچھلا ایکشن، اس کا دورانیہ، حاصل کی گئی پیش رفت، اور مشاہدہ شدہ نتیجہ۔
• episode: زندگیاں، گھڑی، پیش رفت، رکاوٹیں، موت کی حالت، اور لیول کی تکمیل۔

منظم JSON ماڈل کی معیاری حالت ہے۔ مکمل تحریری رینڈرنگ صرف ڈیبگنگ اور صارف انٹرفیس کے لیے موجود ہے۔ ڈیبگ اسنیپ شاٹ میں Mario کے نقاط اور حرکت، ایپی سوڈ کی پیش رفت، قریبی دشمن، اور حروف پر مبنی مقامی ٹائل گرڈ شامل ہو سکتے ہیں۔

World 1-1 چلائیں

World 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 پر کلک کریں۔ Mario کے مرنے یا لیول مکمل کرنے کے بعد بھی ڈیش بورڈ کھلا رہتا ہے۔ باہر نکلنے کے لیے 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 کا نتیجہ Mario کو کنٹرول کرتا ہے، جبکہ چھلانگ کا اندازہ اور خطرے کا اسکور اضافی تشریح اور بصری معلومات فراہم کرتے ہیں۔

درست وقت کے حسابات کوڈ میں ہی رہتے ہیں۔ مثال کے طور پر، پارسر جواب کی عمر، دشمن کی حرکت، ایکشن کی رفتار، اور چھلانگ سے صاف گزرنے کے وقت کو ملا کر ایک ٹائپ شدہ jump_must_start_this_decision حقیقت بناتا ہے۔ Jev اس حقیقت کی تشریح کرتا ہے اور کنٹرولر کے انتخاب کی ذمہ داری اسی کے پاس رہتی ہے؛ ہارنس کسی اسکرپٹ شدہ بحالی ایکشن کو اوور رائڈ کے طور پر لاگو نہیں کرتا۔

ریکارڈ شدہ فیصلوں کا معائنہ کریں

ہر فیصلہ ٹائم اسٹیمپ والی JSON Lines فائل میں لکھا جاتا ہے:

artifacts/run-<timestamp>.jsonl

ریکارڈز میں شامل ہیں:

• Jev کی تاخیر
• ایکشن کے امکانات
• اعتماد
• ماڈل کی کینونیکل حالت
• خام ڈیبگ حالت
• گیم کا نتیجہ

یہ ریکارڈز اجرا کے بعد رن کا معائنہ کرنے کے لیے درکار ڈیٹا فراہم کرتے ہیں۔ انہیں لائیو اوورلے یا رینڈر کردہ سوشل کلپ کے لیے ان پٹ کے طور پر بھی استعمال کیا جا سکتا ہے۔

اعلیٰ درجے کے استعمال کے نکات

گیم پلے سے پہلے مشاہدات کی توثیق کریں

جب آپ ایمولیٹر شروع کیے یا API کال استعمال کیے بغیر ماڈل کے لیے پیش کی جانے والی نمائندگی کا جائزہ لینا چاہیں تو لائیو سیشن سے پہلے state-demo چلائیں۔ کینونیکل ساختی حالت اور انسانوں کے لیے تیار کردہ ڈیبگ متن کے درمیان فرق پر خاص توجہ دیں۔

ٹائمنگ کی حقیقتوں کو ایکشن کی رفتار کے ساتھ سمجھیں

کنٹرولر متعدد فریموں کے وقفوں میں کام کرتا ہے، اس لیے ردِعمل کا وقت بیرونی مفروضے کے بجائے حالت کا حصہ ہے۔ کسی فیصلے کا جائزہ لیتے وقت منتخب ایکشن کا موازنہ جواب کی تاخیر، ایکشن کے دورانیے، متوقع دشمن کے رابطے، اور پارسر کی جانب سے بتائی گئی کسی بھی ٹیک آف کی آخری مہلت سے کریں۔

کام کے مطابق ڈسپلے استعمال کریں

• ماڈل کے استدلالی اشاروں اور گیم پلے کا ایک ساتھ معائنہ کرنے کے لیے ڈیفالٹ ڈیش بورڈ استعمال کریں۔
• جب صرف ایمولیٹر کا آؤٹ پٹ درکار ہو تو --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 آرٹیفیکٹس استعمال کر کے سمجھیں کہ حالت، ٹائمنگ، اعتماد، اور نتائج آپس میں کیسے مربوط ہیں۔