Super Mario Bros.ni TypeSafe Jev va tizimli emulyator telemetriyasi yordamida boshqaring

TypeSafe Mario nima qiladi

TypeSafe Mario — TypeSafe’ning Jev modeli original Super Mario Bros. o‘yini uchun boshqaruv kiritmalarini tanlashiga imkon beruvchi eksperimental kontroller. Model skrinshotlar o‘rniga emulator telemetriyasi va RAM ma’lumotlaridan olingan ixcham, obyektga yo‘naltirilgan JSON ma’lumotlarini qabul qiladi.

Boshqaruv sikli quyidagi arxitekturaga asoslanadi:

NES emulatori -> telemetriya/RAM parseri -> strukturaviy JSON -> Jev Choice -> kontroller kiritmasi

Jev qonuniy amalni tanlagach, emulator bir nechta kadrni o‘tkazadi va yangi holatni yaratadi. Bu jarayon epizod davomida takrorlanadi. Xom lokal plitkalar panjarasi debug jurnallari va boshqaruv panelida mavjud bo‘lib qoladi, ammo modelga yuboriladigan kiritmada takrorlanmaydi.

Mavjud kontroller amallari

Dastlabki amallar maydoni ataylab yettita kontroller makrosi bilan cheklangan:

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

Asosiy imkoniyatlar

• Strukturaviy model kiritmasi: Parser TypeSafe’ga tekislangan matn yoki skrinshotlar o‘rniga mazmunli JSON obyektlarini yuboradi.
• Bir nechta baholash: Har bir so‘rov kontroller tanlovini, oldinga sakrash foydaliligini va bevosita xavfni baholaydi.
• O‘lchangan reaksiya vaqti: Holat amal davomiyligi va kuzatuvdan amal bajarilishigacha bo‘lgan kechikishni o‘z ichiga oladi.
• Jonli boshqaruv paneli: Standart ko‘rinish o‘yinni amal ehtimollari, ishonch darajasi, kechikish, xavf, mukofot va tahlil qilingan holat bilan birlashtiradi.
• Batafsil ish yozuvlari: Har bir qaror keyinchalik tahlil qilish yoki vizualizatsiya qilish uchun JSON Lines yozuvi sifatida saqlanadi.
• Debug ko‘rinuvchanligi: Odam o‘qiy oladigan holat matni va lokal plitkalar panjarasi tekshirish uchun mavjud bo‘lib qoladi.

Talablar va qonuniy sozlash

Loyihani o‘rnatishdan oldin muhitingiz quyidagi talablarga javob berishiga ishonch hosil qiling:

• Python 3.13 yoki undan yangiroq versiya
• TYPESAFE_API_KEYda saqlangan TypeSafe API kaliti
• Super Mario Bros. uchun qonuniy mahalliy sozlama

Repozitoriy Nintendo ROM fayli yoki boshqa mualliflik huquqi bilan himoyalangan o‘yin ma’lumotlarini o‘z ichiga olmaydi. Emulator va o‘yin fayllarini qonuniy ravishda olish hamda ulardan foydalanish uchun javobgarsiz.

O‘rnatish

README virtual muhit yaratish, Mario va ishlab chiqish bog‘liqliklarini o‘rnatish hamda API kalitini sozlash uchun PowerShell buyruqlarini taqdim etadi.

1. Python 3.13 virtual muhitini yarating.
2. Loyihani zarur qo‘shimchalar bilan tahrirlanadigan rejimda o‘rnating.
3. Joriy PowerShell sessiyasi uchun TypeSafe API kalitini sozlang.

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

your-key o‘rniga haqiqiy TypeSafe API kalitingizni kiriting. Buyruq PowerShell muhit o‘zgaruvchisini o‘rnatgani sababli, o‘zgaruvchini alohida saqlamasangiz, keyingi buyruqlarni ayni sozlangan muhitdan ishga tushiring.

Avval model kiritmasini tekshiring

O‘yinni ishga tushirishdan oldin loyiha TypeSafe’ga yuboradigan aniq JSON va matnni ko‘rish uchun state-demo buyrug‘idan foydalaning:

.venv\Scripts\typesafe-mario state-demo

Bu buyruq o‘yinni ishga tushirmaydi va API’ga murojaat qilmaydi. U modelga yuboriladigan sxemani tushunish va emulator kuzatuvlari qanday ifodalanishini tekshirishning eng xavfsiz usulidir.

Strukturaviy holatni tushunish

Kanonik obyekt kuzatuvlarni maqsadiga ko‘ra guruhlaydi:

• player: Joylashuv, tezlik, yerda turganlik holati, sakrash bosqichi va kuchaytirgich.
• trajectory: Havoda bo‘lish vaqti, sakrashdan beri bosib o‘tilgan masofa va Mario bo‘shliqdan o‘tishga qat’iy kirishgan-kirmagani.
• hazard: Uchtagacha dushman, ularning prognoz qilingan joylashuvi, kutilayotgan to‘qnashuv vaqti va sakrashni boshlashning oxirgi muddati.
• terrain: To‘siq va bo‘shliq geometriyasi, kuzatuv ishonchliligi hamda yerda turgan paytdagi so‘nggi ko‘rinish.
• reaction_timing: Kontroller amalining davomiyligi va kuzatuvdan amal bajarilishigacha o‘lchangan kechikish.
• recent_control: Oldingi amal, uning davomiyligi, erishilgan siljish va kuzatilgan natija.
• episode: Jonlar, vaqt hisoblagichi, siljish, to‘xtab qolishlar, o‘lim holati va bosqich yakunlanganligi.

Strukturaviy JSON kanonik model holatidir. Kengroq matnli ko‘rinish faqat debug va foydalanuvchi interfeysi uchun mavjud. Debug surati Mario koordinatalari va harakatini, epizod siljishini, yaqin atrofdagi dushmanlarni hamda belgilar asosidagi lokal plitkalar panjarasini o‘z ichiga olishi mumkin.

World 1-1 ni ishga tushirish

World 1-1 muhitini ishga tushiring va Jev har sakkizta emulator qadamida amal tanlashiga imkon bering:

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

--env parametri muhitni tanlaydi, --frames-per-decision 8 esa model qarorlari orasida nechta emulator qadami bajarilishini belgilaydi. Standart ko‘rinishda loyiha jonli o‘yin va model telemetriyasini o‘z ichiga olgan, yozib olish mumkin bo‘lgan bitta oynani ochadi.

Boshqaruv panelidan foydalanish

Boshqaruv paneli Jev xatti-harakatini kuzatish uchun zarur ma’lumotlarni taqdim etadi:

• Tanlangan kontroller amali
• Choice ehtimollarining to‘liq taqsimoti
• Model ishonchi
• Jev so‘rovi kechikishi
• Oldinga sakrash ehtimoli
• Bevosita xavf ko‘rsatkichi
• Mukofot
• Tahlil qilingan o‘yin holati

Yangi epizodni boshlash uchun R tugmasini bosing yoki Restart tugmasini bosing. Mario halok bo‘lganidan yoki bosqichni yakunlaganidan keyin ham boshqaruv paneli ochiq qoladi. Chiqish uchun Esc yoki Q tugmasini bosing.

Ko‘rsatish rejimini tanlang

Standart birlashtirilgan boshqaruv paneli jarayonni kuzatish yoki yozib olishda foydalidir. Yana ikkita rejim torroq foydalanish holatlarini qo‘llab-quvvatlaydi.

Faqat emulyatorni ko‘rsatish

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

game ko‘rsatish rejimida faqat emulyator oynasi ko‘rsatiladi.

Ko‘rsatishsiz ishga tushirish

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

none ko‘rsatish rejimi ekransiz ishlaydi va benchmark uslubidagi bajarish uchun mo‘ljallangan.

TypeSafe’ning uchta xulosasini tushunish

Har bir so‘rov bir xil tuzilgan holat asosida uchta mustaqil xulosani baholaydi:

• Choice: Keyingi qonuniy boshqaruv makrosini tanlaydi.
• Noul: Ayni vaqtda oldinga sakrash foydali yoki foydasizligini baholaydi.
• Score: Jonli vizualizatsiya uchun darhol yuzaga keladigan xavfni o‘lchaydi.

Bu xulosalarning vazifalari turlicha. Choice natijasi Marioni boshqaradi, sakrash bahosi va xavf balli esa qo‘shimcha talqin hamda vizualizatsiyani ta’minlaydi.

Aniq vaqt hisob-kitoblari kodda qoladi. Masalan, parser javob yoshi, dushman harakati, amal chastotasi va sakrashni xavfsiz yakunlash vaqtini birlashtirib, tiplangan jump_must_start_this_decision faktini hosil qiladi. Jev bu faktni talqin qiladi va boshqaruv tanlovi uchun javobgar bo‘lib qoladi; harness esa oldindan yozilgan tiklanish amalini majburan qo‘llamaydi.

Yozib olingan qarorlarni tekshirish

Har bir qaror vaqt belgisi qo‘yilgan JSON Lines fayliga yoziladi:

artifacts/run-<timestamp>.jsonl

Yozuvlar quyidagilarni o‘z ichiga oladi:

• Jev kechikishi
• Amallar ehtimollari
• Ishonchlilik
• Kanonik model holati
• Xom disk raskadrovka holati
• O‘yin natijasi

Bu yozuvlar bajarilgandan keyin jarayonni tekshirish uchun zarur ma’lumotlarni beradi. Ular jonli overlay yoki ijtimoiy tarmoqlar uchun tayyorlangan videoklipga asos bo‘lishi ham mumkin.

Ilg‘or foydalanish bo‘yicha maslahatlar

O‘yin jarayonidan oldin kuzatuvlarni tekshiring

Emulyatorni ishga tushirmasdan yoki API chaqiruvini sarflamasdan modelga taqdim etiladigan ko‘rinishni ko‘rib chiqmoqchi bo‘lsangiz, jonli sessiyadan oldin state-demo buyrug‘ini bajaring. Kanonik tuzilgan holat bilan insonga mo‘ljallangan disk raskadrovka matni o‘rtasidagi farqqa alohida e’tibor bering.

Vaqt faktlarini amal chastotasi bilan birga talqin qiling

Boshqaruv moduli ko‘p kadrli intervallarda ishlaydi, shuning uchun reaksiya vaqti tashqi taxmin emas, balki holatning bir qismidir. Qarorni ko‘rib chiqayotganda tanlangan amalni javob kechikishi, amal davomiyligi, dushman bilan kutilayotgan to‘qnashuv va parser xabar qilgan har qanday sakrash boshlanishi muddati bilan solishtiring.

Vazifa uchun mos ko‘rsatish rejimidan foydalaning

• Model mulohazalari signallari va o‘yin jarayonini birgalikda tekshirishda standart boshqaruv panelidan foydalaning.
• Faqat emulyator chiqishi kerak bo‘lsa, --display game parametridan foydalaning.
• Ekransiz benchmark ishga tushirishlari uchun --display none parametridan foydalaning.

To‘liq ehtimollar taqsimotini tahlil qiling

Tahlilni faqat tanlangan amal bilan cheklamang. Boshqaruv paneli va JSONL artefaktlari to‘liq Choice ehtimollar taqsimoti hamda ishonchlilikni o‘z ichiga oladi. Bu Jev bitta amalni qat’iy afzal ko‘rganmi yoki og‘irliklari o‘xshash bir nechta variant orasidan tanlaganmi, shuni aniqlashga yordam beradi.

Ishlab chiqish tekshiruvlarini bajaring

Repozitoriyda hissa qo‘shuvchilar uchun formatlash, lint va test buyruqlari mavjud. Ularni sozlangan virtual muhitdan ishga tushiring:

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

Birinchi buyruq formatlashni tekshiradi, ikkinchisi Ruff lint tekshiruvlarini bajaradi, uchinchisi esa testlar to‘plamini qisqa chiqish bilan ishga tushiradi.

Xulosa

TypeSafe Mario skrinshotlar asosida o‘yinni boshqarishga tuzilgan muqobil yondashuvni namoyish etadi. U emulyator telemetriyasi va RAM ma’lumotlarini kanonik, obyektga yo‘naltirilgan JSON formatiga o‘giradi, Jevdan ixcham qonuniy amallar to‘plamidan birini tanlashni so‘raydi va jonli tekshiruv yoki keyingi tahlil uchun har bir qarorni yozib boradi. state-demo buyrug‘idan boshlang, boshqaruv paneli orqali 1-1-dunyoni ishga tushiring va holat, vaqt, ishonchlilik hamda natijalar o‘rtasidagi bog‘liqlikni tushunish uchun yaratilgan JSONL artefaktlaridan foydalaning.