papermc-skill 1.0.0

package/docs/05-concurrency-and-folia.md

@@ -0,0 +1,150 @@
+# Konkurensi, Threading & Kompatibilitas Folia
+
+Salah satu perubahan paling revolusioner di ekosistem Paper adalah kedatangan **Folia**. Folia memecah satu "Server Main Thread" Minecraft menjadi ratusan thread regional mandiri (**Threaded Regions**).
+
+Konsekuensinya, metode konkurensi lama seperti `Bukkit.getScheduler()` atau mengakses state world dari sembarang thread akan menyebabkan **`IllegalStateException` atau crash fatal** di Folia.
+
+---
+
+## 1. Model Threading: Bukkit vs Paper vs Folia
+
+```
+[Bukkit / Vanilla]
+Satu Main Thread ─── Tick Semua Dunia, Entity, Blok, Redstone, AI, Chunk ───>
+
+[Folia Regionized Threading]
+Region Thread 1  ─── Tick Region Dunia A (Chunk 0..32, 0..32) ───>
+Region Thread 2  ─── Tick Region Dunia A (Chunk 64..96, 64..96) ──>
+Region Thread 3  ─── Tick Nether (Region B) ──────────────────────>
+Global Thread    ─── Tick Weather, Time, Player List, Commands ───>
+Async Threads    ─── Network I/O, File Saving, Database Queries ──>
+```
+
+Di Folia:
+- Tidak ada lagi konsep "The Main Thread".
+- Objek `World`, `Entity`, dan `Block` hanya boleh diakses di **thread region yang memiliki chunk/lokasi tersebut**.
+- Mengakses entity pemain dari thread lain akan melempar error `Plugin attempted to access entity from wrong thread`.
+
+---
+
+## 2. Hirarki Scheduler Modern di Folia & Paper
+
+Paper memperkenalkan scheduler baru yang kompatibel dengan Folia dan Paper standar:
+
+### 1. `RegionScheduler`
+Digunakan untuk mengeksekusi task pada lokasi dunia atau koordinat chunk tertentu.
+
+```java
+import org.bukkit.Bukkit;
+import org.bukkit.Location;
+import org.bukkit.plugin.Plugin;
+
+Location loc = player.getLocation();
+
+// Menjalankan task 1-kali pada thread region lokasi tersebut
+Bukkit.getRegionScheduler().execute(plugin, loc, () -> {
+    loc.getBlock().setType(org.bukkit.Material.GOLD_BLOCK);
+});
+
+// Menjalankan task berulang (repeating) pada region
+Bukkit.getRegionScheduler().runAtFixedRate(plugin, loc, task -> {
+    loc.getWorld().spawnParticle(org.bukkit.Particle.FLAME, loc, 5);
+}, 20L, 20L); // delay 20 tick, period 20 tick
+```
+
+### 2. `EntityScheduler`
+Setiap `Entity` memiliki scheduler tersendiri. Task akan dieksekusi tepat pada thread region di mana entity tersebut sedang berada, bahkan jika entity tersebut bergerak/teleport antar region.
+
+```java
+player.getScheduler().run(plugin, task -> {
+    player.giveExp(10);
+    player.sendMessage("Bonus EXP didapatkan!");
+}, () -> {
+    // Callback jika entity telah mati atau tidak valid sebelum task sempat berjalan
+    plugin.getLogger().warning("Pemain logout sebelum exp diberikan.");
+});
+```
+
+### 3. `GlobalRegionScheduler`
+Digunakan untuk hal-hal yang bersifat global server dan tidak terikat pada koordinat block/entity tertentu (misal: pengumuman berkala chat global, update scoreboard global, waktu dunia).
+
+```java
+Bukkit.getGlobalRegionScheduler().runAtFixedRate(plugin, task -> {
+    Bukkit.broadcast(MiniMessage.miniMessage().deserialize("<gold>[Pengumuman] Kunjungi discord kami!</gold>"));
+}, 100L, 1200L);
+```
+
+### 4. `AsyncScheduler`
+Untuk I/O, database query, request HTTP, komputasi berat non-Bukkit API. Menggunakan waktu nyata (`java.time.TimeUnit`), bukan tick game:
+
+```java
+import java.util.concurrent.TimeUnit;
+
+Bukkit.getAsyncScheduler().runDelayed(plugin, task -> {
+    // Menjalankan query database MySQL / SQLite
+    database.savePlayerData(uuid, data);
+}, 5, TimeUnit.SECONDS);
+```
+
+---
+
+## 3. Pola Abstraksi Scheduler Universal (Paper + Folia)
+
+Banyak plugin perlu berjalan di server Paper standar (single-thread) dan Folia sekaligus. Cara terbaik adalah membuat lapisan pembungkus (*abstraction wrapper*) seperti yang digunakan oleh **Chunky** dan **squaremap**:
+
+```java
+public final class PlatformScheduler {
+
+    private static final boolean IS_FOLIA = checkFolia();
+
+    private static boolean checkFolia() {
+        try {
+            Class.forName("io.papermc.paper.threadedregions.RegionizedServer");
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        }
+    }
+
+    public static boolean isFolia() {
+        return IS_FOLIA;
+    }
+
+    public static void runLocation(Plugin plugin, Location location, Runnable runnable) {
+        if (IS_FOLIA) {
+            Bukkit.getRegionScheduler().execute(plugin, location, runnable);
+        } else {
+            Bukkit.getScheduler().runTask(plugin, runnable);
+        }
+    }
+
+    public static void runEntity(Plugin plugin, Entity entity, Runnable runnable) {
+        if (IS_FOLIA) {
+            entity.getScheduler().run(plugin, task -> runnable.run(), null);
+        } else {
+            Bukkit.getScheduler().runTask(plugin, runnable);
+        }
+    }
+
+    public static void runAsync(Plugin plugin, Runnable runnable) {
+        if (IS_FOLIA) {
+            Bukkit.getAsyncScheduler().runNow(plugin, task -> runnable.run());
+        } else {
+            Bukkit.getScheduler().runTaskAsynchronously(plugin, runnable);
+        }
+    }
+}
+```
+
+---
+
+## 4. Aturan Wajib untuk Kompatibilitas Folia
+
+1. **Deklarasikan di Manifest**:
+   Tambahkan `folia-supported: true` di `paper-plugin.yml`. Jika tidak, server Folia akan menampilkan peringatan bahwa plugin Anda berpotensi tidak aman.
+2. **Jangan Pernah Mengakses Chunk/Block dari Async Thread**:
+   Gunakan `world.getChunkAtAsync(x, z)` yang mengembalikan `CompletableFuture<Chunk>`.
+3. **Gunakan TeleportAsync**:
+   Gunakan `entity.teleportAsync(location)` alih-alih `entity.teleport(location)`. Di Folia, teleportasi melintasi region thread yang berbeda harus dilakukan secara asinkron.
+4. **Hindari State Statis Global**:
+   Variabel static yang menyimpan list player atau entity aktif dapat mengalami *race condition* jika dimodifikasi oleh beberapa thread region secara paralel. Gunakan struktur data thread-safe (`ConcurrentHashMap`, `CopyOnWriteArrayList`) bila terpaksa.

package/docs/06-events-and-listeners.md

@@ -0,0 +1,163 @@
+# Sistem Event & Listener di Paper
+
+Sistem event adalah mekanisme reaktif utama di Paper untuk merespons aksi pemain, lingkungan dunia, entitas, dan siklus server. Paper menyediakan banyak event eksklusif berkinerja tinggi serta integrasi penuh dengan Adventure Component.
+
+---
+
+## 1. Anatomi Listener Standar
+
+Listener mengimplementasikan antarmuka `org.bukkit.event.Listener` dan menggunakan anotasi `@EventHandler`:
+
+```java
+import org.bukkit.event.Listener;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.player.PlayerJoinEvent;
+import org.bukkit.plugin.java.JavaPlugin;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+
+public final class PlayerJoinListener implements Listener {
+
+    private final JavaPlugin plugin;
+
+    public PlayerJoinListener(JavaPlugin plugin) {
+        this.plugin = plugin;
+    }
+
+    @EventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)
+    public void onPlayerJoin(PlayerJoinEvent event) {
+        // Paper menggunakan Adventure Component untuk joinMessage
+        event.joinMessage(
+            MiniMessage.miniMessage().deserialize(
+                "<gray>[<green>+</green>] <yellow>" + event.getPlayer().getName() + "</yellow> bergabung ke server!</gray>"
+            )
+        );
+    }
+}
+```
+
+### Memahami `EventPriority`:
+Urutan eksekusi event dari pertama hingga terakhir:
+1. `LOWEST` (dijalankan paling awal, bagus untuk observasi mentah)
+2. `LOW`
+3. `NORMAL` (default)
+4. `HIGH`
+5. `HIGHEST` (dijalankan paling akhir sebelum event final)
+6. `MONITOR` (**HANYA UNTUK MEMBACA/LOGGING**; DILARANG memodifikasi atau membatalkan event di priority ini karena plugin lain tidak akan dapat merespons perubahan Anda).
+
+> **Penting**: Selalu tambahkan `ignoreCancelled = true` jika listener Anda tidak perlu memproses aksi yang sudah dibatalkan oleh plugin proteksi area (seperti WorldGuard/GriefPrevention).
+
+---
+
+## 2. Event Modern Eksklusif Paper
+
+Paper mengganti atau melengkapi beberapa event Bukkit lama dengan alternatif yang lebih efisien dan modern:
+
+### `AsyncChatEvent` (Menggantikan `AsyncPlayerChatEvent`)
+Paper menggunakan `io.papermc.paper.event.player.AsyncChatEvent` yang bekerja langsung dengan `Component` dan MiniMessage:
+
+```java
+import io.papermc.paper.event.player.AsyncChatEvent;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+
+@EventHandler
+public void onChat(AsyncChatEvent event) {
+    // Memodifikasi format pesan dengan Adventure
+    event.renderer((source, sourceDisplayName, message, viewer) -> 
+        MiniMessage.miniMessage().deserialize("<gray>[Member] </gray>")
+            .append(sourceDisplayName)
+            .append(Component.text(": "))
+            .append(message)
+    );
+}
+```
+
+### `PrePlayerAttackEntityEvent`
+Dijalankan sebelum kalkulasi serangan vanilla terjadi. Sangat ideal untuk sistem combat kustom, cooldown attack senjata khusus, atau verifikasi proteksi PvP.
+
+### `ServerTickStartEvent` & `ServerTickEndEvent`
+Memonitor performa server secara presisi per-tick tanpa membebani scheduler.
+
+---
+
+## 3. Membuat Custom Event
+
+Anda dapat membuat event sendiri untuk mengekspos API plugin Anda kepada developer lain (seperti yang dilakukan oleh LuckPerms atau WorldGuard).
+
+### Contoh Custom Event:
+```java
+package com.example.plugin.event;
+
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+public final class PlayerLevelUpEvent extends Event implements Cancellable {
+
+    private static final HandlerList HANDLERS = new HandlerList();
+    private final Player player;
+    private final int newLevel;
+    private boolean cancelled = false;
+
+    public PlayerLevelUpEvent(Player player, int newLevel) {
+        // false jika berjalan di main/region thread (Sync), true jika Async
+        super(false);
+        this.player = player;
+        this.newLevel = newLevel;
+    }
+
+    public Player getPlayer() {
+        return player;
+    }
+
+    public int getNewLevel() {
+        return newLevel;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLERS;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return HANDLERS;
+    }
+}
+```
+
+### Memanggil (Dispatch) Event:
+```java
+PlayerLevelUpEvent event = new PlayerLevelUpEvent(player, 10);
+Bukkit.getPluginManager().callEvent(event);
+
+if (!event.isCancelled()) {
+    // Lanjutkan aksi jika event tidak dibatalkan oleh plugin lain
+    player.sendActionBar(MiniMessage.miniMessage().deserialize("<green>Selamat, Anda naik level!</green>"));
+}
+```
+
+---
+
+## 4. Unregistering Event & Pembersihan
+
+Untuk mencegah memory leak saat reload atau saat plugin dinonaktifkan:
+- Semua event yang didaftarkan melalui `pluginManager.registerEvents(listener, this)` otomatis di-unregister saat `onDisable()`.
+- Jika Anda mendaftarkan event dinamis (misal per-minigame match), unregister secara manual ketika game selesai:
+  ```java
+  HandlerList.unregisterAll(matchListener);
+  ```

package/docs/07-best-practices-and-perf.md

@@ -0,0 +1,118 @@
+# Best Practices & Optimasi Performa Plugin Paper
+
+Pengembangan plugin Minecraft di server berkapasitas besar menuntut efisiensi tinggi, bebas memory leak, dan tidak memblokir tick game. Dokumen ini merangkum aturan emas dan anti-pattern yang sering terjadi.
+
+---
+
+## 1. Mencegah Memory Leak (Kebocoran Memori)
+
+Minecraft memiliki arsitektur objek yang saling terhubung erat. Menyimpan referensi objek Bukkit di memori Java lebih lama dari masa hidupnya dapat mencegah Garbage Collector (GC) membersihkan ratusan megabyte data.
+
+### 🔴 Anti-Pattern: Menyimpan Objek Bukkit di Collection Statis
+```java
+// SANGAT BERBAHAYA: Player objek menahan referensi ke World, Chunk, Connection, dll.
+public static final Set<Player> activePlayers = new HashSet<>();
+public static final Map<Player, PlayerData> dataMap = new HashMap<>();
+```
+Jika pemain disconnect, objek `Player` tidak akan bisa di-garbage collect!
+
+### 🟢 Solusi: Simpan `UUID`
+```java
+// AMAN: UUID hanya 16-byte identifier yang tidak menahan referensi dunia/koneksi
+public static final Set<UUID> activePlayerUuids = new HashSet<>();
+public static final Map<UUID, PlayerData> dataMap = new ConcurrentHashMap<>();
+
+// Ambil instance player hanya saat dibutuhkan:
+Player player = Bukkit.getPlayer(uuid);
+if (player != null) {
+    // Gunakan
+}
+```
+
+> **Aturan Umum**: Jangan pernah menyimpan `Player`, `Entity`, `World`, `Chunk`, atau `Block` di dalam field permanen/statis. Gunakan `UUID`, `NamespacedKey`, atau koordinat primitif (`worldName`, `x`, `y`, `z`).
+
+---
+
+## 2. Operasi I/O & Database Selalu Asinkron
+
+Setiap tick server berjalan dalam ~50 milidetik (20 TPS). Operasi disk I/O, pembacaan file besar, koneksi web/HTTP, atau query database yang membutuhkan waktu 100ms akan langsung menyebabkan server lag/freeze (tps drop).
+
+### 🟢 Solusi: Gunakan Async Threads & CompletableFuture
+```java
+import java.util.concurrent.CompletableFuture;
+import org.bukkit.Bukkit;
+
+public CompletableFuture<PlayerData> loadDataAsync(UUID uuid) {
+    return CompletableFuture.supplyAsync(() -> {
+        // Berjalan di luar thread game (off-main-thread)
+        return database.fetchUser(uuid);
+    }, myPluginThreadPool).thenApply(data -> {
+        return data != null ? data : new PlayerData(uuid);
+    });
+}
+
+// Menggunakan hasilnya:
+loadDataAsync(player.getUniqueId()).thenAccept(data -> {
+    // Jika perlu memodifikasi state game Bukkit (seperti memberi item),
+    // jadwalkan kembali ke scheduler region pemain:
+    player.getScheduler().run(plugin, task -> {
+        player.giveExp(data.getPendingExp());
+    }, null);
+});
+```
+
+---
+
+## 3. Menghindari Synchronous Chunk Loading
+
+Memanggil `world.getChunkAt(x, z)` atau `location.getBlock()` pada chunk yang belum di-load akan memaksa server memuat chunk tersebut dari disk secara synchronous (membekukan tick thread hingga chunk selesai dibaca).
+
+### 🔴 Anti-Pattern
+```java
+Chunk chunk = world.getChunkAt(x, z); // Membekukan server jika chunk belum di-load!
+```
+
+### 🟢 Solusi Paper: Asynchronous Chunk Loading
+Gunakan API Paper `getChunkAtAsync`:
+
+```java
+world.getChunkAtAsync(x, z, true).thenAccept(chunk -> {
+    // Chunk berhasil dimuat tanpa lag spike pada TPS
+    processChunkBlocks(chunk);
+});
+```
+
+---
+
+## 4. Konfigurasi (`config.yml`) yang Tangguh
+
+Di Paper, file YAML secara default menggunakan encoding UTF-8. Pastikan membaca dan menyimpan file konfigurasi dengan aman:
+
+```java
+// Menyimpan default config dari jar jika belum ada
+saveDefaultConfig();
+
+// Reload config
+reloadConfig();
+FileConfiguration config = getConfig();
+
+// Mengambil pesan dengan fallback default
+String rawMessage = config.getString("messages.welcome", "<green>Selamat datang!</green>");
+Component message = MiniMessage.miniMessage().deserialize(rawMessage);
+```
+
+Untuk struktur config yang sangat kompleks, pertimbangkan menggunakan library **Configurate** (`org.spongepowered:configurate-yaml`) yang mendukung pemeliharaan komentar file YAML, schema validation, dan serialisasi otomatis ke record Java.
+
+---
+
+## 5. Ringkasan Checklist Anti-Pattern
+
+| Jangan Lakukan ❌ | Lakukan Ini ✔️ |
+| :--- | :--- |
+| `ChatColor.RED + "Teks"` | `MiniMessage.miniMessage().deserialize("<red>Teks</red>")` |
+| `player.sendMessage("§a...")` | `player.sendMessage(Component)` |
+| `new NamespacedKey(...)` di per-event loop | Simpan instance `NamespacedKey` sebagai `static final` |
+| `world.getBlockAt(x, y, z)` acak di async thread | Akses block hanya di thread region yang bersangkutan |
+| Mengabaikan `paper-plugin.yml` untuk plugin baru | Manfaatkan `paper-plugin.yml` dan `PluginBootstrap` |
+| Menahan koneksi database terbuka di main thread | Gunakan connection pool (seperti HikariCP) & query async |
+| Mengabaikan `folia-supported` | Rancang scheduler menggunakan abstraksi region / universal |

package/docs/08-gui-and-menus.md

@@ -0,0 +1,198 @@
+# Pembuatan GUI / Menu Inventory Modern di Paper
+
+Membuat antarmuka interaktif (GUI Menu) menggunakan inventaris chest adalah salah satu fitur paling sering dibuat di plugin Minecraft. Pendekatan lama yang memeriksa judul GUI dengan string berwarna (`ChatColor.stripColor`) atau mencocokkan nomor slot sangat rapuh dan rawan bug duplikasi item.
+
+Paper modern menawarkan cara yang jauh lebih aman, bersih, dan type-safe menggunakan **Kyori Adventure** dan **PersistentDataContainer (PDC)**.
+
+---
+
+## 1. Masalah pada Pendekatan Lama vs Solusi Modern
+
+| Masalah Legacy (Lama) | Solusi Modern Paper |
+| :--- | :--- |
+| Memeriksa judul menu dengan `event.getView().getTitle().equals("§8Menu")` | Memeriksa `InventoryHolder` kustom atau PDC metadata pada item. |
+| Mencocokkan fungsi tombol berdasarkan `event.getSlot() == 13` | Menandai tombol dengan `PDC` (`NamespacedKey: "gui_action" -> "buy_item"`). |
+| Merusak format warna teks jika ada reload atau translate | Menggunakan Adventure `Component` untuk title inventaris. |
+| Rawan bug eksploitasi duplikasi jika `event.setCancelled(true)` luput | Selalu batalkan event jika holder terverifikasi sebagai custom GUI. |
+
+---
+
+## 2. Pola Custom `InventoryHolder`
+
+Cara paling handal dan standar industri untuk mengenali GUI buatan plugin Anda adalah membuat kelas yang mengimplementasikan `InventoryHolder`:
+
+```java
+package com.example.plugin.gui;
+
+import net.kyori.adventure.text.Component;
+import org.bukkit.Bukkit;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.InventoryHolder;
+import org.jetbrains.annotations.NotNull;
+
+public class CustomMenuHolder implements InventoryHolder {
+
+    private final Inventory inventory;
+    private final String menuId;
+
+    public CustomMenuHolder(Component title, int rows, String menuId) {
+        this.menuId = menuId;
+        // Bukkit.createInventory mendukung Adventure Component secara native di Paper
+        this.inventory = Bukkit.createInventory(this, rows * 9, title);
+    }
+
+    public String getMenuId() {
+        return menuId;
+    }
+
+    @Override
+    public @NotNull Inventory getInventory() {
+        return inventory;
+    }
+}
+```
+
+---
+
+## 3. Membuat Tombol dengan Penanda PDC
+
+Daripada mengingat nomor slot, tandai setiap item tombol dengan aksi spesifik di `PersistentDataContainer`:
+
+```java
+package com.example.plugin.gui;
+
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.ItemMeta;
+import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.plugin.Plugin;
+
+import java.util.List;
+
+public final class GuiItemBuilder {
+
+    public static final NamespacedKey ACTION_KEY = new NamespacedKey("myplugin", "gui_action");
+
+    public static ItemStack createButton(Material material, String nameMiniMessage, List<String> loreMiniMessage, String actionId) {
+        ItemStack item = new ItemStack(material);
+        ItemMeta meta = item.getItemMeta();
+        if (meta != null) {
+            meta.displayName(MiniMessage.miniMessage().deserialize(nameMiniMessage));
+            
+            meta.lore(loreMiniMessage.stream()
+                .map(line -> MiniMessage.miniMessage().deserialize(line))
+                .toList()
+            );
+
+            // Tandai tombol dengan ID aksi unik
+            meta.getPersistentDataContainer().set(ACTION_KEY, PersistentDataType.STRING, actionId);
+            item.setItemMeta(meta);
+        }
+        return item;
+    }
+}
+```
+
+---
+
+## 4. Merakit Menu
+
+```java
+public void openShopMenu(Player player) {
+    CustomMenuHolder holder = new CustomMenuHolder(
+        MiniMessage.miniMessage().deserialize("<gradient:#f12711:#f5af19><bold>Toko Server</bold></gradient>"),
+        3, // 3 baris = 27 slot
+        "server_shop"
+    );
+    Inventory inv = holder.getInventory();
+
+    // Border pengisi (filler)
+    ItemStack filler = GuiItemBuilder.createButton(
+        Material.GRAY_STAINED_GLASS_PANE,
+        "<gray> </gray>",
+        List.of(),
+        "noop" // No operation
+    );
+    for (int i = 0; i < inv.getSize(); i++) {
+        inv.setItem(i, filler);
+    }
+
+    // Tombol aksi
+    inv.setItem(11, GuiItemBuilder.createButton(
+        Material.DIAMOND_SWORD,
+        "<aqua><bold>Beli Senjata Legendaris</bold></aqua>",
+        List.of("<gray>Harga: <gold>500 Koin</gold></gray>", "<yellow>Klik untuk membeli!</yellow>"),
+        "buy_sword"
+    ));
+
+    inv.setItem(15, GuiItemBuilder.createButton(
+        Material.BARRIER,
+        "<red><bold>Tutup Menu</bold></red>",
+        List.of("<gray>Klik untuk keluar</gray>"),
+        "close_menu"
+    ));
+
+    player.openInventory(inv);
+}
+```
+
+---
+
+## 5. Event Listener Menu yang Aman dari Eksploitasi
+
+```java
+package com.example.plugin.gui;
+
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.inventory.InventoryClickEvent;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.persistence.PersistentDataType;
+
+public final class MenuClickListener implements Listener {
+
+    @EventHandler(priority = EventPriority.HIGHEST)
+    public void onInventoryClick(InventoryClickEvent event) {
+        // 1. Verifikasi apakah inventory yang diklik adalah custom holder kita
+        if (!(event.getInventory().getHolder() instanceof CustomMenuHolder holder)) {
+            return;
+        }
+
+        // 2. SELALU batalkan klik untuk mencegah pemain mengambil/memindahkan item GUI!
+        event.setCancelled(true);
+
+        // 3. Abaikan jika klik di luar jendela atau slot kosong
+        ItemStack clickedItem = event.getCurrentItem();
+        if (clickedItem == null || !clickedItem.hasItemMeta()) {
+            return;
+        }
+
+        if (!(event.getWhoClicked() instanceof Player player)) {
+            return;
+        }
+
+        // 4. Baca aksi dari PDC item
+        String action = clickedItem.getItemMeta().getPersistentDataContainer()
+            .get(GuiItemBuilder.ACTION_KEY, PersistentDataType.STRING);
+
+        if (action == null || action.equals("noop")) {
+            return;
+        }
+
+        // 5. Eksekusi aksi berdasarkan action ID
+        switch (action) {
+            case "buy_sword" -> {
+                player.sendMessage(MiniMessage.miniMessage().deserialize("<green>Sukses membeli senjata!</green>"));
+                player.closeInventory();
+            }
+            case "close_menu" -> player.closeInventory();
+            default -> player.sendMessage(MiniMessage.miniMessage().deserialize("<red>Aksi tidak dikenal.</red>"));
+        }
+    }
+}
+```