Dhibiti Super Mario Bros. kwa TypeSafe Jev na Telemetria Iliyopangwa ya Emulator

TypeSafe Mario Hufanya Nini

TypeSafe Mario ni kidhibiti cha majaribio kinachoruhusu modeli ya Jev ya TypeSafe kuchagua ingizo la kidhibiti kwa Super Mario Bros. ya asili. Badala ya kupokea picha za skrini, modeli hupokea JSON fupi inayolenga vitu, iliyotokana na telemetry ya emulator na RAM.

Mzunguko wa udhibiti unafuata usanifu huu:

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

Baada ya Jev kuchagua kitendo halali, emulator husogeza mbele fremu kadhaa na kuzalisha hali mpya. Mchakato huu hurudiwa katika kipindi chote. Gridi ghafi ya vigae vya eneo husalia kwenye kumbukumbu za utatuzi na dashibodi, lakini hainakiliwi katika ingizo linaloelekezwa kwa modeli.

Vitendo vya kidhibiti vinavyopatikana

Seti ya awali ya vitendo imewekewa kikomo kimakusudi kwa makro saba za kidhibiti:

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

Vipengele Muhimu

• Ingizo la modeli lililopangwa: Kichanganua hutuma kwa TypeSafe vitu vya JSON vyenye maana badala ya maelezo yaliyonyooka au picha za skrini.
• Hukumu nyingi: Kila ombi hutathmini chaguo la kidhibiti, manufaa ya kuruka mbele, na hatari ya papo hapo.
• Muda wa mwitikio uliopimwa: Hali inajumuisha muda wa kitendo na ucheleweshaji kutoka uchunguzi hadi kitendo.
• Dashibodi ya moja kwa moja: Onyesho chaguo-msingi linachanganya uchezaji na uwezekano wa vitendo, uhakika, muda wa kusubiri, hatari, zawadi, na hali iliyochanganuliwa.
• Kumbukumbu za kina za uendeshaji: Kila uamuzi huhifadhiwa kama rekodi ya JSON Lines kwa uchanganuzi au uonyeshaji wa baadaye.
• Muonekano wa utatuzi: Maandishi ya hali yanayosomeka na gridi ya karibu ya vigae husalia kupatikana kwa ukaguzi.

Mahitaji na Usanidi wa Kisheria

Kabla ya kusakinisha mradi, hakikisha mazingira yako yanatimiza mahitaji haya:

• Python 3.13 au mpya zaidi
• Ufunguo wa API wa TypeSafe uliohifadhiwa katika TYPESAFE_API_KEY
• Usanidi halali wa ndani wa Super Mario Bros.

Hifadhi ya mradi haina ROM ya Nintendo wala data nyingine ya mchezo iliyo na hakimiliki. Unawajibika kupata na kutumia emulator na faili za mchezo wako kwa njia halali.

Usakinishaji

README hutoa amri za PowerShell za kuunda mazingira pepe, kusakinisha utegemezi wa Mario na wa uundaji, na kusanidi ufunguo wa API.

1. Unda mazingira pepe ya Python 3.13.
2. Sakinisha mradi katika hali ya kuhaririwa pamoja na ziada zinazohitajika.
3. Weka ufunguo wa API wa TypeSafe kwa kipindi cha sasa cha PowerShell.

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

Badilisha your-key kwa ufunguo wako halisi wa API wa TypeSafe. Kwa kuwa amri hii huweka kigezo cha mazingira cha PowerShell, endesha amri zinazofuata kutoka mazingira hayo hayo yaliyosanidiwa isipokuwa ukiendeleza kigezo hicho kando.

Kagua Ingizo la Modeli Kwanza

Kabla ya kuanzisha mchezo, tumia state-demo kukagua JSON na maandishi kamili ambayo mradi ungetuma kwa TypeSafe:

.venv\Scripts\typesafe-mario state-demo

Amri hii haianzishi mchezo wala haiiti API. Ndiyo njia salama zaidi ya kuelewa schema inayolengwa kwa modeli na kuthibitisha jinsi uchunguzi wa emulator unavyowakilishwa.

Kuelewa hali iliyopangwa

Kitu cha kikanoni hupanga uchunguzi kulingana na madhumuni yake:

• player: Mahali, kasi, hali ya kuwa ardhini, awamu ya kuruka, na nguvu.
• trajectory: Muda wa angani, umbali tangu kuruka, na iwapo Mario amejitolea kuvuka pengo.
• hazard: Hadi maadui watatu, maeneo yao yaliyokadiriwa, muda unaotarajiwa wa kugusana, na muda wa mwisho wa kuruka.
• terrain: Jiometri ya vizuizi na mapengo, uaminifu wa uchunguzi, na onyesho la mwisho la eneo la ardhini.
• reaction_timing: Muda wa kitendo cha kidhibiti na ucheleweshaji uliopimwa kutoka uchunguzi hadi kitendo.
• recent_control: Kitendo kilichotangulia, muda wake, maendeleo yaliyopatikana, na matokeo yaliyoonekana.
• episode: Maisha, saa, maendeleo, kusimama, hali ya kufa, na kukamilika kwa kiwango.

JSON iliyopangwa ndiyo hali ya kikanoni ya modeli. Uwasilishaji mpana zaidi wa maandishi upo kwa ajili ya utatuzi na kiolesura cha mtumiaji pekee. Picha ya utatuzi inaweza kujumuisha viwianishi na mwendo wa Mario, maendeleo ya kipindi, maadui walio karibu, na gridi ya ndani ya vigae inayotumia herufi.

Endesha World 1-1

Anzisha mazingira ya World 1-1 na umruhusu Jev kuchagua kitendo kila hatua nane za emulator:

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

Chaguo la --env huchagua mazingira, huku --frames-per-decision 8 likibainisha idadi ya hatua za emulator zinazotokea kati ya maamuzi ya modeli. Kwa onyesho chaguo-msingi, mradi hufungua dirisha moja linaloweza kurekodiwa lenye mchezo wa moja kwa moja na telemetry ya modeli.

Tumia dashibodi

Dashibodi huonyesha taarifa zinazohitajika kufuatilia tabia ya Jev:

• Kitendo cha kidhibiti kilichochaguliwa
• Mgawanyo kamili wa uwezekano wa Choice
• Uhakika wa modeli
• Muda wa kusubiri ombi la Jev
• Uwezekano wa kuruka mbele
• Alama ya hatari ya papo hapo
• Zawadi
• Hali ya mchezo iliyochanganuliwa

Bonyeza R au ubofye Restart ili kuanza kipindi kipya. Dashibodi hubaki wazi baada ya Mario kufa au kukamilisha kiwango. Bonyeza Esc au Q ili kuondoka.

Chagua Hali ya Kuonyesha

Dashibodi chaguomsingi iliyounganishwa ni muhimu unapofuatilia au kurekodi mchezo. Hali mbili za ziada zinasaidia matumizi mahususi zaidi.

Onyesha emulator pekee

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

Hali ya kuonyesha game huonyesha dirisha la emulator pekee.

Endesha bila kuonyesha

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

Hali ya kuonyesha none huendesha programu bila kiolesura cha picha na imekusudiwa kwa utekelezaji wa aina ya ulinganishaji wa utendaji.

Elewa Hukumu Tatu za TypeSafe

Kila ombi hutathmini hukumu tatu huru juu ya hali ileile iliyopangwa:

• Choice: Huchagua amri-mseto inayofuata iliyoruhusiwa ya kidhibiti.
• Noul: Hukadiria iwapo kuruka kwenda mbele kuna manufaa wakati huo.
• Score: Hupima hatari ya papo hapo kwa ajili ya taswira ya moja kwa moja.

Hukumu hizi zina majukumu tofauti. Matokeo ya Choice humdhibiti Mario, huku makadirio ya kuruka na alama ya hatari vikitoa tafsiri na taswira ya ziada.

Mahesabu sahihi ya muda hubaki kwenye msimbo. Kwa mfano, kichanganuzi huunganisha umri wa jibu, mwendo wa adui, mfuatano wa vitendo, na muda wa kuondoa kizuizi kwa kuruka kuwa ukweli wenye aina wa jump_must_start_this_decision. Jev hutafsiri ukweli huo na bado anamiliki chaguo la kidhibiti; harness haitumii ubatilishaji wa kitendo cha kurekebisha kilichoandikwa mapema.

Kagua Maamuzi Yaliyorekodiwa

Kila uamuzi huandikwa kwenye faili la JSON Lines lenye muhuri wa muda:

artifacts/run-<timestamp>.jsonl

Rekodi hizo zinajumuisha:

• Kuchelewa kwa Jev
• Uwezekano wa vitendo
• Kujiamini
• Hali ya kielelezo iliyo kanoniki
• Hali ghafi ya utatuzi
• Matokeo ya mchezo

Rekodi hizi hutoa data inayohitajika kukagua mchezo baada ya utekelezaji. Pia zinaweza kutumika kama ingizo la onyesho la moja kwa moja au klipu ya kijamii iliyotengenezwa.

Vidokezo vya Matumizi ya Juu

Thibitisha uchunguzi kabla ya mchezo

Endesha state-demo kabla ya kipindi cha moja kwa moja unapotaka kukagua uwakilishi unaoelekezwa kwa kielelezo bila kuanzisha emulator au kutumia ombi la API. Zingatia hasa utenganishaji kati ya hali kanoniki iliyopangwa na maandishi ya utatuzi yanayolenga binadamu.

Tafsiri ukweli wa muda pamoja na mfuatano wa vitendo

Kidhibiti hutenda katika vipindi vya fremu nyingi, kwa hiyo muda wa kuitikia ni sehemu ya hali badala ya kuwa dhana ya nje. Unapokagua uamuzi, linganisha kitendo kilichochaguliwa na ucheleweshaji wa jibu, muda wa kitendo, mgusano wa adui unaotarajiwa, na muda wowote wa mwisho wa kuruka ulioripotiwa na kichanganuzi.

Tumia hali inayofaa ya kuonyesha kwa kazi

• Tumia dashibodi chaguomsingi unapokagua ishara za mantiki ya kielelezo pamoja na mchezo.
• Tumia --display game unapohitaji tu matokeo ya emulator.
• Tumia --display none kwa majaribio ya ulinganishaji wa utendaji bila kiolesura.

Changanua mgawanyo kamili wa uwezekano

Usiweke uchanganuzi kwenye kitendo kilichochaguliwa pekee. Dashibodi na vizalia vya JSONL vinajumuisha mgawanyo kamili wa uwezekano wa Choice pamoja na kujiamini, jambo linaloweza kuonyesha iwapo Jev alipendelea sana kitendo kimoja au alichagua kati ya njia mbadala kadhaa zenye uzito unaokaribiana.

Endesha Ukaguzi wa Uundaji

Hazina hii inajumuisha amri za uumbizaji, ukaguzi wa msimbo, na majaribio kwa wachangiaji. Zifanye kutoka kwenye mazingira pepe yaliyosanidiwa:

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

Amri ya kwanza hukagua uumbizaji, ya pili huendesha ukaguzi wa Ruff wa msimbo, na ya tatu hutekeleza seti ya majaribio kwa matokeo mafupi.

Hitimisho

TypeSafe Mario huonyesha njia mbadala iliyopangwa ya kudhibiti mchezo badala ya kutegemea picha za skrini. Hutafsiri telemetry ya emulator na RAM kuwa JSON kanoniki inayolenga vitu, humwomba Jev achague kutoka kwenye seti fupi ya vitendo vinavyoruhusiwa, na kurekodi kila uamuzi kwa ukaguzi wa moja kwa moja au uchanganuzi wa baadaye. Anza na state-demo, cheza World 1-1 kupitia dashibodi, kisha utumie vizalia vya JSONL vilivyotengenezwa kuelewa jinsi hali, muda, kujiamini, na matokeo vinavyohusiana.