دليل Ultimate SFighterAI الشامل: درّب وكيلًا بـ PPO قادرًا على إنهاء «ستريت فايتر 2»

نبذة على المشروع

Ultimate SFighterAI هو مشروع ديال التعلّم المعزّز العميق موجّه للعبة «ستريت فايتر 2: تشامبيون إيديشن». كيستعمل Ryu كشخصية اللاعب، وكي درّب موديل NatureCNN باستعمال خوارزمية PPO، وكي وسّع التدريب باش يشمل المراحل الـ12 كاملين ديال اللعبة.

مدخلات القرار ديال الموديل ك تجي كاملة من بيكسلات RGB ديال صورة اللعبة، بلا ما يقرا مباشرة موقع الشخصية ولا حالة الحركة ولا نقاط الحياة. بيئة التدريب كتستعمل غير المتغيّرات الموجودة فالذاكرة agent_hp وenemy_hp باش تحسب المكافأة وتحدّد الربح والخسارة.

المشروع كيوفّر أوزان الموديل المدرّب وسجلات التدريب، وهاد الشي كيخلّيك تقدر تشوف مواجهة AI مباشرة، ولا تعاود التجربة، ولا تبدّل حجم التشغيل الموازي، ولا تكمّل التدريب انطلاقاً من موديل موجود.

الوظائف الأساسية وخصائص التنفيذ

• تغطية المراحل الـ12 كاملين: كل مرحلة تقدر تخدم فمحاكي مستقل، وجميع المراحل كيدرّبو نفس موديل NatureCNN.
• قرار بصري خالص: الموديل كيختار الحركة والهجوم والتقنيات الخاصة اعتماداً على صورة اللعبة المعالجة.
• 27 حركة منفصلة: كتشمل الوقوف، الحركة، الهجمات العادية، الهجمات من وضعية القرفصاء، وزيد عليهم هادوكن، ركلة الإعصار والضربة الطالعة فالاتجاهين اليمين واليسار.
• التعلّم المعزّز بـ PPO: المشروع كيتدرّب باستعمال خوارزمية PPO من Stable-Baselines3.
• أنماط تقييم متعددة: كيدعم اختبار تحميل الحفظات مرحلة بمرحلة، ونظام الربح بجوج جولات من أصل ثلاثة، وتقييم KO واحد، والتقدّم المتواصل ابتداءً من المرحلة الأولى.
• موديل مدرّب مسبقاً: الأوزان الافتراضية كاينة فـ logs/trained_models/ppo_ryu.zip.
• تصوير التدريب: تقدر تستعمل TensorBoard باش تشوف تغيّر المكافآت وسجلات تحديث الموديل.
• دعم أجهزة متعددة: معاملات التدريب والاستدلال كيدعمو auto وcpu وcuda وmps.

المعالجة المسبقة للصورة

صورة اللعبة الأصلية كتدوز من قصّ مركزي، واستخراج المقدّمة المتحرّكة، والتصغير، باش تولّي فالأخير مدخلاً للموديل بحجم 84×84×3. استخراج المقدّمة المتحرّكة كيستعمل فروقات الرمادي بين ثلاثة أوقات: t-16 وt-8 وt، وكيضرب سطوع الخلفية فـ 0.35، ومن بعد كيركّب القنوات الثلاث R وG وB. هاد المعالجة كتعاون الموديل يحسّ بحركة الشخصيات والهجمات.

نظام المكافآت

المكافأة كتتكوّن بالأساس من تغيّر نقاط حياة الجوج، ونتيجة الإسقاط، وكلفة الوقت. طريقة حساب مكافأة الضرر هي:

0.01 × (3 × الدم اللي نقص من الخصم − الدم اللي نقص منك)

المكافأة ملي كتسقط الخصم هي:

0.01 × (176 + نقاط حياتك المتبقية)

العقوبة ملي كتتسقط نتا هي:

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.

التثبيت وإعداد البيئة

الخطوة الأولى: حضّر بيئة Python

المشروع كينصح باستعمال Python 3.10. البيئة الموثّقة فالـREADME هي macOS مع Apple Silicon وPython 3.10.20، وتدار فيها التحقّقات على مساري CPU وApple MPS. فالمنصات الأخرى خاص الرجوع لتعليمات التثبيت الرسمية ديال Stable-Retro وPyTorch.

أنشئ وفعّل بيئة افتراضية فالمجلد الرئيسي ديال المشروع، ومن بعد ثبّت التبعيات:

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

مستعملو Windows يقدرو يفعّلو البيئة الافتراضية بهاد الأمر:

.venv\Scripts\activate

تقدر حتى تستعمل Anaconda باش تنشئ بيئة Python 3.10، ومن بعد تثبّت التبعيات اللي فـ requirements.txt. التبعيات الرئيسية ديال المشروع هي Gymnasium وStable-Retro وStable-Baselines3.

الخطوة الثانية: حضّر ROM ديال اللعبة

Stable-Retro ما كيوفّرش ROM ديال الألعاب، والمشروع حتى هو ما فيهش ROM. خاصك تحصل بطرق قانونية على ROM مدعوم ديال النسخة الأمريكية من «ستريت فايتر 2: تشامبيون إيديشن».

من بعد ما تحصل على ROM، تقدر توفّر المسار المطلق ديالو باستعمال متغيّر بيئي. فـ 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 أوتوماتيكياً. إلا كان Stable-Retro ديال بيئة Python الحالية مستورد هاد ROM من قبل، تقدر تشغّل البرنامج مباشرة.

الخطوة الثالثة: تأكّد من بيانات المراحل

الملفات الـ12 ديال .state اللي فمجلد data/ كتحفظ حالات البداية من المرحلة 1 حتى المرحلة 12. الملفان data.json وscenario_full_frame.json كيحدّدو متغيّرات ذاكرة اللعبة وإعدادات المشهد. البرنامج كيقرا هاد الملفات مباشرة، وما كايناش حاجة تنسخها لمجلد تثبيت Stable-Retro.

تشغيل الموديل المدرّب مسبقاً

اختبار المراحل الـ12 كاملين مرحلة بمرحلة

من بعد ما تكمل إعداد البيئة، نفّذ من المجلد الرئيسي ديال المشروع:

python -m main.test --episodes 1

البرنامج غادي يحمّل بالتتابع حفظات بداية المراحل من 1 حتى 12، وكل مرحلة افتراضياً كتستعمل نظام الربح بجوج جولات من أصل ثلاثة. --episodes 1 كتعني تقييم دورة كاملة؛ إلا حيدتي هاد المعامل، فالافتراضي هو اختبار 10 دورات.

إلا خسرات شي مرحلة، البرنامج غادي يكمل اختبار المراحل اللي من بعدها. فالطرفية غادي يبان ربح وخسارة كل مرحلة، والمكافأة، ونسبة الربح فالمرحلة، وزيد نسبة الدورات اللي ربح فيها الموديل المراحل الـ12 كاملين.

إغلاق الصورة والتركيز على نتائج التقييم

إلا ما بغيتيش تشوف المواجهات، تقدر تغلق العرض وتستعمل CPU بوضوح فالاستدلال:

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

إغلاق العرض مناسب للتقييمات الجماعية، حيث كيقلّل الكلفة الإضافية ديال العرض.

التقدّم المتواصل ابتداءً من المرحلة الأولى

إلا بغيتي تشوف 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: اختيار جهاز استدلال الموديل، والقيمة الافتراضية هي auto.
• --speed N: تسريع العرض عبر تقليل عدد الإطارات المعروضة، والقيمة الافتراضية هي 4.

درّب الموديل ديالك

بدا بإعداد صغير

احتياجات الموارد ديال إعداد التدريب الافتراضي كبيرة بزاف. فأول تشغيل، كينصح المشروع تشغّل محاكي واحد فقط لكل مرحلة وتستعمل دفعة صغيرة:

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

حيت المشروع فيه 12 مرحلة، فـ --envs-per-level 1 كتعني تشغيل 12 محاكي موازي فالمجموع. تأكّد أولاً أن ROM وبناء البيئة والجهاز وإخراج السجلات خدامين مزيان، ومن بعد زيد عدد التشغيلات الموازية بالتدريج.

فهم حجم التدريب الافتراضي

إلا شغّلتي مباشرة python -m main.train، فكل مرحلة غادي تشغّل افتراضياً 64 محاكي، يعني 768 بيئة موازية فالمجموع. ومع n-steps=128 الافتراضي، كل تحديث ديال PPO غادي يجمع 98,304 عينة، والهدف الكامل للتدريب هو 7 مئات مليون خطوة.

الإعداد الافتراضي كيحتاج CPU وذاكرة كافيين، وما مناسبش كاختبار أول على حاسوب عادي. خاصك تنقص --envs-per-level أو --batch-size أو عدد خطوات التدريب الإجمالي حسب العتاد المتوفر.

معاملات التدريب المستعملة بزاف

• --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 المتوفرة. الأمر التالي كيزيد مليون خطوة تدريب وكيكتب النتائج فمجلد جديد:

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.