إنشاء أول مود Fabric عملي: إعداد المشروع وإضافة عنصر ووصفة وترجمة

هذا المقال مخصص لمن يريد نتيجة ملموسة بدل شرح نظري. سنبني مودًا بسيطًا يضيف عنصرًا اسمه “Ignis Shard”، ثم نربطه باسم عربي، ونضعه في Creative Tab، ونضيف وصفة crafting. أسماء الدوال تختلف حسب إصدار Minecraft والقوالب الحديثة، لذلك اعتبر الكود هيكلًا تعليميًا وراجع صفحة الإصدار التي تستخدمها قبل اللصق الحرفي.

قبل البدء: ما الذي تحتاجه؟

تحتاج Minecraft: Java Edition، وJDK مناسبًا للإصدار المستهدف، وIDE، وGit اختياريًا، ومشروع Fabric مولّدًا من القالب الرسمي. صفحة Fabric تذكر أن المبتدئ يحتاج فهمًا أساسيًا لـJava والبرمجة الكائنية، كما تشرح أن Gradle يبني المشروع وأن Loom يجهز بيئة التطوير [1]. لا تحمل نسخة عشوائية من API ثم تحاول تعويض التعارض بتغيير أرقام عشوائية.

1. إنشاء المشروع

افتح Fabric Template Mod Generator، اختر اسم المود وmod id وpackage name وإصدار Minecraft، ثم فعّل Data Generation إذا كنت تريد توليد ملفات recipes أو models لاحقًا. استخدم package مثل com.ignisstudios.ignisshard، واجعل mod id مثل ignis_shard حسب قواعد القالب. تذكّر المعرّف؛ فهو يظهر في مسارات الموارد وفي namespace الوصفات.

بعد التنزيل، فك الضغط في مسار بسيط مثل C:\Projects\IgnisShard، ثم افتح المشروع في IDE وانتظر مزامنة Gradle. توصي وثائق Fabric بتجنب المسارات ذات المسافات والأحرف غير ASCII، وتطلب تعديل gradle.properties وfabric.mod.json لبيانات مشروعك [2].

2. افحص الملفات قبل تعديلها

3. سجّل العنصر

أنشئ صنفًا للتسجيل بدل وضع الثوابت في كل مكان. في القوالب الحديثة قد ترى أسماء API مختلفة، لكن الفكرة ثابتة: namespace واضح، identifier ثابت، وItem Properties متوافقة مع الإصدار.

public final class ModItems {
    public static final Item IGNIS_SHARD = Registry.register(
        Registries.ITEM,
        Identifier.fromNamespaceAndPath(IgnisShard.MOD_ID, "ignis_shard"),
        new Item(new Item.Properties())
    );

    public static void registerModItems() {
        IgnisShard.LOGGER.info("Registering items for " + IgnisShard.MOD_ID);
    }
}

في نسخة أخرى قد يكون اسم إنشاء Identifier مختلفًا؛ لا تعتبر اختلاف الاسم فشلًا في الفكرة. المهم أن يستخدم العنصر namespace المود لا namespace اللعبة، لأن namespace يمنع التصادم ويجعل ملفاته قابلة للتتبع.

4. أضف العنصر إلى تبويب Creative

العنصر المسجل لا يظهر تلقائيًا في كل واجهة. استخدم API الخاص بالتبويبات في إصدارك، أو اتبع مثال القالب. اختبر ظهور العنصر من قائمة Creative، ثم جرّبه في Survival. لا تعتمد على أمر يعطيك العنصر فقط؛ فالوصفة والـtranslation والـmodel هي التي تثبت أن الحزمة مكتملة.

5. ملف النموذج

أنشئ المسار التالي، مع استبدال namespace إذا كان مختلفًا:

src/main/resources/assets/ignis_shard/models/item/ignis_shard.json

محتوى النموذج عادة يشير إلى نموذج item الأساسي وصورة texture. ضع الصورة في مسار متطابق تحت textures/item. مشكلة “العنصر يظهر كصندوق بنفسجي وأسود” غالبًا تعني أن مسار texture أو model غير مطابق لحالة الأحرف.

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "ignis_shard:item/ignis_shard"
  }
}

6. الترجمة العربية والإنجليزية

أضف ملفين لغة على الأقل حتى لا تظهر مفاتيح داخل اللعبة:

src/main/resources/assets/ignis_shard/lang/en_us.json
src/main/resources/assets/ignis_shard/lang/ar_sa.json

استخدم key يبدأ بـitem. ثم namespace ثم id. الاسم العربي طويل أو قصير حسب تصميمك، لكن حافظ على نفس key في الملفين:

{
  "item.ignis_shard.ignis_shard": "Ignis Shard"
}

7. أضف وصفة crafting

الوصفة تحتاج pattern وkey وresult بصيغة يقرأها إصدار اللعبة. إذا كان قالبك يستخدم result object يتضمن count، اتبع المثال الذي يولده القالب أو توثيق الإصدار. لا تخلط بين id العنصر واسم الملف:

{
  "type": "minecraft:crafting_shaped",
  "pattern": ["A A", " B ", "A A"],
  "key": {
    "A": {"item": "minecraft:amethyst_shard"},
    "B": {"item": "minecraft:iron_ingot"}
  },
  "result": {
    "id": "ignis_shard:ignis_shard",
    "count": 1
  }
}

لاحظ أن بعض الإصدارات تستخدم صيغة مختلفة للـresult. هذه ليست مشكلة في التصميم؛ إنها إشارة إلى ضرورة تثبيت إصدار مستهدف وقراءة مثال مطابق له.

8. اختبر من الصفر

1. شغل عميل التطوير وأنشئ عالمًا جديدًا.
2. ابحث عن العنصر في Creative.
3. افتح ملف اللغة وتأكد من الاسم.
4. نفّذ الوصفة في crafting table.
5. أعد تشغيل اللعبة وتحقق من عدم ظهور خطأ بعد إغلاق العالم.
6. شغّل ./gradlew build ثم جرّب ملف JAR الناتج في تثبيت Fabric نظيف.

أخطاء شائعة وحلول سريعة

بعد نجاح هذا المثال، أضف خاصية واحدة فقط: اسمًا لامعًا، صوتًا، أو استخدامًا عند النقر. التدرج يجعل تتبع الخطأ ممكنًا ويعطيك أساسًا يصلح لمود حقيقي.

9. اجعل المثال قابلًا للتوسعة

بعد أن يظهر العنصر ويعمل، أضف tooltip أو تأثيرًا صغيرًا، لكن لا تضف كل شيء في commit واحد. أنشئ commit للعنصر، وآخر للوصفة، وآخر للترجمة إن كنت تعمل مع فريق. هذا يجعل الرجوع إلى آخر نقطة سليمة سهلًا، ويجعل مراجعة الكود أسرع.

تنظيم أسماء المشروع

استخدم اسمًا موحدًا للـid في Java وresources وJSON. لا تكتب IgnisShard في مكان وignis-shards في مكان آخر. اختلاف حرف واحد كافٍ لإنتاج ملف صحيح شكليًا لا تستخدمه اللعبة. راجع أيضًا أن اسم texture لا يحتوي امتداد PNG داخل JSON.

10. اختبار الوصفة مثل اللاعب

لا تختبر الوصفة بأمر يمنحك المواد فقط. اجمع المواد من Survival، جرّب ترتيبًا خاطئًا، أخرج النتيجة، أعد فتح العالم، ثم جرّب الوصفة في server محلي إذا كان المود يستهدف اللعب الجماعي. اختبر اللغة العربية والإنجليزية، وتأكد من أن الاسم لا يخرج خارج نافذة inventory.

عندما تنتهي، اكتب README من خمس فقرات: الفكرة، الإصدار، المتطلبات، التثبيت، والمشاكل المعروفة. هذا يحول المثال من تجربة شخصية إلى أول مشروع يمكن لشخص آخر فهمه.

مراجع موثوقة

راجِع هذه الصفحات الرسمية عند اختلاف الإصدار أو تغيّر أسماء الملفات؛ توثيق اللعبة والمنصة يتغير مع الزمن.

1. Fabric Documentation — Introduction to Fabric and Modding
2. Fabric Documentation — Creating a Project
3. Fabric Documentation — Developer Guides