Cách tạo bản mod Minecraft: Từ dự án Fabric, mã Java đến build file JAR

Hướng dẫn này tạo ra một bản mod in ra log trong lần chạy đầu tiên dựa trên Minecraft Java Edition 26.2 và Fabric. Đây là một ví dụ dành cho người mới bắt đầu, theo dõi cho đến điểm mà tệp mod được trình tải nhận dạng và mã Java bạn viết được thực thi. Các tiện ích bổ sung (addon) của Bedrock, các dự án Forge và NeoForge có cấu trúc khác nhau, vì vậy đừng trộn lẫn chúng trong cùng một dự án.

1. Chuẩn bị môi trường phát triển

Tài liệu 26.2 hiện tại của Fabric đề xuất JDK 25. Thay vì chỉ cài đặt môi trường chạy Java (runtime), hãy cài đặt JDK dành cho nhà phát triển và chuẩn bị IntelliJ IDEA hoặc VS Code. Kiểm tra phiên bản Java thực tế đang sử dụng bằng lệnh bên dưới trong terminal. Project SDK của IDE và Gradle JVM cũng phải trỏ đến cùng một phiên bản. Để tạo cho các phiên bản cũ hơn như 1.21.1, hãy thay đổi phần lựa chọn phiên bản ở đầu tài liệu và phiên bản trình tạo cùng nhau, đồng thời tuân theo các yêu cầu về JDK của phiên bản đó.

java -version
javac -version

2. Tạo dự án trong trình tạo Fabric

1. Mở Template Mod Generator chính thức của Fabric.
2. Đặt Mod Name thành TroubleMaker Hello, Mod ID thành tmhello, và Package Name thành com.ascgame.tmhello.
3. Đặt phiên bản Minecraft thành 26.2. Các tùy chọn nâng cao như Kotlin hoặc tạo dữ liệu riêng biệt không cần phải thêm vào ở ví dụ đầu tiên.
4. Tải xuống tệp ZIP và giải nén nó vào một đường dẫn đơn giản như C:/Projects/TMHello. Thư mục dự án được quyết định tùy theo hệ điều hành thực tế của bạn.
5. Mở build.gradle hoặc thư mục gốc của dự án trong IDE và đợi quá trình nhập Gradle (Gradle importing) hoàn tất. Giữ nguyên các phiên bản Loader, Loom và API do trình tạo chỉ định.

3. Hiểu chức năng của các tệp

src/main/java dành cho mã Java chung, src/main/resources/fabric.mod.json dành cho ID mod, lớp khởi điểm (entry class) và khai báo phần phụ thuộc (dependencies), còn gradle.properties dành cho các thiết lập phiên bản và dự án. Tùy thuộc vào trình tạo, mã máy khách (client code) có thể được chia thành src/client/java. Ví dụ này chỉ thay đổi mã khởi tạo chung. Không tự ý xóa tất cả các tệp thiết lập hoặc ghi đè cài đặt phiên bản khác từ internet.

4. Viết lớp khởi tạo của tôi

Tìm tệp thực thi ModInitializer chung đã được tạo và sửa đổi nó theo cấu trúc bên dưới. Nếu bạn đã đổi tên tệp thành TMHello.java, hãy khớp cả thư mục gói (package folder) và tên lớp. Vì nó sử dụng log SLF4J, bạn có thể kiểm tra xem quá trình khởi tạo có diễn ra hay không mà không cần API đăng ký vật phẩm vốn dễ thay đổi ở các phiên bản trò chơi khác nhau.

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.");
    }
}

Trong khi giữ nguyên các nội dung khác của fabric.mod.json, hãy xác minh rằng entrypoints.main trỏ đến tên đầy đủ của lớp ở trên. Đoạn mã dưới đây không phải là toàn bộ tệp mà là phần cần kiểm tra. Không thay thế hoàn toàn các mixins hoặc cài đặt máy khách hiện có.

{
  "entrypoints": {
    "main": ["com.ascgame.tmhello.TMHello"]
  }
}

5. Chạy phát triển và Build tệp cuối cùng

1. Từ thư mục gốc của dự án, chạy gradlew.bat runClient trên Windows hoặc ./gradlew runClient trên macOS/Linux.
2. Tìm kiếm cụm từ TroubleMaker trong bảng điều khiển của máy khách phát triển (development client console) hoặc run/logs/latest.log. Đây là một ví dụ được in ra một lần trong quá trình khởi tạo trước khi vào thế giới.
3. Thoát trò chơi và tạo tệp phân phối bằng gradlew.bat build trên Windows hoặc ./gradlew build trên macOS/Linux.
4. Kiểm tra tệp JAR phân phối chung trong build/libs. Không sử dụng các tệp phát triển có đính kèm chữ sources hoặc dev trong tên làm bản phân phối chung.
5. Đặt tệp JAR vào thư mục mods của một phiên bản (instance) Fabric riêng biệt có cùng phiên bản Minecraft. Nếu phần phụ thuộc được tạo có chứa Fabric API, hãy cài đặt nó tương ứng với phiên bản đó.
6. Chạy bằng trình khởi chạy thực tế và xác minh xem cụm từ tương tự có được ghi lại trong logs/latest.log của phiên bản đó hay không.

6. Các lỗi thường gặp và cách khôi phục

Đối với lỗi Unsupported class file version, trước tiên hãy kiểm tra phiên bản Java; đối với lỗi tải lớp khởi điểm, hãy kiểm tra sự không tương thích giữa gói, tên lớp và entrypoints. Nếu không có phản hồi sau khi đưa vào thư mục mods, hãy kiểm tra xem bạn có đặt nó vào một phiên bản trình khởi chạy khác hay không. Ví dụ này không thêm dữ liệu lưu (save data), vì vậy bạn có thể thoát trò chơi và xóa tệp JAR để so sánh. Khi thêm vật phẩm hoặc khối trong tương lai, hãy đọc tài liệu Fabric First Item của phiên bản mục tiêu và điều chỉnh đường dẫn tệp cũng như API đăng ký cho phiên bản đó.

7. Thông tin cần đính kèm khi chia sẻ

Viết rõ Mod ID, phiên bản Minecraft được hỗ trợ, các điều kiện về Loader và Fabric API, các yêu cầu về JDK, các tính năng ví dụ và cách gỡ bỏ trong tệp README. Phân biệt rõ mã nguồn và tệp JAR phân phối, đồng thời không bao gồm tệp trò chơi gốc hoặc tệp mod của tác giả khác. Hãy phân phối phiên bản ban đầu với số phiên bản như 1.0.0 sau khi xác nhận rằng log được in ra trên trình khởi chạy thông thường thực tế.

Tài liệu gốc và tiêu chí xác minh

Đây là hướng dẫn dành for người mới bắt đầu được viết bởi đội ngũ vận hành TroubleMaker vào ngày 7 tháng 10 năm 2026, sau khi kiểm tra tài liệu công cụ chính thức và của nhà sáng tạo. Mã và sơ đồ là các ví dụ tự tạo của chúng tôi để giải thích và không phải là kết quả xác minh quá trình chơi thực tế của trò chơi này trên máy chủ này. Vui lòng xác minh bằng phiên bản được chỉ định trong văn bản trên một bản lưu thử nghiệm riêng trước khi phân phối. Đối chiếu các phiên bản mới nhất và phần phụ thuộc của từng công cụ từ các nguồn gốc bên dưới.

Fabric 개발 환경

Fabric 프로젝트 생성

Fabric 모드 빌드

Fabric 공식 생성기