README.md

# 🎮 Minecraft Java Server — Hugging Face Spaces

> سيرفر Minecraft Java Edition صغير يعمل داخل Docker على Hugging Face Spaces.
> مثالي للعب مع الأصدقاء دون الحاجة لاستضافة مدفوعة.

---

## ما الذي يفعله هذا المشروع؟

- يُشغّل **Minecraft Java server** داخل حاوية Docker.
- يُنزّل JAR السيرفر تلقائيًا من Mojang عند أول تشغيل.
- يحفظ عالمك ولوغاتك في `/data` (دائم بين إعادات التشغيل).
- يقبل إعدادات مرنة عبر متغيرات البيئة دون تعديل الكود.

---

## المتطلبات

| المتطلب | التفاصيل |
|--------|----------|
| حساب Hugging Face | مجاني على [huggingface.co](https://huggingface.co) |
| Space من نوع Docker | اختر **Docker** عند إنشاء الـ Space |
| Hardware | Space مجاني يكفي للتجربة — CPU basic |
| Minecraft Java Edition | على أجهزة اللاعبين (نسخة مدفوعة) |
| منفذ مفتوح | HF Spaces لا تدعم TCP مباشرة — راجع ملاحظة الشبكة |

---

## كيفية الرفع إلى Hugging Face

```bash
# 1. ثبّت git-lfs إن لم يكن مثبتًا
git lfs install

# 2. أنشئ Space جديد من نوع Docker على huggingface.co/new-space

# 3. استنسخ الـ Space الفارغ
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 4. انسخ ملفات هذا المشروع إليه
cp -r /path/to/minecraft-hf-space/* .

# 5. ارفع
git add .
git commit -m "Initial Minecraft server setup"
git push
```

بعد الـ push، سيبني HF الـ Docker image تلقائيًا ويُشغّل السيرفر.

---

## كيفية تشغيل السيرفر

بعد رفع الملفات:

1. افتح الـ Space على Hugging Face.
2. انتظر حتى يكتمل البناء (عادةً 2-3 دقائق).
3. راقب اللوغات من تبويب **Logs** في الـ Space.
4. عند ظهور `Done! For help, type "help"` — السيرفر شغّال.

### الاتصال بالسيرفر ⚠️

> **تنبيه مهم:** Hugging Face Spaces لا تكشف منافذ TCP خارجيًا تلقائيًا.
> لتمرير المنفذ، استخدم إحدى الطرق التالية:

| الخيار | التفاصيل |
|--------|----------|
| **playit.gg** | خدمة مجانية لتمرير منفذ Minecraft — الأسهل |
| **ngrok** | يتطلب حساب مجاني، يدعم TCP |
| **Cloudflare Tunnel** | للمستخدمين المتقدمين |

مثال باستخدام playit.gg داخل الـ container:
```bash
# أضف في start.sh قبل تشغيل Java:
curl -SsL https://playit.gg/downloads/playit-linux-amd64 -o /tmp/playit
chmod +x /tmp/playit
/tmp/playit &
```

---

## كيف أحافظ على العالم محفوظًا؟

- **العالم يُحفظ في `/data/world`** (أو أي اسم اخترته في `MC_WORLD`).
- `/data` هو الـ volume الدائم في Spaces — البيانات لا تُحذف عند إعادة التشغيل.
- لعمل نسخة احتياطية يدوية: اذهب إلى **Files** في الـ Space وحمّل مجلد `data/world`.

> ⚠️ إذا **حذفت الـ Space** نفسه، ستُفقد البيانات. احتفظ بنسخة خارجية دائمًا.

---

## كيف أغيّر الإعدادات؟

كل الإعدادات الرئيسية تُتحكم بها عبر **Environment Variables** في إعدادات الـ Space:

| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `MC_VERSION` | `1.21.4` | إصدار Minecraft |
| `MC_MEMORY` | `1G` | الحد الأدنى للـ RAM |
| `MC_MAX_MEMORY` | `2G` | الحد الأقصى للـ RAM |
| `MC_WORLD` | `world` | اسم مجلد العالم |
| `SERVER_PORT` | `25565` | منفذ السيرفر |

### طريقة التعديل:
1. افتح Space ← **Settings** ← **Variables and secrets**
2. أضف المتغير بالاسم والقيمة المطلوبة.
3. أعد تشغيل الـ Space.

### تغيير إعدادات اللعبة (server.properties):
بعد أول تشغيل، عدّل `/data/server.properties` مباشرة عبر:
- أداة الـ terminal في الـ Space (إن توفرت)
- أو أضف سكريبت يعدّل الملف قبل التشغيل

---

## هيكل الملفات

```
minecraft-hf-space/
├── Dockerfile                      # تعريف الحاوية
├── start.sh                        # سكريبت التشغيل
├── README.md                       # هذا الملف
└── config/
    └── server.properties.template  # قالب الإعدادات
```

بعد التشغيل الأول، ستجد في `/data`:
```
/data/
├── server.jar          # JAR السيرفر (مُخزَّن مؤقتًا)
├── eula.txt
├── server.properties
├── world/              # العالم المحفوظ
└── logs/
```

---

## نصائح الأداء

- **RAM:** على الـ Space المجاني (16GB RAM)، `MC_MAX_MEMORY=3G` جيد لـ 5 لاعبين.
- **view-distance:** قيمة 6-8 تكفي وتوفر CPU.
- **Aikar's flags:** مُضمّنة في `start.sh` لتحسين GC.

---

## الترخيص

هذا المشروع لأغراض تعليمية وتجريبية.
Minecraft ملك لـ Mojang/Microsoft — تأكد من امتلاك نسخة أصلية.