Ultimate SFighterAI ٹیوٹوریل: PPO کے ذریعے 《Street Fighter 2》 مکمل کرنے والے ایجنٹ کی تربیت

پروجیکٹ کا تعارف

Ultimate SFighterAI ایک گہری تقویتی سیکھنے کا پروجیکٹ ہے جو Street Fighter 2: Champion Edition کے لیے بنایا گیا ہے۔ یہ کھلاڑی کے کردار کے طور پر Ryu استعمال کرتا ہے، PPO الگورتھم کے ذریعے NatureCNN ماڈل کو تربیت دیتا ہے، اور تربیت کا دائرہ تمام 12 اسٹیج تک پھیلاتا ہے۔

ماڈل کے فیصلوں کے لیے ان پٹ مکمل طور پر گیم اسکرین کے RGB پکسلز سے آتا ہے؛ کردار کی پوزیشن، ایکشن کی حالت یا صحت براہِ راست نہیں پڑھی جاتی۔ تربیتی ماحول صرف میموری کے متغیرات میں موجود agent_hp اور enemy_hp کو انعام کا حساب لگانے اور جیت یا ہار کا فیصلہ کرنے کے لیے استعمال کرتا ہے۔

پروجیکٹ میں پہلے سے تربیت یافتہ ماڈل کے وزن اور تربیتی ریکارڈ موجود ہیں، اس لیے آپ براہِ راست AI مقابلہ دیکھ سکتے ہیں، تجربہ دوبارہ چلا سکتے ہیں، متوازی ماحول کی تعداد تبدیل کر سکتے ہیں، یا موجودہ ماڈل کی بنیاد پر مزید تربیت جاری رکھ سکتے ہیں۔

اہم خصوصیات اور نفاذ

• تمام 12 اسٹیج شامل: ہر اسٹیج الگ سمیولیٹر میں چل سکتا ہے اور سب ایک ہی NatureCNN ماڈل کو مشترکہ طور پر تربیت دیتے ہیں۔
• خالص بصری فیصلہ سازی: ماڈل پروسیس شدہ گیم اسکرین کی بنیاد پر حرکت، حملہ اور خصوصی وار منتخب کرتا ہے۔
• 27 مجرد ایکشن: غیر جانب دار حالت، حرکت، عام حملے، بیٹھ کر حملہ، اور بائیں یا دائیں سمت میں Hadoken، Tatsumaki Senpu-kyaku اور Shoryuken جیسے ایکشن شامل ہیں۔
• PPO تقویتی سیکھنا: پروجیکٹ Stable-Baselines3 کے PPO الگورتھم پر مبنی ہے۔
• متعدد جائزہ طریقے: ہر اسٹیج کا محفوظ شدہ ڈیٹا لوڈ کر کے الگ الگ ٹیسٹ، تین میں سے دو راؤنڈ جیت، ایک KO کا جائزہ، اور پہلے اسٹیج سے مسلسل پیش رفت کی سہولت موجود ہے۔
• پہلے سے تربیت یافتہ ماڈل: ڈیفالٹ وزن logs/trained_models/ppo_ryu.zip میں موجود ہیں۔
• تربیت کی بصری نگرانی: انعام میں تبدیلی اور ماڈل اپ ڈیٹ کے ریکارڈ TensorBoard کے ذریعے دیکھے جا سکتے ہیں۔
• متعدد ڈیوائسز کی معاونت: تربیت اور inference کے پیرامیٹرز auto، cpu، cuda اور mps کو سپورٹ کرتے ہیں۔

اسکرین کی پیشگی پروسیسنگ

اصل گیم اسکرین کو مرکز سے کاٹنے، متحرک foreground نکالنے اور سائز تبدیل کرنے کے مراحل سے گزارا جاتا ہے، جس کے بعد ماڈل کے لیے 84×84×3 کا ان پٹ تیار ہوتا ہے۔ متحرک foreground نکالنے کے لیے t-16، t-8 اور t تین اوقات کے grayscale فرق استعمال کیے جاتے ہیں؛ پس منظر کی brightness کو 0.35 سے ضرب دے کر R، G اور B تینوں چینلز کے ساتھ ملایا جاتا ہے۔ اس عمل سے ماڈل کو کردار کی حرکت اور حملوں کو محسوس کرنے میں مدد ملتی ہے۔

انعام کا نظام

انعام بنیادی طور پر دونوں فریقوں کی صحت میں تبدیلی، knockdown کے نتیجے اور وقت کی لاگت سے تشکیل پاتا ہے۔ نقصان کے انعام کا حساب یوں ہے:

0.01 × (3 × مخالف کی کم ہوئی صحت − اپنی کم ہوئی صحت)

مخالف کو knockdown کرنے پر انعام:

0.01 × (176 + اپنی باقی صحت)

خود knockdown ہونے پر جرمانہ:

0.01 × (176 + مخالف کی باقی صحت)

اس کے علاوہ، ہر حقیقی طور پر انجام دیے گئے ایکشن پر وقت کا جرمانہ عائد ہوتا ہے، جس کی ڈیفالٹ قدر 0.0005 ہے۔

پروجیکٹ ڈائریکٹری کی وضاحت

• data/：12 اسٹیج کے ابتدائی محفوظ شدہ کھیل، گیم میموری کے متغیرات اور منظر کی ترتیب محفوظ کرتا ہے۔
• main/train.py：تمام اسٹیج کی متوازی تربیت اور دوبارہ تربیت سنبھالتا ہے۔
• main/test.py：الگ الگ اسٹیج کے ٹیسٹ اور مسلسل پیش رفت کا جائزہ لیتا ہے۔
• main/env_utils.py：ROM کی ترتیب اور ماحول کی تعمیر سنبھالتا ہے۔
• main/custom_wrappers.py：اسکرین پروسیسنگ، ایکشن میپنگ اور انعام کا حساب نافذ کرتا ہے۔
• logs/trained_models/ppo_ryu.zip：پروجیکٹ کا فراہم کردہ تربیت یافتہ ماڈل۔
• logs/：تربیتی عمل کے TensorBoard ریکارڈ شامل کرتا ہے۔
• requirements.txt：Python انحصارات کی فہرست۔

تنصیب اور ماحول کی ترتیب

مرحلہ 1: Python ماحول تیار کریں

پروجیکٹ Python 3.10 استعمال کرنے کی تجویز دیتا ہے۔ README میں درج تصدیق شدہ ماحول macOS، Apple Silicon اور Python 3.10.20 پر مشتمل ہے، جہاں CPU اور Apple MPS دونوں راستوں کی بھی تصدیق کی گئی ہے۔ دیگر پلیٹ فارمز کے لیے Stable-Retro اور PyTorch کی سرکاری تنصیب کی ہدایات دیکھیں۔

پروجیکٹ کی root ڈائریکٹری میں virtual environment بنائیں اور فعال کریں، پھر dependencies انسٹال کریں:

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows صارفین virtual environment فعال کرنے کے لیے یہ کمانڈ استعمال کر سکتے ہیں:

.venv\Scripts\activate

آپ Anaconda کے ذریعے Python 3.10 کا ماحول بھی بنا سکتے ہیں، پھر requirements.txt میں موجود dependencies انسٹال کریں۔ پروجیکٹ کی بنیادی dependencies میں Gymnasium، Stable-Retro اور Stable-Baselines3 شامل ہیں۔

مرحلہ 2: گیم ROM تیار کریں

Stable-Retro گیم ROM فراہم نہیں کرتا، اور یہ پروجیکٹ بھی ROM شامل نہیں کرتا۔ براہِ کرم Street Fighter 2: Champion Edition کے امریکی ورژن کا معاون ROM قانونی ذرائع سے حاصل کریں۔

ROM حاصل کرنے کے بعد اس کا absolute path environment variable کے ذریعے فراہم کیا جا سکتا ہے۔ macOS یا Linux میں چلائیں:

export SF2_ROM_PATH="/absolute/path/to/your/rom.md"

Windows PowerShell میں:

$env:SF2_ROM_PATH = "C:\path\to\your\rom.md"

دوسرا طریقہ یہ ہے کہ ROM کو پروجیکٹ کی ڈیفالٹ جگہ پر رکھیں:

data/street-fighter-ii-special-champion-edition-usa.md

تربیت اور ٹیسٹ کے پروگرام ROM کو خودکار طور پر import کریں گے۔ اگر موجودہ Python environment کے Stable-Retro میں ROM پہلے ہی import کیا جا چکا ہو تو اسے براہِ راست چلایا جا سکتا ہے۔

مرحلہ 3: اسٹیج کا ڈیٹا چیک کریں

data/ ڈائریکٹری میں موجود 12 .state فائلیں بالترتیب اسٹیج 1 سے 12 تک کے ابتدائی حالات محفوظ کرتی ہیں۔ data.json اور scenario_full_frame.json گیم میموری کے متغیرات اور منظر کی ترتیب متعین کرتے ہیں۔ پروگرام ان فائلوں کو براہِ راست پڑھتا ہے؛ انہیں Stable-Retro کی installation directory میں نقل کرنے کی ضرورت نہیں۔

پہلے سے تربیت یافتہ ماڈل چلائیں

تمام 12 اسٹیج کا الگ الگ ٹیسٹ

ماحول کی ترتیب مکمل ہونے کے بعد پروجیکٹ کی root ڈائریکٹری میں چلائیں:

python -m main.test --episodes 1

پروگرام اسٹیج 1 سے 12 تک کے ابتدائی محفوظ شدہ حالات باری باری لوڈ کرے گا، اور ہر اسٹیج پر ڈیفالٹ طور پر تین میں سے دو راؤنڈ جیتنے کا نظام استعمال کرے گا۔ --episodes 1 کا مطلب ایک مکمل جائزہ راؤنڈ ہے؛ اگر یہ پیرامیٹر چھوڑ دیا جائے تو ڈیفالٹ طور پر 10 راؤنڈ ٹیسٹ کیے جائیں گے۔

اگر کوئی اسٹیج ناکام ہو جائے تو پروگرام بعد کے اسٹیج کا ٹیسٹ جاری رکھے گا۔ ٹرمینل ہر اسٹیج کی جیت یا ہار، انعام، اسٹیج کی جیت کی شرح، اور ایک جائزہ راؤنڈ میں تمام 12 اسٹیج جیتنے کا تناسب دکھائے گا۔

جائزے پر توجہ دینے کے لیے اسکرین بند کریں

اگر مقابلہ دیکھنے کی ضرورت نہ ہو تو rendering بند کر کے CPU inference واضح طور پر استعمال کریں:

python -m main.test --episodes 1 --no-render --device cpu

Rendering بند کرنا batch evaluation کے لیے موزوں ہے اور ڈسپلے کی اضافی لاگت کم کرتا ہے۔

اسٹیج 1 سے مسلسل پیش رفت

اگر AI کو گیم کے معمول کے طریقہ کار کے مطابق اگلے مخالف کو چیلنج کرتے دیکھنا ہو تو یہ کمانڈ چلائیں:

python -m main.test --episodes 1 --no-load-level-saves

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

الگ الگ اسٹیج کے ٹیسٹ میں “تمام جیت” سے مراد ہے کہ ماڈل نے 12 آزاد اسٹیج محفوظات پر جائزہ پاس کیا؛ جبکہ “مکمل پیش رفت کی شرح” کا تقاضا ہے کہ ماڈل ایک ہی مسلسل عمل میں تمام 12 اسٹیج مکمل کرے۔ دونوں کے معنی مختلف ہیں۔

عام ٹیسٹ پیرامیٹرز

• --model-path PATH：PPO ماڈل متعین کریں، ڈیفالٹ logs/trained_models/ppo_ryu.zip ہے۔
• --episodes N：الگ الگ اسٹیج کے جائزے کے راؤنڈ یا مسلسل پیش رفت کی کوششوں کی تعداد متعین کریں، ڈیفالٹ 10 ہے۔
• --no-render：گیم اسکرین بند کریں۔
• --no-load-level-saves：ہر اسٹیج کا محفوظ شدہ ڈیٹا لوڈ نہ کریں، بلکہ پہلے اسٹیج سے مسلسل چیلنج شروع کریں۔
• --reset-round：الگ الگ اسٹیج کے ٹیسٹ میں ڈیفالٹ تین میں سے دو کے بجائے ایک KO کو جائزے کی اکائی بنائیں۔
• --device auto/cpu/cuda/mps：ماڈل کی inference ڈیوائس منتخب کریں، ڈیفالٹ auto ہے۔
• --speed N：ڈسپلے کیے جانے والے فریم کم کر کے visualization تیز کریں، ڈیفالٹ 4 ہے۔

اپنا ماڈل تربیت دیں

چھوٹی ترتیب سے شروع کریں

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

python -m main.train --envs-per-level 1 --batch-size 256 --log-dir runs/ryu

چونکہ پروجیکٹ میں 12 اسٹیج شامل ہیں، --envs-per-level 1 کا مطلب ہے کہ کل 12 متوازی سمیولیٹر چلیں گے۔ پہلے ROM، ماحول کی تعمیر، ڈیوائس اور log output کے درست ہونے کی تصدیق کریں، پھر بتدریج متوازی ماحول کی تعداد بڑھائیں۔

ڈیفالٹ تربیتی پیمانے کو سمجھیں

جب براہِ راست python -m main.train چلایا جاتا ہے تو ہر اسٹیج کے لیے ڈیفالٹ طور پر 64 سمیولیٹر شروع ہوتے ہیں، یعنی کل 768 متوازی ماحول۔ ڈیفالٹ n-steps=128 کے ساتھ PPO کی ایک update میں 98,304 samples جمع ہوتے ہیں، جبکہ مکمل تربیتی ہدف 700 ملین steps ہے۔

ڈیفالٹ ترتیب کے لیے کافی CPU اور میموری درکار ہے، اس لیے یہ عام کمپیوٹر پر پہلی آزمائش کے لیے موزوں نہیں۔ اپنے ہارڈویئر کے مطابق --envs-per-level، --batch-size یا تربیتی steps کی کل تعداد کم کریں۔

عام تربیتی پیرامیٹرز

• --envs-per-level N：ہر لیول کے لیے متوازی ماحول کی تعداد؛ متعین نہ ہونے پر ہر لیول کے لیے 64 ماحول ہوں گے۔
• --total-timesteps N：اس تربیتی مرحلے کے کل اسٹیپس؛ دوبارہ تربیت کے وقت اس سے مراد اضافی اسٹیپس ہیں، طے شدہ قدر 700000000 ہے۔
• --n-steps N：ہر اپ ڈیٹ سے پہلے ہر سمیولیٹر کے ذریعے جمع کیے جانے والے اسٹیپس کی تعداد، طے شدہ قدر 128 ہے۔
• --batch-size N：PPO اپ ڈیٹ بیچ کا حجم، طے شدہ قدر 8192 ہے۔
• --n-epochs N：ہر نمونہ شدہ ڈیٹا بیچ کی تربیتی ادوار کی تعداد، طے شدہ قدر 3 ہے۔
• --learning-rate N：سیکھنے کی شرح، طے شدہ قدر 0.0002 ہے۔
• --device auto/cpu/cuda/mps：تربیتی ڈیوائس منتخب کریں، طے شدہ قدر mps ہے۔
• --log-dir PATH：ماڈل اور تربیتی گراف کے آؤٹ پٹ کی ڈائریکٹری، طے شدہ قدر logs/ALL_MOTION_SIMULTANEOUS ہے۔

پہلے سے تربیت یافتہ وزن کے ساتھ دوبارہ تربیت

پروجیکٹ فراہم کردہ PPO وزن سے دوبارہ تربیت کی حمایت کرتا ہے۔ درج ذیل کمانڈ مزید 1000000 اسٹیپس کی تربیت چلاتی ہے اور نتائج نئی ڈائریکٹری میں محفوظ کرتی ہے:

python -m main.train \
  --resume-model logs/trained_models/ppo_ryu.zip \
  --envs-per-level 1 --batch-size 256 \
  --total-timesteps 1000000 --log-dir runs/ryu-resume

دوبارہ تربیت کے وقت، --total-timesteps سے مراد اس مرحلے میں انجام دیے جانے والے اضافی تربیتی اسٹیپس ہیں، نہ کہ پرانے ماڈل کی تربیت سمیت مجموعی ہدف۔

تربیتی گراف دیکھنے کے لیے TensorBoard استعمال کرنا

پروجیکٹ تربیتی ریکارڈ خود محفوظ کرتا ہے۔ TensorBoard شروع کریں:

tensorboard --logdir=logs

اس کے بعد براؤزر میں http://localhost:6006/ کھولیں، جہاں انعام میں تبدیلی اور ماڈل اپ ڈیٹس سے متعلق گراف دیکھے جا سکتے ہیں۔

اپنی تربیت سے بننے والے لاگز دیکھنے کے لیے صرف ڈائریکٹری تبدیل کریں:

tensorboard --logdir=runs/ryu

اعلیٰ سطح کے استعمال کی تجاویز

1. پہلے تصدیق کریں، پھر توسیع کریں: ابتدا میں ہر لیول کے لیے ایک ماحول استعمال کرتے ہوئے مختصر تربیت مکمل کریں، اور ROM درآمد، سیو فائل پڑھنے اور لاگ لکھنے کی درستگی کی تصدیق کے بعد متوازی سمیولیٹرز کی تعداد بڑھائیں۔
2. پلیٹ فارم کے مطابق ڈیوائس منتخب کریں: Apple Silicon پر mps آزمایا جا سکتا ہے، NVIDIA GPU سے مطابقت رکھنے والے ماحول میں cuda منتخب کریں، ورنہ cpu یا auto استعمال کریں۔ README میں macOS Apple Silicon ماحول کی تصدیق کی گئی ہے؛ دیگر پلیٹ فارمز پر PyTorch اور Stable-Retro کے تقاضوں کے مطابق ترتیب دینا ضروری ہے۔
3. تشخیص کی دو اقسام الگ رکھیں: ہر لیول کی الگ سیو فائل کی جانچ مختلف حریفوں کی کارکردگی کے تجزیے کے لیے موزوں ہے، جبکہ مسلسل لیولز مکمل کرنا پورے گیم کے طریقۂ کار سے زیادہ قریب ہے۔ نتائج رپورٹ کرتے وقت استعمال شدہ موڈ واضح کریں۔
4. بغیر رینڈرنگ کے بیچ تشخیص کریں: متعدد ادوار کے اعدادوشمار جمع کرتے وقت --no-render شامل کریں، اور حکمتِ عملی کی کارکردگی دیکھتے وقت اسکرین فعال کریں۔
5. تجربات کو الگ ڈائریکٹریز میں محفوظ کریں: مختلف پیرامیٹر مجموعوں کے لیے --log-dir کے ذریعے الگ ڈائریکٹریز بنائیں تاکہ تربیتی ریکارڈ ایک دوسرے پر تحریر نہ ہوں اور TensorBoard میں موازنہ آسان رہے۔
6. مکمل کمانڈ اختیارات دیکھیں: تربیت اور جانچ کے دونوں اسکرپٹس مدد کی معلومات فراہم کرتے ہیں۔

python -m main.train --help
python -m main.test --help

ماڈیول کے ذریعے چلانے کے علاوہ، پروجیکٹ اسکرپٹس کو براہِ راست چلانے کی بھی حمایت کرتا ہے:

python main/train.py
python main/test.py

اختتامیہ

Ultimate SFighterAI یہ دکھاتا ہے کہ پکسل ان پٹ، ایکشن میپنگ، انعام کی تشکیل، PPO اور متعدد لیولز کے متوازی ماحول کو ملا کر ایک مکمل فائٹنگ گیم ایجنٹ کیسے بنایا جا سکتا ہے۔ آغاز کا سب سے قابلِ اعتماد طریقہ یہ ہے کہ پہلے ROM ترتیب دے کر پہلے سے تربیت یافتہ ماڈل چلائیں، پھر کم متوازی ماحول کے ساتھ تربیت دوبارہ پیش کریں، اور آخر میں دوبارہ تربیت، ڈیوائس کے انتخاب اور TensorBoard کے تجزیے کے ذریعے تجربات کا حجم بتدریج بڑھائیں۔

پروجیکٹ Apache License 2.0 کے تحت جاری کیا گیا ہے اور Gymnasium، Stable-Retro اور Stable-Baselines3 جیسے اوپن سورس اجزا استعمال کرتا ہے۔