PlaceholderAPI — إضافة لإدراج بيانات ديناميكية في Minecraft
تستبدل PlaceholderAPI (PAPI) العناصر النائبة في النص بقيم ديناميكية مثل اسم اللاعب أو رصيده. دليل الأوامر والملحقات والإعدادات.
تستبدل PlaceholderAPI (PAPI) العناصر النائبة في النص بقيم ديناميكية مثل اسم اللاعب أو رصيده. دليل الأوامر والملحقات والإعدادات.
PlaceholderAPI — إضافة لإدراج بيانات ديناميكية في Minecraft
إصدار Minecraft الذي تم اختبار المقال وكتابته عليه: 26.1.2
نطاق الإصدارات المدعومة: 1.8.x – 26.1.x
PlaceholderAPI (اختصارًا PAPI) هي إضافة خادم لـ Minecraft تضع قيمًا ديناميكية في النص بدلاً من رموز خاصة. هي بحد ذاتها لا تُخرج شيئًا: إنها محرك يبحث في السطر عن رمز بالشكل %player_name% ويستبدله بالقيمة الفعلية — اسم اللاعب، رصيده، رتبته، عدد اللاعبين المتصلين بالخادم. أما البيانات نفسها فتوفرها وحدات منفصلة — ملحقات، بينما تقوم PAPI فقط بتنفيذ عملية الاستبدال. وبفضل ذلك تقرأ إضافات الدردشة ولوحة النقاط وقائمة التاب والقوائم القيم بنفس الصيغة، دون أي بنية خاصة بها.
صيغة العناصر النائبة
يُكتب العنصر النائب بين علامتي نسبة مئوية: %<розширення>_<параметр>%. الجزء الأول قبل الشرطة السفلية هو اسم الملحق، ويليه المعامل نفسه. على سبيل المثال، %player_name% يُعيد اسم اللاعب، بينما %server_online% يُعيد عدد اللاعبين المتصلين.
لا يعمل الاستبدال إلا حيث تستدعيه الإضافة المستقبِلة نفسها. إذا كانت الإضافة لا تدعم PAPI، تبقى الرموز في رسائلها نصًا عاديًا. يمكن التحقق من عنصر نائب واحد عبر أمر التحليل:
/papi parse me %player_name%
إذا عاد في الرد نص الرمز نفسه وليس قيمة، فهذا يعني أن الملحق المطلوب غير موجود أو أن الإضافة المصدر معطّلة.
الملحقات وeCloud
لا تحتوي PlaceholderAPI في الأساس على أي عنصر نائب — فكلها تأتي من الملحقات. بعضها مدمج في الإضافة المصدر ويسجّل نفسه تلقائيًا عند تشغيل الخادم؛ وبعضها الآخر يكون على شكل ملفات jar منفصلة في سحابة الملحقات (eCloud) ويُثبَّت في المجلد /plugins/PlaceholderAPI/expansions/.
يمكن تنزيل الملحق المطلوب مباشرة من داخل اللعبة:
/papi ecloud download <розширення>
/papi reload
لا يُنزَّل عبر هذا الأمر سوى الملحقات المُتحقَّق منها — وهذا يحمي من الأكواد الضارة. أما الملحقات غير المُتحقَّق منها فتُثبَّت يدويًا: يُنزَّل ملف jar من الموقع ويُوضع في مجلد الملحقات.
الوصول إلى eCloud: إذا كانت الاستضافة أو جدار الحماية يحجب الاتصال الخارجي، فلن يعمل التنزيل عبر الأمر — وسيتوجب عندها إضافة الملحق يدويًا.
الأوامر
تبدأ جميع الأوامر بـ /papi. وهي متاحة افتراضيًا للمشغّلين (operators) فقط؛ وتُمنح صلاحيات فردية عبر عُقد placeholderapi.*.
الأمر | الوظيفة |
| تحليل العناصر النائبة في نص خاص بلاعب |
| تحليل العناصر النائبة العلائقية بين لاعبين |
| عرض الملحقات النشطة |
| معلومات عن ملحق معيّن |
| تنزيل ملحق من السحابة |
| قائمة العناصر النائبة الخاصة بالملحق |
| إعادة تحميل الإضافة والإعدادات |
| إصدار الإضافة المثبتة |
الإعدادات
في ملف config.yml هناك عدد قليل فقط من المعاملات المفيد تعديلها:
المعامل | وظيفته |
| الاتصال بـ eCloud. |
| نص القيم المنطقية للعناصر النائبة؛ يمكن استبداله مثلاً بـ نعم / لا |
| صيغة التاريخ والوقت للعناصر النائبة المقابلة |
| التحقق من تحديثات الإضافة عند التشغيل وإشعار المشغّلين |
بقية القيم في الملف داخلية (حماية الملحقات، وضع الاستبدال في مكونات Adventure، تصحيح الأخطاء) ولا تُغيَّر افتراضيًا.
الخلاصة
توفر PlaceholderAPI صيغة موحّدة لاستبدال البيانات تفهمها مئات الإضافات: فبدلاً من تكامل منفصل مع كل إضافة، يكفي سطر واحد يحتوي على عنصر نائب. وهي ضرورية لمشرفي خوادم Minecraft التي تحتوي على دردشة أو قائمة تاب أو لوحة نقاط أو قائمة تعتمد على بيانات ديناميكية؛ أما في وضع اللاعب الفردي فليس لها أي استخدام.
التثبيت
التثبيت النموذجي يستغرق حوالي 5 دقائق. الخطوات نفسها؛ يختلف فقط المُحمّل والبناء المطابق.
- 1Stop your Minecraft server.
- 2Drop the plugin .jar into the server /plugins folder.
- 3Start the server once so the plugin generates its config files.
- 4Edit /plugins/<name>/config.yml as needed, then run /reload confirm or restart.
