Hướng dẫn

Cách làm plugin Folia

Cập nhật 18 tháng 10, 2026

Folia là một bản fork của Paper chia thế giới thành các vùng và tick chúng trên những luồng khác nhau, để máy chủ lớn tận dụng được nhiều nhân CPU. Không còn một luồng chính duy nhất nữa, và điều đó làm hỏng scheduler Bukkit quen thuộc. Plugin Folia là plugin Paper được viết cho mô hình này, và phải khai báo điều đó trong plugin.yml.

Một ví dụ với các chi tiết thời gian mà Folia cần.

Tạo thứ này với Codexe

Từng bước

  1. 1.Kiểm tra xem bạn có cần Folia không

    Folia giúp các máy chủ có nhiều người chơi phân tán khắp thế giới. Hầu hết máy chủ chạy Paper; nhiều plugin phổ biến không hỗ trợ Folia, nên hãy kiểm tra trước những plugin mà bạn phụ thuộc vào.

  2. 2.Build với API của Folia

    Dùng dependency folia-api cho phiên bản của bạn từ kho PaperMC, với scope provided, trong một dự án Maven hoặc Gradle.

  3. 3.Thay thế scheduler Bukkit

    Bukkit.getScheduler() không hoạt động trên Folia. Dùng region scheduler cho việc tại một vị trí, entity scheduler cho việc trên một người chơi hoặc mob, global region scheduler cho tác vụ toàn thế giới, và async scheduler cho I/O.

  4. 4.Chỉ tác động lên mọi thứ từ chính vùng của chúng

    Chỉ thay đổi một khối hoặc thực thể trên luồng sở hữu nó. Dùng teleportAsync thay vì teleport, và lên lịch vào vùng của mục tiêu trước khi thay đổi nó.

  5. 5.Khai báo hỗ trợ Folia

    Thêm folia-supported: true vào plugin.yml. Thiếu dòng này Folia sẽ từ chối nạp plugin.

  6. 6.Thử trên máy chủ Folia

    Biên dịch được chỉ chứng minh mã build được với API của Folia, không chứng minh nó an toàn với đa luồng. Hãy chạy nó trên một máy chủ Folia thử nghiệm với nhiều người chơi ở những nơi khác nhau.

Bốn loại scheduler

SchedulerLấy bằngDùng cho
Vùng (region)Bukkit.getRegionScheduler()Việc tại một vị trí trong thế giới: đặt khối, sinh thực thể
Thực thể (entity)entity.getScheduler()Việc trên một người chơi hoặc mob, đi theo họ qua các vùng
Vùng toàn cục (global region)Bukkit.getGlobalRegionScheduler()Thời gian trong thế giới, thời tiết, những thứ không gắn với một vị trí
Bất đồng bộ (async)Bukkit.getAsyncScheduler()Cơ sở dữ liệu, tệp, yêu cầu web, không bao giờ đụng vào thế giới

Những gì thường bị hỏng

  • Tác vụ lặp lại cho mọi người chơi: một vòng lặp duy nhất qua mọi người chơi online không còn hoạt động; thay vào đó hãy lên lịch một tác vụ trên entity scheduler của từng người chơi.
  • Dịch chuyển và thời gian chờ: "dịch chuyển sau 3 giây" cần entity scheduler và teleportAsync.
  • Dữ liệu dùng chung: map và bộ đếm được dùng từ nhiều vùng phải an toàn với đa luồng, ví dụ các collection đồng thời.
  • Dependency: một thư viện gọi scheduler Bukkit sẽ ném UnsupportedOperationException trên Folia.

Một plugin cho cả Paper và Folia

Các scheduler region, entity, global và async cũng là một phần của API Paper ở các phiên bản hiện tại, nên một plugin chỉ dùng chúng và khai báo folia-supported: true có thể chạy trên cả Paper lẫn Folia. Đó thường là lựa chọn tốt nhất: một tệp .jar cho mọi máy chủ.

Với Codexe

Chọn loại Folia. Plugin được tạo lên lịch công việc bằng các scheduler region, entity, global region và async, khai báo folia-supported: true và build với API của Folia bằng Maven. Nó được biên dịch và kiểm tra trước khi Sẵn sàng.

Hãy ghi chi tiết về thời gian trong yêu cầu ("mỗi phút cho từng người chơi online", "dịch chuyển sau 3 giây"): đó là chỗ mã Folia khác biệt nhiều nhất. Dùng thử ngay chưa chạy được máy chủ Folia, nên hãy thử tệp .jar trên máy chủ Folia của riêng bạn.

Câu hỏi

Plugin Paper có chạy trên Folia không?

Chỉ khi chúng được viết cho Folia và khai báo folia-supported: true. Một plugin Paper bình thường dùng scheduler Bukkit sẽ bị từ chối hoặc gặp lỗi.

Plugin Folia có chạy trên Paper không?

Có, khi nó chỉ dùng những API mà Paper cũng có, bao gồm cả các scheduler của Folia trên các phiên bản Paper hiện tại.

Plugin Folia của tôi ném ra ngoại lệ liên quan đến scheduler

Có đoạn mã nào đó, thường là từ một thư viện, vẫn dùng scheduler Bukkit. Hãy nhờ khung chat của dự án chuyển nó sang region scheduler hoặc entity scheduler.

Làm plugin Folia

Prompt này mở ra sẵn sàng để gửi:

“Một plugin Folia 1.21.4 tên RTP: /rtp dịch chuyển người chơi đến một vị trí an toàn ngẫu nhiên trong phạm vi 5000 khối sau 3 giây chờ, bị hủy nếu di chuyển, dùng entity scheduler và teleportAsync, thời gian hồi 10 phút cho mỗi người chơi lưu trong SQLite, folia-supported: true, bán kính, thời gian hồi và tin nhắn trong config.yml.”

Tạo thứ này với Codexe
Cách làm plugin Folia (region scheduler) | Codexe