Lawula i-Super Mario Bros. nge-TypeSafe Jev kanye Nedatha Ehlekile Ye-Emulator

Okungenziwa yi-TypeSafe Mario

I-TypeSafe Mario iyisilawuli sokuhlola esivumela imodeli ye-Jev ye-TypeSafe ukuthi ikhethe okokufaka kwesilawuli komdlalo wokuqala we-Super Mario Bros. Esikhundleni sokuthola izithombe-skrini, imodeli ithola i-JSON emfushane egxile ezintweni, ethathwe kudatha ye-emulator ne-RAM.

Iluphu yokulawula ilandela lesi sakhiwo:

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

Ngemva kokuba u-Jev ekhethe isenzo esisemthethweni, i-emulator iqhubekisela phambili amafreyimu ambalwa bese ikhiqiza isimo esisha. Le nqubo iyaphindwa kuyo yonke i-episode. Igridi yamathayela yasendaweni eluhlaza iyatholakala kumalogi okulungisa amaphutha nakudeshibhodi, kodwa ayiphindwa kokokufaka okuqondiswe kumodeli.

Izinsi zokulawula ezitholakalayo

Isikhala sezenzo sokuqala sinqunyelwe ngamabomu kuma-macro okulawula ayisikhombisa:

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

Izici Eziyinhloko

• Okokufaka kwemodeli okuhlelekile: I-parser ithumela ku-TypeSafe izinto ze-JSON ezinencazelo, esikhundleni sombhalo oyisicaba noma izithombe-skrini.
• Ukuhlola okuningi: Isicelo ngasinye sihlola ukukhetha kwesilawuli, usizo lokugxuma uye phambili, kanye nobungozi obusheshayo.
• Isikhathi sokusabela esilinganisiwe: Isimo sihlanganisa ubude besenzo nokubambezeleka phakathi kokubona nokwenza isenzo.
• Ideshibhodi ebukhoma: Isibonisi esizenzakalelayo sihlanganisa umdlalo namathuba ezenzo, ukuzethemba, ukubambezeleka, ubungozi, umvuzo, kanye nesimo esihlaziyiwe.
• Amarekhodi anemininingwane okusebenza: Isinqumo ngasinye sigcinwa njengerekhodi le-JSON Lines ukuze sihlaziywe noma siboniswe kamuva.
• Ukubonakala kokulungisa amaphutha: Umbhalo wesimo ofundeka ngabantu kanye negridi yamathayela yasendaweni kusatholakala ukuze kuhlolwe.

Izidingo Nokumiswa Okusemthethweni

Ngaphambi kokufaka iphrojekthi, qinisekisa ukuthi indawo yakho ihlangabezana nalezi zidingo:

• Python 3.13 noma entsha
• Ukhiye we-TypeSafe API ogcinwe ku-TYPESAFE_API_KEY
• Ukusethwa kwasendaweni okusemthethweni kwe-Super Mario Bros.

Indawo yokugcina ikhodi ayinayo i-ROM ye-Nintendo noma enye idatha yomdlalo evikelwe yilungelo lobunikazi. Unesibopho sokuthola nokusebenzisa i-emulator namafayela omdlalo wakho ngokusemthethweni.

Ukufaka

I-README inikeza imiyalo ye-PowerShell yokwakha indawo ebonakalayo, ukufaka okuncikile ku-Mario nokuthuthukisa, kanye nokumisa ukhiye we-API.

1. Yakha indawo ebonakalayo ye-Python 3.13.
2. Faka iphrojekthi ngemodi ehlelekayo kanye nezinto ezengeziwe ezidingekayo.
3. Setha ukhiye we-TypeSafe API weseshini yamanje ye-PowerShell.

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

Faka esikhundleni se-your-key ukhiye wakho wangempela we-TypeSafe API. Njengoba lo myalo usetha i-variable yemvelo ye-PowerShell, sebenzisa imiyalo elandelayo endaweni efanayo emisiwe ngaphandle kokuthi uyigcine ngokuhlukile.

Hlola Okokufaka Kwemodeli Kuqala

Ngaphambi kokuqalisa umdlalo, sebenzisa i-state-demo ukuze uhlole i-JSON nombhalo oqondile iphrojekthi ebingawuthumela ku-TypeSafe:

.venv\Scripts\typesafe-mario state-demo

Lo myalo awuqalisi umdlalo futhi awubizi i-API. Uyindlela ephephe kakhulu yokuqonda i-schema eqondiswe kumodeli nokuqinisekisa ukuthi ukubonwa kwe-emulator kumelelwa kanjani.

Ukuqonda isimo esihlelekile

Into eyisisekelo ihlanganisa ukubonwa ngokwenhloso yakho:

• player: Indawo, isivinini, isimo sokuma phansi, isigaba sokugxuma, kanye namandla akhethekile.
• trajectory: Isikhathi emoyeni, ibanga kusukela ekusukeni, nokuthi u-Mario uzibophezele yini ekuweleni igebe.
• hazard: Izitha ezingafika kwezintathu, izindawo zazo ezibikezelwe, isikhathi esilindelwe sokuthintana, kanye nomnqamulajuqu wokusuka.
• terrain: Ijiyomethri yezithiyo namagebe, ukwethembeka kokubona, kanye nokubuka kokugcina kokuma phansi.
• reaction_timing: Ubude besenzo sesilawuli kanye nokubambezeleka okulinganisiwe phakathi kokubona nokwenza isenzo.
• recent_control: Isenzo sangaphambilini, ubude baso, inqubekelaphambili etholakele, kanye nomphumela oboniwe.
• episode: Izimpilo, iwashi, inqubekelaphambili, ukuma isikhathi eside, isimo sokufa, kanye nokuqedwa kwezinga.

I-JSON ehlelekile iyisimo esisemthethweni semodeli. Ukumelwa kombhalo okugcwele kukhona kuphela ukulungisa amaphutha nesixhumi esibonakalayo somsebenzisi. Isifinyezo sokulungisa amaphutha singafaka izixhumanisi zika-Mario nokunyakaza kwakhe, inqubekelaphambili ye-episode, izitha eziseduze, kanye negridi yamathayela yasendaweni esekelwe kuzinhlamvu.

Qalisa i-World 1-1

Qalisa indawo ye-World 1-1 bese uvumela u-Jev ukuthi akhethe isenzo ngemva kwezinyathelo eziyisishiyagalombili ze-emulator:

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

Inketho ye---env ikhetha indawo, kanti i---frames-per-decision 8 inquma ukuthi zingaki izinyathelo ze-emulator ezenzekayo phakathi kwezinqumo zemodeli. Ngesibonisi esizenzakalelayo, iphrojekthi ivula iwindi elilodwa elingaqoshwa eliqukethe umdlalo obukhoma nedatha yokusebenza yemodeli.

Sebenzisa ideshibhodi

Ideshibhodi iveza ulwazi oludingekayo ukulandela ukuziphatha kuka-Jev:

• Isenzo sesilawuli esikhethiwe
• Ukusatshalaliswa okuphelele kwamathuba e-Choice
• Ukuzethemba kwemodeli
• Ukubambezeleka kwesicelo sika-Jev
• Amathuba okugxuma uye phambili
• Isikolo sobungozi obusheshayo
• Umvuzo
• Isimo somdlalo esihlaziyiwe

Cindezela u-R noma uchofoze u-Restart ukuze uqale isiqephu esisha. Ideshibhodi ihlala ivuliwe ngemva kokuba u-Mario eshonile noma eseqedile ileveli. Cindezela u-Esc noma u-Q ukuze uphume.

Khetha Imodi Yokubonisa

Ideshibhodi ezenzakalelayo ehlanganisiwe ilusizo lapho ubuka noma uqopha umdlalo. Amanye amamodi amabili asekela izimo zokusetshenziswa eziqondile.

Bonisa i-emulator kuphela

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

Imodi yokubonisa ye-game ibonisa iwindi le-emulator kuphela.

Qalisa ngaphandle kokubonisa

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

Imodi yokubonisa ye-none isebenza ngaphandle kwe-interface futhi yenzelwe ukuqaliswa okufana nokuhlolwa kokusebenza.

Qonda Izahlulelo Ezintathu ze-TypeSafe

Isicelo ngasinye sihlola izahlulelo ezintathu ezizimele phezu kwesimo esihlelekile esifanayo:

• Choice: Ikhetha i-macro yesilawuli elandelayo esemthethweni.
• Noul: Ilinganisela ukuthi ukugxuma okuya phambili kuyasiza yini ngaleso sikhathi.
• Score: Ikala ingozi esheshayo ukuze isetshenziswe ekuboniseni okubukhoma.

Lezi zahlulelo zinezindima ezihlukene. Umphumela we-Choice ulawula u-Mario, kuyilapho isilinganiso sokugxuma namaphuzu engcuphe kunikeza incazelo eyengeziwe nokubonisa.

Izibalo eziqondile zesikhathi zihlala kukhodi. Isibonelo, i-parser ihlanganisa ubudala bempendulo, ukunyakaza kwezitha, ijubane lezenzo, nesikhathi sokususa isithiyo ngokugxuma kube yiqiniso elinezinhlobo elithi jump_must_start_this_decision. U-Jev uhumusha lelo qiniso futhi usaphethe ukukhetha kwesilawuli; i-harness ayisebenzisi ukweqa okubhalwe kusengaphambili kwesenzo sokubuyisa.

Hlola Izinqumo Eziqoshiwe

Isinqumo ngasinye sibhalwa kufayela le-JSON Lines elinesitembu sesikhathi:

artifacts/run-<timestamp>.jsonl

Amarekhodi aqukethe:

• Ukubambezeleka kuka-Jev
• Amathuba ezenzo
• Ukuzethemba
• Isimo esisemthethweni semodeli
• Isimo esingahluziwe sokulungisa amaphutha
• Umphumela womdlalo

Lawa marekhodi ahlinzeka ngedatha edingekayo yokuhlola umdlalo ngemva kokuqaliswa. Angasetshenziswa futhi njengokufakwayo kwe-overlay ebukhoma noma kwekliphu yomphakathi ekhiqiziwe.

Amathiphu Okusebenzisa Okuthuthukile

Qinisekisa okubukwayo ngaphambi komdlalo

Qalisa i-state-demo ngaphambi kweseshini ebukhoma lapho ufuna ukubuyekeza ukumelwa okubhekene nemodeli ngaphandle kokuqala i-emulator noma ukusebenzisa ucingo lwe-API. Naka kakhulu umehluko phakathi kwesimo esihlelekile esisemthethweni nombhalo wokulungisa amaphutha ogxile kumuntu.

Humusha amaqiniso esikhathi kanye nejubane lesenzo

Isilawuli sisebenza ngezikhawu zamafreyimu amaningi, ngakho isikhathi sokusabela siyingxenye yesimo esikhundleni sokuba umcabango wangaphandle. Lapho ubuyekeza isinqumo, qhathanisa isenzo esikhethiwe nokubambezeleka kwempendulo, ubude besenzo, ukuthintana okulindelekile nesitha, kanye nanoma yimuphi umnqamulajuqu wokusuka obikwe yi-parser.

Sebenzisa ukubonisa okufanele umsebenzi

• Sebenzisa ideshibhodi ezenzakalelayo lapho uhlola amasignali okucabanga kwemodeli kanye nomdlalo ndawonye.
• Sebenzisa i---display game lapho kudingeka kuphela okukhiphayo kwe-emulator.
• Sebenzisa i---display none ekuhlolweni kokusebenza okungenayo i-interface.

Hlaziya ukusatshalaliswa okuphelele kwamathuba

Ungagcini ukuhlaziya esenzweni esikhethiwe kuphela. Ideshibhodi nezinto ze-JSONL zifaka ukusatshalaliswa okuphelele kwamathuba e-Choice kanye nokuzethemba, okungaveza ukuthi u-Jev wayethanda kakhulu isenzo esisodwa noma wakhetha phakathi kwezinye izindlela ezinesisindo esicishe sifane.

Qalisa Ukuhlolwa Kokuthuthukisa

Indawo yokugcina ikhodi inemiyalo yokufometha, yokuhlola ikhodi, neyokuhlola abanikeli. Yiqalise usuka endaweni ebonakalayo elungiselelwe:

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

Umyalo wokuqala uhlola ukufometha, owesibili usebenzisa ukuhlolwa kwe-lint kwe-Ruff, kanti owesithathu usebenzisa iqoqo lokuhlola ngokukhipha okufushane.

Isiphetho

I-TypeSafe Mario ikhombisa enye indlela ehlelekile yokulawula umdlalo esikhundleni sokuthembela ezithombeni-skrini. Ihumusha i-telemetry ye-emulator ne-RAM ibe yi-JSON esemthethweni egxile ezintweni, icele u-Jev ukuthi akhethe phakathi kwezenzo ezimbalwa ezisemthethweni, futhi iqophe zonke izinqumo ukuze zihlolwe bukhoma noma zihlaziywe kamuva. Qala nge-state-demo, dlala i-World 1-1 usebenzisa ideshibhodi, bese usebenzisa izinto ze-JSONL ezikhiqiziwe ukuze uqonde ubudlelwano phakathi kwesimo, isikhathi, ukuzethemba, nemiphumela.