স্ট্রাকচার্ড এমুলেটর টেলিমেট্রি ও 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 কী
• Super Mario Bros.-এর জন্য একটি আইনসম্মত স্থানীয় সেটআপ

রিপোজিটরিতে Nintendo ROM বা অন্য কোনো কপিরাইটযুক্ত গেম ডেটা নেই। আপনার এমুলেটর ও গেম ফাইল আইনসম্মতভাবে সংগ্রহ ও ব্যবহার করার দায়িত্ব আপনার।

ইনস্টলেশন

README-তে ভার্চুয়াল পরিবেশ তৈরি, Mario ও ডেভেলপমেন্ট নির্ভরতা ইনস্টল এবং API কী কনফিগার করার জন্য PowerShell কমান্ড দেওয়া আছে।

1. Python 3.13-এর একটি ভার্চুয়াল পরিবেশ তৈরি করুন।
2. প্রয়োজনীয় অতিরিক্ত উপাদানসহ প্রকল্পটি editable mode-এ ইনস্টল করুন।
3. বর্তমান PowerShell সেশনের জন্য TypeSafe API কী সেট করুন।

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 কী বসান। কমান্ডটি একটি PowerShell পরিবেশ ভেরিয়েবল সেট করে, তাই আলাদাভাবে ভেরিয়েবলটি স্থায়ী না করলে পরবর্তী কমান্ডগুলো একই কনফিগার করা পরিবেশ থেকে চালান।

প্রথমে মডেলের ইনপুট পরিদর্শন করুন

গেম চালু করার আগে, প্রকল্পটি TypeSafe-এ যে সঠিক JSON ও টেক্সট পাঠাবে তা দেখতে state-demo ব্যবহার করুন:

.venv\Scripts\typesafe-mario state-demo

এই কমান্ডটি গেম চালু করে না এবং API-তে কলও করে না। মডেলের জন্য ব্যবহৃত স্কিমা বোঝা এবং এমুলেটরের পর্যবেক্ষণ কীভাবে উপস্থাপিত হয় তা যাচাই করার এটাই সবচেয়ে নিরাপদ উপায়।

স্ট্রাকচার্ড স্টেট বোঝা

ক্যানোনিকাল অবজেক্টটি পর্যবেক্ষণগুলোকে তাদের উদ্দেশ্য অনুযায়ী সাজায়:

• player: অবস্থান, বেগ, মাটিতে থাকা অবস্থার তথ্য, লাফের পর্যায় এবং পাওয়ার-আপ।
• 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 আর্টিফ্যাক্ট ব্যবহার করুন।