إضافة Minecraft PlaceholderAPI

🔌 حول PlaceholderAPI

PlaceholderAPI هو إضافة Minecraft توفّر نظام placeholders مركزيًا ومنظومة توسعات (eCloud). يتيح ذلك للإضافات الأخرى قراءة واستبدال آلاف الـ placeholders الديناميكية (بيانات اللاعب، قيم الاقتصاد، القيم الخاصة بالإضافات، إلخ) دون الحاجة إلى تكامل مباشر أو اعتمادات ثقيلة.

🎯 الهدف

تحل الإضافة مشكلة صعوبة التكامل بين الإضافات عبر توفير API واحد وقابل للتوسعة للـ placeholders. ينشر مطورو الإضافات "توسعات" توفّر placeholders مسماة؛ ويثبت مديرو الخادم هذه التوسعات حتى تتمكن الإضافات التي تعرض بيانات الخادم (لوحات النتائج، الدردشة، الهولوغرامات، الواجهات الرسومية) من إظهار البيانات الحية باستخدام صياغة موحدة.

⚙️ الميزات

• API أساسي لتحليل placeholders حتى تتمكن الإضافات الأخرى من الارتباط به.
• نظام التوسعات: توسعات مستقلة أو توسعات مدمجة داخل الإضافات.
• eCloud (سحابة التوسعات) للعثور على التوسعات الموثوقة وتنزيلها داخل اللعبة.
• أوامر إدارة أثناء التشغيل لعرض التوسعات وتسجيلها وإلغاء تسجيلها وإعادة تحميلها.
• أوامر debug/parse لتقييم placeholders للاعب أو بث النتائج، وهي مفيدة لاستكشاف الأخطاء وإصلاحها.
• أدوات مثل أمر dump لمشاركة التوسعات المثبتة وحالة الإضافة عند طلب الدعم.

🧩 لمن هذه الإضافة

• مديرو الخوادم الذين يحتاجون إلى نص ديناميكي موحّد عبر عدة إضافات (لوحات النتائج، قائمة اللاعبين، الهولوغرامات، الواجهات الرسومية).
• مطورو الإضافات الذين يريدون إتاحة أو استخدام placeholders دون فرض اعتمادات ثقيلة.
• خوادم Survival وminigame وnetwork التي تجمع العديد من الإضافات وتحتاج إلى صياغة placeholders متسقة.

🏗️ أمثلة على الاستخدام

• يثبت خادم توسعة Vault بحيث يمكن استخدام placeholders الخاصة بالاقتصاد مثل رصيد اللاعب في إضافات لوحة النتائج والدردشة.
• يقوم مدير بتنزيل توسعة خاصة بإضافة من eCloud بحيث يمكن لإضافة هولوغرام عرض بيانات الهدف مباشرة.
• يوفّر مطور بيانات الإضافة عبر PlaceholderExpansion حتى تتمكن خوادم أخرى من عرض تلك البيانات دون الاعتماد على الإضافة مباشرة.

⌨️ الأوامر

(ملاحظة: الأوامر أعلاه موثقة في مرجع الأوامر الرسمي لـ PlaceholderAPI. لا تُدرج نودات الصلاحية للأوامر الفردية في التوثيق المشار إليه.)

⚙️ التثبيت

📥 الإعداد

• نزّل ملف jar الرسمي لـ PlaceholderAPI وضعه في مجلد plugins/ الخاص بالخادم.
• شغّل الخادم أو أعد تشغيله وتأكد من أن PlaceholderAPI يتم تحميله في وحدة التحكم.
• ثبّت التوسعات إما بوضع ملفات jar الخاصة بها في plugins/PlaceholderAPI/expansions/ أو باستخدام أوامر eCloud داخل اللعبة (للتوسعات الموثوقة).

📦 الاعتمادات

• لا يحتاج PlaceholderAPI نفسه إلى اعتماد عام على إضافة أخرى ليعمل. بعض الـ placeholders التي توفرها التوسعات تعتمد على إضافات أخرى (مثل توسعة تعرض قيم الاقتصاد، والتي ستحتاج إلى إضافة الاقتصاد المناسبة). تعتمد هذه المتطلبات على التوسعة المحددة.

🧠 ملاحظات تقنية

• يتم توفير PlaceholderAPI للخوادم المبنية على Spigot ويُستخدم أيضًا بشكل شائع على Paper. توفّر هذه الإضافة API للمطورين لتسجيل PlaceholderExpansions.
• يمكن توزيع التوسعات كملفات jar مستقلة أو مضمّنة داخل إضافات أخرى؛ وغالبًا ما تُثبَّت التوسعات المستقلة في plugins/PlaceholderAPI/expansions/.
• تتيح ميزة eCloud اكتشاف التوسعات الموثوقة وتنزيلها داخل اللعبة؛ ويجب أن تسمح الخوادم باتصالات HTTPS الصادرة حتى تعمل تنزيلات eCloud.
• تتضمن الإضافة أوامر debug وparsing لمساعدة المديرين على التحقق من أن placeholders تُحل بشكل صحيح.

🤝 متى تكون هذه الإضافة مفيدة

إذا كان خادمك يستخدم عدة إضافات تحتاج إلى عرض بيانات ديناميكية مشتركة بين الإضافات (الدردشة، التاب، الهولوغرامات، لوحات النتائج أو الواجهات الرسومية)، فإن PlaceholderAPI مفيدة لأنها تركز حل الـ placeholders وتتيح لك إضافة دعم لإضافات أخرى عبر توسعات معيارية دون تعديل كل إضافة مستهلكة.