طريقة صناعة تعديل ماينكرفت: بدءاً من مشروع Fabric وتكود Java وحتى بناء ملف JAR
يعتمد هذا الدليل على إصدار Minecraft Java Edition 26.2 وFabric لإنشاء تعديل يقوم بطبع سجل (Log) عند التشغيل الأول. هذا مثال تمهيدي يوضح النقطة التي يتم فيها التعرف على ملف التعديل بواسطة محمل الألعاب وتنفيذ كود Java الذي كتبته. يختلف الهيكل عن إضافات Bedrock (Bedrock Add-ons) ومشاريع Forge أو NeoForge، لذا لا تقم بخلطها داخل مشروع واحد.
1. تجهيز بيئة التطوير
ترشد وثائق Fabric الحالية 26.2 إلى استخدام JDK 25. بدلاً من تثبيت بيئة تشغيل Java فقط، قم بتثبيت JDK الخاص بالتطوير وقم بإعداد IntelliJ IDEA أو VS Code. تحقق من إصدار Java الفعلي قيد الاستخدام في الطرفية (Terminal) باستخدام الأمر أدناه. يجب أن يشير مشروع SDK الخاص بـ IDE وGradle JVM إلى نفس الإصدار أيضاً. إذا كنت تريد الإنشاء لإصدار أقدم مثل 1.21.1، فقم بتغيير اختيار الإصدار في أعلى المستند وإصدار المُنشئ معاً، واتبع متطلبات JDK لذلك الإصدار.
java -version
javac -version
2. إنشاء مشروع من منشئ Fabric
- افتح منشئ قوالب Fabric الرسمي (Template Mod Generator).
- حدد اسم التعديل (Mod Name) باسم TroubleMaker Hello، ومعرف التعديل (Mod ID) باسم tmhello، واسم الحزمة (Package Name) باسم com.ascgame.tmhello.
- اضبط إصدار ماينكرفت على 26.2. لست بحاجة إلى إضافة خيارات متقدمة مثل Kotlin أو إنشاء البيانات المنفصلة في المثال الأول.
- قم بتنزيل ملف ZIP وفك ضغطه في مسار بسيط مثل C:/Projects/TMHello. يتم تحديد مجلد المشروع وفقاً لنظام التشغيل الفعلي لديك.
- افتح build.gradle أو جذر المشروع في IDE وانتظر حتى ينتهي استيراد Gradle. احتفظ بإصدارات Loader وLoom وAPI التي حددها المُنشئ كما هي.
3. فهم وظيفة الملفات
src/main/java مخصص لكود Java المشترك، وsrc/main/resources/fabric.mod.json مخصص لمعرف التعديل، فئة الدخول (Entry class)، وإعلانات التبعية، وgradle.properties مخصص للإصدار وإعدادات المشروع. اعتماداً على المُنشئ، قد يتم تقسيم كود العميل إلى src/client/java. يعدل هذا المثال كود التهيئة المشترك فقط. لا تقم بحذف جميع ملفات الإعدادات عشوائياً أو الكتابة فوق إعدادات الإصدارات الأخرى من الإنترنت.
4. كتابة فئة التهيئة الخاصة بك
ابحث عن ملف تنفيذ ModInitializer المشترك الذي تم إنشاؤه وقم بتعديله ليصبح بالشكل التالي. إذا قمت بتغيير اسم الملف إلى TMHello.java، فقم مطابقة مجلد الحزمة (Package) واصطلاح اسم الفئة أيضاً. نظراً لأنه يتم استخدام سجلات SLF4J، يمكنك التحقق مما إذا تمت التهيئة دون واجهة برمجة تطبيقات تسجيل العناصر التي تتاثر بسهولة بالتغيير في إصدارات اللعبة الأخرى.
package com.ascgame.tmhello;
import net.fabricmc.api.ModInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class TMHello implements ModInitializer {
public static final String MOD_ID = "tmhello";
private static final Logger LOG = LoggerFactory.getLogger(MOD_ID);
@Override
public void onInitialize() {
LOG.info("TroubleMaker: my first Fabric mod is ready.");
}
}تأكد من أن entrypoints.main يشير إلى الاسم الكامل للفئة المذكورة أعلاه مع الاحتفاظ بالمحتويات الأخرى لملف fabric.mod.json. أدناه هو الجزء الذي يجب التحقق منه وليس الملف بأكمله. لا تستبدل إعدادات mixins أو العميل الحالية بالكامل.
{
"entrypoints": {
"main": ["com.ascgame.tmhello.TMHello"]
}
}
5. تشغيل التطوير وبناء الملف النهائي
- في جذر المشروع، قم بتنفيذ gradlew.bat runClient لنظام Windows، أو ./gradlew runClient لنظام macOS/Linux.
- ابحث عن عبارة TroubleMaker في وحدة تحكم عميل التطوير (Client console) أو في run/logs/latest.log. هذا مثال يتم طباعته مرة واحدة أثناء التهيئة قبل الدخول إلى العالم.
- قم إنهاء اللعبة وإنشاء ملف التوزيع باستخدام gradlew.bat build لنظام Windows أو ./gradlew build لنظام macOS/Linux.
- تحقق من ملف JAR العادي للتوزيع في build/libs. لا تستخدم الملفات المخصصة للتطوير التي تحمل اللاحقة sources أو dev كملفات توزيع عادية.
- ضع ملف JAR في مجلد mods الخاص بنسخة Fabric منفصلة لنفس إصدار ماينكرفت. إذا كان هناك Fabric API ضمن التبعيات التي تم إنشاؤها، فقم بتثبيته بما يتطابق مع نفس الإصدار.
- قم بالتشغيل باستخدام المشغل الفعلي (Launcher) وتأكد من طباعة نفس العبارة في logs/latest.log الخاصة بالنسخة.
6. الأخطاء الشائعة وطرق الإصلاح
بالنسبة لخطأ إصدار ملف فئة غير مدعوم (Unsupported class file version)، تحقق من إصدار Java أولاً، وبالنسبة لخطأ تحميل فئة الدخول، تحقق من عدم تطابق الحزمة (Package) أو اسم الفئة أو نقاط الدخول (Entrypoints). إذا وضعته في مجلد mods وبقي صامتاً، فتأكد مما إذا كنت قد وضعته في مثيل مشغل آخر. لا يضيف هذا المثال بيانات حفظ، لذا يمكنك إنهاء اللعبة وإزالة ملف JAR للمقارنة. عند إضافة عناصر أو كتل لاحقاً، تابع قراءة وثيقة Fabric First Item الخاصة بالإصدار المستهدف، وقم بملاءمة مسار الملف وواجهة برمجة تطبيقات التسجيل مع ذلك الإصدار.
7. المعلومات التي يجب تضمينها عند المشاركة
قم بتدوين معرف التعديل (Mod ID)، وإصدار ماينكرفت المدعوم، وشروط Loader وFabric API، ومتطلبات JDK، ووظائف المثال، وطريقة الإزالة في ملف README. قم بالتمييز بين الكود الأصلي وملف JAR للتوزيع، ولا تقم بتضمين اللعبة الأساسية أو ملفات تعديل خاصة بمصممين آخرين. بالنسبة للإصدار الأول، قم بتوزيع التعديل بعد إضافة رقم إصدار مثل 1.0.0 بعد التأكد من أن السجل يتم طباعته في المشغل العادي الفعلي.
المستند الأصلي ومعايير التحقق
هذا دليل تمهيدي كتبه فريق تشغيل TroubleMaker بعد التحقق من وثائق المُنشئ والأدوات الرسمية في 7 أكتوبر 2026. الكود والرسوم البيانية هي أمثلة مخصصة للشرح ولا تمثل نتائج التحقق من اللعب الفعلي لتلك اللعبة على هذا الخادم. يرجى النشر بعد التحقق في حفظ اختبار منفصل باستخدام الإصدار الموضح في النص. قارن أحدث الإصدارات والتبعيات لكل أداة من المصدر أدناه:
ترجمة آلية من Gemini · يُحفظ النص الأصلي ومنطقة المصدر.
اللغة الأصلية · ko
마인크래프트 모드 만드는 법: Fabric 프로젝트·Java 코드·JAR 빌드까지
이 공략은 Minecraft Java Edition 26.2와 Fabric을 기준으로 첫 실행 때 로그를 출력하는 모드를 만듭니다. 모드 파일이 로더에 인식되고 내가 쓴 Java 코드가 실행되는 지점까지 따라가는 입문 예제입니다. Bedrock 애드온, Forge·NeoForge 프로젝트와 구조가 다르므로 한 프로젝트 안에 섞지 마세요.
[1. 개발 환경 준비]
Fabric의 현재 26.2 문서는 JDK 25를 안내합니다. Java 실행 환경만 설치하는 대신 개발용 JDK를 설치하고 IntelliJ IDEA 또는 VS Code를 준비합니다. 터미널에서 아래 명령으로 실제 사용 중인 Java를 확인하세요. IDE의 Project SDK와 Gradle JVM도 같은 버전을 가리켜야 합니다. 1.21.1 등 구버전으로 만들려면 문서 상단 버전 선택과 생성기 버전을 함께 바꾸고 그 버전의 JDK 요구 사항을 따릅니다.
```sh
java -version
javac -version
```
[image:conditions]
[2. Fabric 생성기에서 프로젝트 만들기]
1. Fabric 공식 Template Mod Generator를 엽니다.
2. Mod Name은 TroubleMaker Hello, Mod ID는 tmhello, Package Name은 com.ascgame.tmhello로 지정합니다.
3. Minecraft 버전을 26.2로 맞춥니다. Kotlin·별도 데이터 생성 등 고급 옵션은 첫 예제에서 추가하지 않아도 됩니다.
4. ZIP을 내려받아 C:/Projects/TMHello 같은 단순한 경로에 압축을 풉니다. 프로젝트 폴더는 실제 운영체제에 맞춰 정합니다.
5. IDE에서 build.gradle 또는 프로젝트 루트를 열고 Gradle 가져오기가 끝날 때까지 기다립니다. 생성기가 정한 Loader·Loom·API 버전을 그대로 보관합니다.
[3. 파일이 하는 일을 이해하기]
src/main/java는 공통 Java 코드, src/main/resources/fabric.mod.json은 모드 ID·진입 클래스·의존성 선언, gradle.properties는 버전과 프로젝트 설정입니다. 생성기에 따라 클라이언트 코드가 src/client/java로 나뉠 수 있습니다. 이 예제는 공통 초기화 코드만 바꿉니다. 임의로 모든 설정 파일을 지우거나 인터넷의 다른 버전 설정을 덮어쓰지 마세요.
[4. 내 초기화 클래스를 작성하기]
생성된 공통 ModInitializer 구현 파일을 찾고 아래 구조로 수정합니다. 파일명을 TMHello.java로 바꾸었다면 package 폴더와 클래스 이름도 일치시킵니다. SLF4J 로그를 사용하므로 다른 게임 버전에서 바뀌기 쉬운 아이템 등록 API 없이 초기화 여부를 확인할 수 있습니다.
```java
package com.ascgame.tmhello;
import net.fabricmc.api.ModInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class TMHello implements ModInitializer {
public static final String MOD_ID = "tmhello";
private static final Logger LOG = LoggerFactory.getLogger(MOD_ID);
@Override
public void onInitialize() {
LOG.info("TroubleMaker: my first Fabric mod is ready.");
}
}
```
fabric.mod.json의 다른 내용을 유지한 채 entrypoints.main이 위 클래스의 전체 이름을 가리키는지 확인합니다. 아래는 전체 파일이 아니라 확인할 부분입니다. 기존 mixins나 client 설정까지 통째로 대체하지 마세요.
```json
{
"entrypoints": {
"main": ["com.ascgame.tmhello.TMHello"]
}
}
```
[image:request]
[5. 개발 실행과 최종 파일 빌드]
1. 프로젝트 루트에서 Windows는 gradlew.bat runClient, macOS/Linux는 ./gradlew runClient를 실행합니다.
2. 개발 클라이언트 콘솔 또는 run/logs/latest.log에서 TroubleMaker 문구를 검색합니다. 월드에 들어가기 전 초기화 때 한 번 출력되는 예제입니다.
3. 게임을 종료하고 Windows는 gradlew.bat build, macOS/Linux는 ./gradlew build로 배포 파일을 만듭니다.
4. build/libs에서 일반 배포 JAR을 확인합니다. 이름에 sources 또는 dev가 붙은 개발용 파일을 일반 배포본으로 사용하지 않습니다.
5. 같은 Minecraft 버전의 별도 Fabric 인스턴스 mods 폴더에 JAR을 넣습니다. 생성된 의존성에 Fabric API가 있으면 같은 버전에 맞춰 설치합니다.
6. 실제 런처로 실행하고 인스턴스의 logs/latest.log에 같은 문구가 찍히는지 확인합니다.
[6. 자주 생기는 오류와 복구]
Unsupported class file version은 Java 버전, 진입 클래스 로딩 오류는 package·클래스명·entrypoints 불일치부터 확인합니다. mods 폴더에 넣었는데 조용하면 다른 런처 인스턴스에 넣었는지도 확인하세요. 이 예제는 세이브 데이터를 추가하지 않으므로 게임을 종료하고 JAR을 제거해 비교할 수 있습니다. 이후 아이템이나 블록을 추가할 때는 대상 버전의 Fabric First Item 문서를 이어서 읽고, 파일 경로와 등록 API를 그 버전에 맞춥니다.
[image:contact]
[7. 공유할 때 함께 적을 정보]
모드 ID, 지원 Minecraft 버전, Loader·Fabric API 조건, JDK 요구 사항, 예제 기능과 제거 방법을 README에 적습니다. 코드 원본과 배포 JAR을 구분하고 게임 본체나 다른 제작자의 모드 파일을 포함하지 않습니다. 최초 버전은 로그가 실제 일반 런처에서 출력되는지 확인한 뒤 1.0.0처럼 버전을 붙여 배포하세요.
[원본 문서와 확인 기준]
2026년 10월 7일 제작자·공식 도구 문서를 확인해 TroubleMaker 운영팀이 작성한 입문 공략입니다. 코드와 도식은 설명을 위한 자체 예제이며 이 서버에서 해당 게임의 실제 플레이를 검증한 결과는 아닙니다. 본문에 명시한 버전으로 별도 테스트 세이브에서 확인하고 배포하세요. 도구별 최신 버전·의존성은 아래 원본에서 대조합니다.
Fabric 개발 환경
Fabric 프로젝트 생성
Fabric 모드 빌드
Fabric 공식 생성기
تعليقات 1
제시해주신 가이드에서 언급된 JDK 25와 같은 특정 Java 버전 요구 사항이, 프로젝트 생성 시 선택하는 마인크래프트 버전마다 다르게 적용되는 것인가요? 아니면 Fabric 로더 자체의 업데이트 주기에 따라 결정되는 것인지 궁금합니다.