دليل

كيف تحدّث plugin إلى إصدار Minecraft جديد

حُدّث في 18 أكتوبر 2026

عندما ينتقل خادمك إلى إصدار Minecraft جديد، تستمر كثير من الـ plugins في العمل دون تغيير، لأن Bukkit API مستقرة. وأخرى تتوقف عن التحميل أو تتعطل بطرق صغيرة. إذا لم يحدّث المؤلف plugin ما وكان لديك كوده المصدري، يمكنك تحديثه بنفسك: إليك ما الذي يتغير وبأي ترتيب.

صفه كما يجب أن يعمل على الإصدار الجديد.

ولّد هذا بـ Codexe

خطوة بخطوة

  1. 1.جرّب ملف .jar القديم أولاً

    ضعه على خادم تجريبي بالإصدار الجديد واقرأ وحدة التحكم. إذا حُمّل وعمل، فقد لا تحتاج إلى تغيير أي شيء.

  2. 2.غيّر اعتمادية الـ API

    في pom.xml أو build.gradle، اضبط paper-api أو spigot-api على الإصدار الجديد.

  3. 3.حدّث api-version وJava

    اضبط api-version في plugin.yml (مثل '1.21') وجمّع لإصدار Java الذي يحتاجه الإصدار الجديد: Java 17 قبل 1.20.5، وJava 21 منذ 1.20.5، وJava 25 لـ 26.x.

  4. 4.أصلح ما لم يعد يُجمَّع

    ابنِ وراجع الأخطاء: مواد أُعيدت تسميتها، ودوالّ حُذفت، وفئات أحداث تغيّرت. يسردها المجمِّع مع الملف والسطر.

  5. 5.حدّث الاعتماديات

    الـ plugins التي يستخدمها الـ plugin الخاص بك (Vault وPlaceholderAPI وProtocolLib وWorldGuard) تحتاج هي أيضاً إلى إصدارات تدعم إصدار Minecraft الجديد، في ملف البناء وعلى الخادم.

  6. 6.اختبر على الإصدار الجديد

    حمّله على خادم بالإصدار الجديد مع الـ plugins نفسها، وجرّب كل أمر وميزة، لا الإقلاع فقط.

ما الذي يتعطل عادةً

  • أسماء المواد والـ enums: أعاد تحديث 1.13 تسمية معظم العناصر والكتل؛ والإصدارات اللاحقة تضيف بعضها أو تعيد تسميته أو تحذفه. الكود الذي يستخدم الأسماء القديمة أو المعرّفات الرقمية يفشل.
  • حذف الدوالّ المهملة: الدوالّ الموسومة كمهملة لعدة إصدارات تختفي في النهاية.
  • بيانات العناصر: منذ 1.20.5، استُبدلت بيانات NBT للعناصر بمكوّنات البيانات. الـ plugins التي تعدّل NBT العناصر مباشرة تحتاج إلى إعادة كتابة ذلك الجزء؛ أما واجهة ItemMeta API العادية فتستمر في العمل.
  • NMS والانعكاس (reflection): الكود الذي يستخدم فئات الخادم الداخلية يتعطل في كل إصدار تقريباً. استبدله بالـ API حيثما أمكن، أو بمكتبة مثل ProtocolLib.
  • إصدارات المكتبات: المكتبات المضمّنة المبنية لإصدار Java أقدم قد تفشل على الجديد.

التحديث عبر إصدارات كثيرة

الانتقال من 1.8 أو 1.12 إلى 1.21 أقرب إلى إعادة كتابة الأجزاء التي تتعامل مع العناصر والكتل والجسيمات منه إلى تحديث. افعل ذلك دفعة واحدة على الـ API الجديد، لا إصداراً بعد إصدار، وتوقّع أن تحتاج ملفات الإعدادات أيضاً إلى أسماء مواد جديدة.

إذا كان على الـ plugin دعم عدة إصدارات في آن واحد، فجمّعه على أقدم إصدار تدعمه وتجنّب الـ API المضاف لاحقاً، أو استخدم بناءً منفصلاً لكل إصدار.

مع Codexe

في Pro وما فوقها يمكنك استيراد الكود المصدري للـ plugin كملف ZIP وأن تطلب مثلاً: "هذا plugin الخاص بي لـ Paper 1.20.4. حدّثه إلى Paper 1.21.4". يقرأ Codexe إصدار Minecraft من ملف البناء، ويبني بإصدار Java الذي يحتاجه ذلك الإصدار، ويصلح أخطاء التجميع باستخدام التواقيع الحقيقية للـ API الذي يبني عليه. ولـ plugin صنعته على Codexe، اطلب الإصدار الجديد في محادثة المشروع.

التجميع يثبت أن الـ plugin يُبنى على الـ API الجديد. ثم جرّبه على خادم تجريبي، لأن تغيّرات السلوك بين الإصدارات لا تظهر كأخطاء تجميع.

أسئلة

هل يمكنني تحديث plugin دون كوده المصدري؟

ليس بشكل موثوق. فك تجميع ملف .jar يعطي كوداً يصعب صيانته وقد يخالف ترخيص المؤلف. ابحث أولاً عن نسخة محدّثة أو فرع تتم صيانته.

هل يعمل plugin لإصدار 1.21.1 على 1.21.4؟

غالباً نعم، ضمن الإصدار الرئيسي نفسه، ما لم يستخدم NMS أو API تغيّر. اختبره قبل أن تعتمد عليه.

لماذا يقول الخادم "Unsupported API version"؟

هذه هي الحالة المعاكسة: الـ plugin يستهدف API أحدث من الخادم. ابنِه لإصدار خادمك أو حدّث الخادم.

أعد بناء plugin لإصدارك

يُفتح هذا الوصف جاهزاً للإرسال:

“نسخة Paper 1.21.4 من plugin الـ Spigot 1.12.2 الخاص بي TreeFeller: كسر الجذع السفلي لشجرة بالفأس يكسر الشجرة كلها، ويستهلك المتانة لكل جذع، ويعمل مع كل أنواع الخشب في 1.21 بما فيها cherry وmangrove، والتبديل بـ /treefeller، والإعدادات في config.yml.”

ولّد هذا بـ Codexe
كيف تحدّث plugin لـ Minecraft إلى إصدار جديد | Codexe