CradGacha

ไทย

English
Tiếng Việt

ไทย

English
Tiếng Việt

Appearance

Developer API ​

CradGacha มี API เล็กๆ ที่เสถียรให้ปลั๊กอินอื่นใช้: Bukkit event 2 ตัว + facade แบบ static ทุกเมธอด เรียกจาก main thread เท่านั้น และใช้ได้เมื่อ CradGacha เปิดใช้งานแล้ว

API แบ่งเป็น 2 ส่วน:

ส่วนเมธอดใช้ได้เมื่อ
Free (read-only)isMenuOpen, getPity, getTokens, getCrateIdsทุก jar
Premium (สั่งงาน + events)openCrate, addTokens, takeTokens, GachaOpenEvent, GachaPreOpenEventjar Premium หรือ มี api.premium-token ที่ถูกต้อง

ปลดล็อกส่วน Premium

เมธอด premium จะทำงานเฉพาะเมื่อติดตั้ง CradGacha Premium หรือมี api.premium-token (ไม่ว่าง) ใน config.yml · jar Premium จะ เจน token ให้อัตโนมัติ ใน config ตอนรันครั้งแรก — ก็อปไปใส่ config ของ ปลั๊กอินคู่หูเพื่อใช้ premium API ร่วมกับ jar Free ได้ · ระหว่างล็อก openCrate/takeTokens คืน false, addTokens ไม่ทำอะไร, และ event จะไม่ยิง · เช็ค isPremiumApiAvailable() ก่อน

การตั้งค่า ​

เพิ่ม jar ของ CradGacha เป็น dependency แบบ compileOnly และ depend เพื่อให้โหลดก่อน:

yaml
# plugin.yml ของคุณ
depend: [CradGacha]        # หรือ: softdepend: [CradGacha]

API อยู่ใน package com.threebstudio.cradgacha.api

Facade — CradGachaAPI ​

java
import com.threebstudio.cradgacha.api.CradGachaAPI;

// ----- Premium: เช็คก่อนเรียก -----
if (CradGachaAPI.isPremiumApiAvailable()) {
    // สั่งเปิดตู้ผ่านโค้ด — flow เดียวกับกดปุ่ม Open ในเมนู
    // คืน false ถ้าถูกบล็อก (ไม่มีตู้/ค่าเปิด/cooldown/event ถูก cancel) หรือ premium API ถูกล็อก
    boolean started = CradGachaAPI.openCrate(player, "starter", 10);
    CradGachaAPI.addTokens(uuid, 100);        // ให้ token (ไม่ทำอะไรถ้าล็อก)
    CradGachaAPI.takeTokens(uuid, 50);        // false ถ้ายอดไม่พอ หรือถ้าล็อก
}

// ----- Free: ใช้ได้เสมอ -----
CradGachaAPI.isMenuOpen(player);          // ผู้เล่นอยู่ในเมนู CradGacha ไหม?
CradGachaAPI.getPity(uuid, "starter");    // ตัวนับ pity ของตู้
CradGachaAPI.getTokens(uuid);             // ยอด token ในตัว
CradGachaAPI.getCrateIds();               // List<String> id ของทุกตู้ที่โหลด

Events ​

event ทั้งสองอยู่ในส่วน Premium — ยิงเฉพาะเมื่อ premium API ปลดล็อก (jar Premium หรือ api.premium-token) · บนเซิร์ฟ Free ที่ล็อกอยู่ listener จะไม่ถูกเรียกเลย

GachaPreOpenEvent — cancel ได้ ​

ยิง ก่อน เช็ค/หักอะไรทั้งสิ้น · cancel เพื่อบล็อกการเปิด (จำกัด region, ล็อกเควส, เช็คสิทธิ์…) หรือปรับจำนวนการ์ด

java
import com.threebstudio.cradgacha.api.GachaPreOpenEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyListener implements Listener {
  @EventHandler
  public void onPreOpen(GachaPreOpenEvent e) {
    if (isInArena(e.getPlayer())) {
      e.setCancelled(true);          // บล็อกทั้งหมด — ไม่หักอะไรเลย
      return;
    }
    // e.getCrateId(), e.getCount(), e.setCount(n)  (n จะถูก clamp ตาม settings.max-open)
  }
}

GachaOpenEvent — เชิงข้อมูล ​

ยิง หลัง สุ่มรางวัลและบันทึกลง pending แล้ว (ของหายไม่ได้แล้ว) ก่อนโชว์ผล · cancel ไม่ได้ — ถ้าจะบล็อกให้ใช้ GachaPreOpenEvent · ยิงทั้งหน้า reveal แบบเคอร์เซอร์และ world reveal สำรอง

java
import com.threebstudio.cradgacha.api.GachaOpenEvent;
import com.threebstudio.cradgacha.Reward;

@EventHandler
public void onOpen(GachaOpenEvent e) {
  for (Reward r : e.getResults()) {           // อ่านอย่างเดียว เรียงตามการ์ด
    // r.displayName(), r.itemId(), r.amount(), r.rarity().id(), r.hasCommands()
  }
  // e.getPlayer(), e.getCrateId()
}

หมายเหตุ ​

  • API ตั้งใจให้เล็กและเสถียรข้ามเวอร์ชัน
  • ทุกอย่างต้องเรียกจาก main thread ของเซิร์ฟเวอร์
  • ถ้าอยากได้ hook เพิ่มหรือมีไอเดีย integrate เปิด issue ที่ GitHub หรือถามใน Discord