Best Practices Integrasi RankForge API – Thread, Folia & Kompatibilitas

1. Thread dan Folia

Operasi	Thread
`get*` (baca poin, tier, statistik)	Aman dari thread mana pun untuk nilai primitif, tetapi lihat catatan `PlayerData` di bawah
`setPoints`, `addPoints`, `removePoints`	Hanya thread server (main thread di Paper, region thread di Folia), karena memicu event sinkron
`saveAsync()`	Dari thread mana pun; hasilnya `CompletableFuture`

Dari kode async, pindahkan ke thread server dengan Bukkit.getGlobalRegionScheduler().execute(plugin, ...) (berjalan di Paper dan Folia).
getPlayerData() mengembalikan objek hidup yang bisa berubah dari thread lain. Baca nilainya sekali dan simpan di variabel lokal; jangan menyimpan referensinya lama-lama.

2. Selalu tangani `null`

getTier, getTierByPoints, dan getNextTier mengembalikan null untuk pemain Unranked atau di tier tertinggi. getPlayerData bisa null untuk pemain yang belum punya data.

Tier tier = api.getTier(player);
String name = tier != null ? tier.display : "Unranked";

3. Integrasi opsional harus aman

Gunakan softdepend dan pisahkan kode integrasi ke class tersendiri.
Cek RankForgeAPI.isAvailable() sebelum get().
Daftarkan listener RankForge hanya jika plugin-nya aktif.

4. Hanya pakai API publik

Class yang stabil untuk dipakai: xyz.noxlydev.rankforge.api.*, xyz.noxlydev.rankforge.model.*, dan RankForge (instance plugin). Package lain (manager, database, gui, hook, util) adalah internal: namanya bisa berubah di build ProGuard atau antar versi. Jangan memanggil getDataManager() atau class sejenis.

5. Ubah poin lewat API, bukan lewat data

Mengubah PlayerData langsung tidak menandai data untuk disimpan dan melewati event. Gunakan setPoints / addPoints / removePoints.

6. Hindari loop event

Jangan memanggil addPoints / setPoints di dalam handler PlayerPointsChangeEvent. Gunakan event.setNewPoints(...) untuk menyesuaikan nilai.

7. Jaga performa

getTopPlayers(limit) mengurutkan semua pemain tiap dipanggil. Untuk tampilan yang sering diperbarui, simpan hasilnya (cache) beberapa detik.
Untuk nilai tampilan sederhana, placeholder %rankforge_top_*% sudah memakai cache internal.

8. Versi dan kompatibilitas

Kompilasi terhadap Java 21 dan Paper API 1.21+.
Cantumkan versi RankForge minimum yang kamu uji di dokumentasi plugin kamu.
Setelah update RankForge, jalankan ulang tes integrasi: API publik dijaga stabil, tetapi event baru atau perubahan perilaku dapat muncul antar versi.