Upload 2 files

README.md

@@ -0,0 +1,152 @@
+# 🎮 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 — تأكد من امتلاك نسخة أصلية.

start.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+set -e
+
+# ═══════════════════════════════════════════════════════════
+#  Minecraft Java Server — startup script
+#  Runs inside Docker on Hugging Face Spaces
+# ═══════════════════════════════════════════════════════════
+
+DATA_DIR="/data"
+SERVER_JAR="${DATA_DIR}/server.jar"
+LOG_DIR="${DATA_DIR}/logs"
+
+MC_VERSION="${MC_VERSION:-1.21.4}"
+MC_MEMORY="${MC_MEMORY:-1G}"
+MC_MAX_MEMORY="${MC_MAX_MEMORY:-2G}"
+MC_WORLD="${MC_WORLD:-world}"
+SERVER_PORT="${SERVER_PORT:-25565}"
+
+mkdir -p "${DATA_DIR}" "${LOG_DIR}"
+
+echo "══════════════════════════════════════════"
+echo " Minecraft Java Server"
+echo " Version  : ${MC_VERSION}"
+echo " Memory   : ${MC_MEMORY} → ${MC_MAX_MEMORY}"
+echo " World    : ${MC_WORLD}"
+echo " Port     : ${SERVER_PORT}"
+echo "══════════════════════════════════════════"
+
+# ── 1. Accept EULA automatically ───────────────────────────
+echo "eula=true" > "${DATA_DIR}/eula.txt"
+echo "[✓] EULA accepted."
+
+# ── 2. Download server JAR if not cached ──────────────────
+if [ ! -f "${SERVER_JAR}" ]; then
+    echo "[~] Fetching Minecraft ${MC_VERSION} server JAR..."
+
+    MANIFEST_URL="https://launchermeta.mojang.com/mc/game/version_manifest.json"
+    VERSION_URL=$(curl -sL "${MANIFEST_URL}" | \
+        python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+target = '${MC_VERSION}'
+for v in data['versions']:
+    if v['id'] == target:
+        print(v['url'])
+        break
+")
+
+    if [ -z "${VERSION_URL}" ]; then
+        echo "[✗] Version ${MC_VERSION} not found in Mojang manifest!"
+        exit 1
+    fi
+
+    SERVER_URL=$(curl -sL "${VERSION_URL}" | \
+        python3 -c "import sys, json; d=json.load(sys.stdin); print(d['downloads']['server']['url'])")
+
+    curl -L "${SERVER_URL}" -o "${SERVER_JAR}"
+    echo "[✓] Server JAR downloaded."
+else
+    echo "[✓] Server JAR already cached."
+fi
+
+# ── 3. Write server.properties (first run only) ────────────
+PROPS_FILE="${DATA_DIR}/server.properties"
+if [ ! -f "${PROPS_FILE}" ]; then
+    sed \
+        -e "s|{{WORLD}}|${MC_WORLD}|g" \
+        -e "s|{{PORT}}|${SERVER_PORT}|g" \
+        /home/minecraft/server.properties.template > "${PROPS_FILE}"
+    echo "[✓] server.properties created."
+else
+    echo "[✓] server.properties already exists — skipping."
+fi
+
+# ── 4. Link data dir into working dir ─────────────────────
+# HF Spaces run from /home/minecraft but data lives in /data
+cd "${DATA_DIR}"
+
+# ── 5. Launch! ────────────────────────────────────────────
+echo ""
+echo "[★] Starting Minecraft server..."
+echo ""
+
+exec java \
+    -Xms${MC_MEMORY} \
+    -Xmx${MC_MAX_MEMORY} \
+    -XX:+UseG1GC \
+    -XX:+ParallelRefProcEnabled \
+    -XX:MaxGCPauseMillis=200 \
+    -XX:+UnlockExperimentalVMOptions \
+    -XX:+DisableExplicitGC \
+    -XX:G1NewSizePercent=30 \
+    -XX:G1MaxNewSizePercent=40 \
+    -XX:G1HeapRegionSize=8M \
+    -XX:G1ReservePercent=20 \
+    -XX:G1HeapWastePercent=5 \
+    -XX:G1MixedGCCountTarget=4 \
+    -XX:InitiatingHeapOccupancyPercent=15 \
+    -XX:G1MixedGCLiveThresholdPercent=90 \
+    -XX:G1RSetUpdatingPauseTimePercent=5 \
+    -XX:SurvivorRatio=32 \
+    -XX:+PerfDisableSharedMem \
+    -XX:MaxTenuringThreshold=1 \
+    -Dusing.aikars.flags=https://mcflags.emc.gs \
+    -jar "${SERVER_JAR}" nogui