Documentation

GumballZ Docs

Tài liệu hướng dẫn đầy đủ cho Minecraft Plugin và Roblox Script

Tổng quan

GumballZPay là PaperMC plugin tích hợp thanh toán VietQR/SePay cho server Minecraft. Người chơi có thể nạp xu in-game thông qua website hoặc lệnh trong game, và tự động nhận rank khi tổng tiền nạp đạt ngưỡng.

Nạp xu in-game

QR Bank tự động

Auto-Rank

Theo mốc tích lũy

Gift Code

Tặng xu giữa người chơi

Yêu cầu

Phần mềm	Phiên bản	Bắt buộc
PaperMC / Purpur	1.21.1+	Bắt buộc
Java	21+	Bắt buộc
Vault	Any	Bắt buộc
LuckPerms	5.x	Tùy chọn
EssentialsX	Any	Tùy chọn

Cài đặt

1
Tải GumballZPay-1.0.0.jar từ GitHub Releases
2
Bỏ vào thư mục /plugins/ của server
3
Restart server → plugins/GumballZPay/config.yml tự tạo
4
Chỉnh api.secret trong config.yml
5
Dùng /gzpay reload để áp dụng

Cấu hình config.yml

api:
  url: "https://gumballzhub.vercel.app"
  secret: "YOUR_MINECRAFT_API_KEY"  # Phải khớp với Vercel env

payment:
  poll_interval_seconds: 5
  poll_timeout_minutes: 10

packages:
  money_20k:
    name: "§a§l💰 20,000 Xu"
    price_vnd: 20000
    reward_type: money
    reward_value: 20000

auto-rank:
  enabled: true
  ranks:
    - required_total_vnd: 50000
      luckperms_group: "vip"
      display_name: "§e§lVIP"
    - required_total_vnd: 700000
      luckperms_group: "god"
      display_name: "§d§lGOD"

Lệnh trong game

Lệnh	Quyền	Mô tả
/store	gumballzpay.use	Mở GUI cửa hàng
/napthe	gumballzpay.use	Mở GUI / tạo đơn
/napthe huy	gumballzpay.use	Hủy đơn đang chờ
/napthe redeem <mã>	gumballzpay.use	Đổi mã claim / gift code
/gzpay reload	gumballzpay.admin	Reload config
/gzpay giftcode <xu>	gumballzpay.admin	Tạo gift code

Luồng thanh toán

🎮 In-game (có server):

/napthe money_20k
 → Tạo đơn → click link → quét QR → thanh toán
 → Plugin tự nhận → +xu vào Vault → kiểm tra auto-rank

🌐 Web Store (không cần vào server):

gumballzhub.vercel.app/minecraft/store
 → Nhập tên MC + chọn gói → quét QR → thanh toán
 → Nhận mã claim (VD: MC3X9KZA)
 → Vào game: /napthe redeem MC3X9KZA → nhận xu!

🎁 Gift Code (admin → player):

Admin: /gzpay giftcode 50000 Tang ban
 → Hệ thống tạo code GZ3K8MNP
Admin gửi code cho người chơi
Player: /napthe redeem GZ3K8MNP → nhận 50,000 xu!

Tải Plugin JAR GitHub