วิธีสร้างม็อด Minecraft: โปรเจกต์ Fabric, โค้ด Java และการบิวด์ไฟล์ JAR
คู่มือนี้อ้างอิงจาก Minecraft Java Edition 26.2 และ Fabric เพื่อสร้างม็อดที่จะแสดงผลบันทึก (Log) ในการรันครั้งแรก โดยเป็นตัวอย่างระดับเริ่มต้นเพื่อให้ทำตามจนถึงจุดที่ไฟล์ม็อดถูกจดจำโดยตัวโหลด (Loader) และโค้ด Java ที่คุณเขียนถูกทำงาน เนื่องจากโครงสร้างมีความแตกต่างจาก Bedrock Add-ons และโปรเจกต์ Forge / NeoForge จึงไม่ควรนำมารวมกันในโปรเจกต์เดียว
1. การเตรียมสภาพแวดล้อมการพัฒนา
เอกสารปัจจุบันของ Fabric สำหรับเวอร์ชัน 26.2 แนะนำให้ใช้ JDK 25 แทนที่จะติดตั้งเพียงสภาพแวดล้อมรันไทม์ Java ให้ติดตั้ง JDK สำหรับพัฒนาและเตรียม IntelliJ IDEA หรือ VS Code ให้พร้อม ตรวจสอบ Java ที่ใช้งานจริงในเทอร์มินัลด้วยคำสั่งด้านล่าง Project SDK ของ IDE และ Gradle JVM ก็ต้องชี้ไปที่เวอร์ชันเดียวกันด้วย หากต้องการสร้างสำหรับเวอร์ชันเก่าเช่น 1.21.1 ให้เปลี่ยนการเลือกเวอร์ชันที่ด้านบนของเอกสารและเวอร์ชันของตัวสร้าง (Generator) ไปพร้อมกัน แล้วปฏิบัติตามข้อกำหนด JDK ของเวอร์ชันนั้น
java -version
javac -version
2. การสร้างโปรเจกต์ใน Fabric Generator
- เปิดเว็บไซต์อย่างเป็นทางการของ Fabric Template Mod Generator
- กำหนด Mod Name เป็น TroubleMaker Hello, Mod ID เป็น tmhello และ Package Name เป็น com.ascgame.tmhello
- ตั้งค่าเวอร์ชัน Minecraft เป็น 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 สำหรับประกาศ Mod ID, คลาสเริ่มต้น (Entry class) และการพึ่งพา, ส่วน gradle.properties สำหรับตั้งค่าเวอร์ชันและโปรเจกต์ ขึ้นอยู่กับตัวสร้าง โค้ดฝั่งไคลเอนต์อาจถูกแยกไปไว้ที่ src/client/java ตัวอย่างนี้จะแก้ไขเฉพาะโค้ดเริ่มต้นทั่วไปเท่านั้น ห้ามลบไฟล์ตั้งค่าทั้งหมดตามอำเภอใจหรือเขียนทับด้วยการตั้งค่าเวอร์ชันอื่นจากอินเทอร์เน็ต
4. การเขียนคลาสเริ่มต้นของคุณ
ค้นหาไฟล์อิมปรีเมนต์ ModInitializer ทั่วไปที่ถูกสร้างขึ้น และแก้ไขให้เป็นโครงสร้างด้านล่าง หากคุณเปลี่ยนชื่อไฟล์เป็น TMHello.java ให้ตรวจสอบว่าโฟลเดอร์แพ็กเกจและชื่อคลาสตรงกันด้วย เนื่องจากมีการใช้ SLF4J log คุณจึงสามารถตรวจสอบการเริ่มต้นทำงานได้โดยไม่ต้องใช้ API ลงทะเบียนไอเทมที่มีโอกาสเปลี่ยนแปลงได้ง่ายในแต่ละเวอร์ชันของเกม
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 ที่มีอยู่เดิมทั้งหมด
{
"entrypoints": {
"main": ["com.ascgame.tmhello.TMHello"]
}
}
5. การรันเพื่อพัฒนาและการบิวด์ไฟล์ขั้นสุดท้าย
- ที่รูทของโปรเจกต์ ให้รัน gradlew.bat runClient บน Windows หรือ ./gradlew runClient บน macOS/Linux
- ค้นหาข้อความ TroubleMaker ในคอนโซลของไคลเอนต์สำหรับพัฒนา หรือใน run/logs/latest.log นี่คือตัวอย่างที่จะแสดงผลหนึ่งครั้งในช่วงการเริ่มต้นทำงานก่อนเข้าสู่เวิลด์
- ปิดเกมและสร้างไฟล์สำหรับเผยแพร่ด้วยคำสั่ง gradlew.bat build บน Windows หรือ ./gradlew build บน macOS/Linux
- ตรวจสอบไฟล์ JAR สำหรับเผยแพร่ทั่วไปใน build/libs อย่าใช้ไฟล์สำหรับพัฒนาที่มีคำว่า sources หรือ dev ต่อท้ายชื่อเป็นไฟล์เผยแพร่ทั่วไป
- นำไฟล์ JAR ไปใส่ในโฟลเดอร์ mods ของอินสแตนซ์ Fabric แยกต่างหากสำหรับเวอร์ชัน Minecraft ที่ตรงกัน หากการพึ่งพาที่สร้างขึ้นมี Fabric API ให้ติดตั้งให้ตรงกับเวอร์ชันเดียวกันด้วย
- รันด้วยตัวเปิดเกมจริง (Launcher) และตรวจสอบว่ามีข้อความเดียวกันปรากฏใน logs/latest.log ของอินสแตนซ์นั้น
6. ข้อผิดพลาดที่พบบ่อยและการกู้คืน
หากเจอ Unsupported class file version ให้ตรวจสอบเวอร์ชัน Java ก่อน; หากเจอข้อผิดพลาดในการโหลดคลาสเริ่มต้น ให้ตรวจสอบความไม่ตรงกันของ package, ชื่อคลาส และ entrypoints หากใส่ในโฟลเดอร์ mods แล้วเงียบหาย ให้ตรวจสอบว่าใส่ผิดอินสแตนซ์ของตัวเปิดเกมหรือไม่ เนื่องจากตัวอย่างนี้ไม่ได้เพิ่มข้อมูลเซฟ คุณจึงสามารถออกจากเกมและลบไฟล์ JAR เพื่อเปรียบเทียบได้ ในการเพิ่มไอเทมหรือบล็อกภายหลัง ให้ศึกษาเอกสาร Fabric First Item ของเวอร์ชันเป้าหมายต่อ และปรับพาธไฟล์รวมถึง API การลงทะเบียนให้ตรงกับเวอร์ชันนั้น
7. ข้อมูลที่ควรระบุร่วมด้วยเมื่อแชร์
ให้ระบุ Mod ID, เวอร์ชัน Minecraft ที่รองรับ, เงื่อนไข Loader และ Fabric API, ข้อกำหนด JDK รวมถึงฟีเจอร์ตัวอย่างและวิธีการลบไว้ใน README แยกซอร์สโค้ดและไฟล์ JAR สำหรับเผยแพร่ให้ชัดเจน และห้ามรวมตัวเกมหลักหรือไฟล์ม็อดของผู้สร้างรายอื่น สำหรับเวอร์ชันแรก ให้ตรวจสอบว่า log แสดงผลออกมาได้จริงในตัวเปิดเกมทั่วไป จากนั้นค่อยเผยแพร่โดยใส่หมายเลขเวอร์ชันเช่น 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 로더 자체의 업데이트 주기에 따라 결정되는 것인지 궁금합니다.