papermc-skill 1.0.0

package/docs/09-custom-items-and-combat.md

@@ -0,0 +1,171 @@
+# Custom Items, Ability & Combat di Paper
+
+Membuat item kustom dengan kemampuan sihir atau skill khusus (seperti tongkat sihir petir, pedang lifesteal, atau bow peledak) adalah fitur paling favorit di server RPG dan Mini-games.
+
+Paper menyediakan API native untuk raycasting, particle, cooldown visual vanilla, dan Adventure sound effects tanpa perlu library eksternal.
+
+---
+
+## 1. Anatomi Custom Item dengan PDC
+
+Selalu identifikasi item kustom menggunakan `PersistentDataContainer` (PDC), bukan nama atau lore yang bisa dipalsukan pemain via Anvil:
+
+```java
+package com.example.plugin.item;
+
+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 java.util.List;
+
+public final class CustomItemFactory {
+
+    public static final NamespacedKey ITEM_ID_KEY = new NamespacedKey("myplugin", "item_id");
+    public static final NamespacedKey COOLDOWN_KEY = new NamespacedKey("myplugin", "ability_cooldown");
+
+    public static ItemStack createLightningWand() {
+        ItemStack item = new ItemStack(Material.BLAZE_ROD);
+        ItemMeta meta = item.getItemMeta();
+        if (meta != null) {
+            meta.displayName(MiniMessage.miniMessage().deserialize("<gradient:#ffe259:#ffa751><bold>Tongkat Petir Kuno</bold></gradient>"));
+            meta.lore(List.of(
+                MiniMessage.miniMessage().deserialize("<gray>Klik kanan untuk menembakkan <yellow>Petir Murni</yellow>.</gray>"),
+                MiniMessage.miniMessage().deserialize("<dark_gray>Cooldown: <gold>3 Detik</gold></dark_gray>")
+            ));
+
+            // Tandai ID item
+            meta.getPersistentDataContainer().set(ITEM_ID_KEY, PersistentDataType.STRING, "lightning_wand");
+            item.setItemMeta(meta);
+        }
+        return item;
+    }
+}
+```
+
+---
+
+## 2. Sistem Cooldown: Visual Vanilla vs Timestamp
+
+Minecraft memiliki API bawaan untuk menampilkan cooldown visual (animasi abu-abu berputar pada hotbar slot):
+
+```java
+// Memberikan cooldown visual vanilla selama 60 tick (3 detik) pada Blaze Rod
+player.setCooldown(Material.BLAZE_ROD, 60);
+
+// Memeriksa apakah pemain sedang dalam cooldown
+if (player.hasCooldown(Material.BLAZE_ROD)) {
+    player.sendActionBar(MiniMessage.miniMessage().deserialize("<red>Kemampuan masih cooldown!</red>"));
+    return;
+}
+```
+
+---
+
+## 3. Raycasting Entitas & Partikel (Skill Sihir)
+
+Raycasting digunakan untuk mendeteksi apa yang sedang dibidik pemain secara presisi menggunakan `World#rayTraceEntities` atau kalkulasi vektor:
+
+```java
+package com.example.plugin.item;
+
+import net.kyori.adventure.sound.Sound;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import org.bukkit.FluidCollisionMode;
+import org.bukkit.Location;
+import org.bukkit.Material;
+import org.bukkit.Particle;
+import org.bukkit.SoundCategory;
+import org.bukkit.World;
+import org.bukkit.entity.Damageable;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.block.Action;
+import org.bukkit.event.player.PlayerInteractEvent;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.util.RayTraceResult;
+import org.bukkit.util.Vector;
+
+public final class CustomItemListener implements Listener {
+
+    @EventHandler
+    public void onInteract(PlayerInteractEvent event) {
+        if (event.getAction() != Action.RIGHT_CLICK_AIR && event.getAction() != Action.RIGHT_CLICK_BLOCK) {
+            return;
+        }
+
+        ItemStack item = event.getItem();
+        if (item == null || !item.hasItemMeta()) return;
+
+        String itemId = item.getItemMeta().getPersistentDataContainer()
+            .get(CustomItemFactory.ITEM_ID_KEY, PersistentDataType.STRING);
+
+        if (!"lightning_wand".equals(itemId)) {
+            return;
+        }
+
+        event.setCancelled(true);
+        Player player = event.getPlayer();
+
+        // 1. Cek Cooldown
+        if (player.hasCooldown(Material.BLAZE_ROD)) {
+            player.sendActionBar(MiniMessage.miniMessage().deserialize("<red>Tunggu sejenak sebelum menembak lagi!</red>"));
+            return;
+        }
+
+        // Set cooldown 3 detik (60 ticks)
+        player.setCooldown(Material.BLAZE_ROD, 60);
+
+        // 2. Eksekusi Efek Serangan
+        castLightningBeam(player);
+    }
+
+    private void castLightningBeam(Player player) {
+        World world = player.getWorld();
+        Location eyeLoc = player.getEyeLocation();
+        Vector direction = eyeLoc.getDirection().normalize();
+
+        // Putar suara tembakan sihir
+        player.playSound(Sound.sound(
+            org.bukkit.Sound.ENTITY_ILLUSIONER_CAST_SPELL.key(),
+            Sound.Source.PLAYER,
+            1.0f,
+            1.5f
+        ));
+
+        // Partikel beam sepanjang garis pandang (hingga 30 blok)
+        for (double d = 1; d <= 30; d += 0.5) {
+            Location point = eyeLoc.clone().add(direction.clone().multiply(d));
+            world.spawnParticle(Particle.ELECTRIC_SPARK, point, 2, 0.05, 0.05, 0.05, 0.01);
+        }
+
+        // Raytrace entitas yang terkena garis tembakan
+        RayTraceResult result = world.rayTraceEntities(
+            eyeLoc,
+            direction,
+            30.0,
+            0.5,
+            entity -> entity != player && entity instanceof Damageable
+        );
+
+        if (result != null && result.getHitEntity() != null) {
+            Entity target = result.getHitEntity();
+            Location hitLoc = target.getLocation();
+
+            // Panggil sambaran petir visual & berikan damage
+            world.strikeLightningEffect(hitLoc);
+            if (target instanceof Damageable damageable) {
+                damageable.damage(8.0, player); // 8 damage = 4 hati
+            }
+
+            player.sendActionBar(MiniMessage.miniMessage().deserialize("<yellow>Tembakan Mengenai Target!</yellow>"));
+        }
+    }
+}
+```

package/docs/10-database-and-storage.md

@@ -0,0 +1,187 @@
+# Penyimpanan Database Asinkron: SQLite & HikariCP di Paper
+
+Menyimpan data pemain (uang/ekonomi, statistik level, inventaris kustom, quest) langsung ke file YAML (`config.yml` atau `player.yml`) sering kali menjadi lambat dan berisiko korup jika server memiliki ribuan pemain unik.
+
+Standar industri untuk penyimpanan data di plugin produksi adalah menggunakan database relasional (seperti **SQLite** untuk server mandiri, atau **MySQL/PostgreSQL via HikariCP** untuk jaringan multi-server/BungeeCord).
+
+---
+
+## 1. Aturan Emas Database di Minecraft
+
+> **DILARANG KERAS menjalankan koneksi database, query `SELECT`, atau `INSERT/UPDATE` di main/region tick thread.**
+> Query yang memakan waktu 50ms akan langsung menyebabkan TPS server turun dan pemain mengalami lag atau rollback.
+
+Gunakan selalu **Asynchronous Execution (`CompletableFuture`)** yang me-return hasil ke thread region pemain saat selesai.
+
+---
+
+## 2. Menyiapkan HikariCP (Connection Pooling)
+
+HikariCP adalah library connection pool tercepat di ekosistem Java (digunakan secara ekstensif oleh **LuckPerms**).
+
+### Dependensi Gradle:
+```kotlin
+dependencies {
+    implementation("com.zaxxer:HikariCP:5.1.0")
+}
+```
+
+### Inisialisasi DataSource:
+```java
+package com.example.plugin.database;
+
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+
+public final class DatabaseManager {
+
+    private HikariDataSource dataSource;
+
+    public void initMySQL(String host, int port, String database, String user, String password) {
+        HikariConfig config = new HikariConfig();
+        config.setJdbcUrl("jdbc:mysql://" + host + ":" + port + "/" + database + "?useSSL=false&characterEncoding=utf-8");
+        config.setUsername(user);
+        config.setPassword(password);
+
+        // Pengaturan Pool HikariCP yang Direkomendasikan
+        config.setMaximumPoolSize(10);
+        config.setMinimumIdle(2);
+        config.setConnectionTimeout(10000); // 10 detik
+        config.setIdleTimeout(600000);      // 10 menit
+        config.setMaxLifetime(1800000);     // 30 menit
+        config.setPoolName("PluginHikariPool");
+
+        this.dataSource = new HikariDataSource(config);
+    }
+
+    public void initSQLite(String filePath) {
+        HikariConfig config = new HikariConfig();
+        config.setJdbcUrl("jdbc:sqlite:" + filePath);
+        config.setMaximumPoolSize(1); // SQLite hanya boleh 1 writer pool
+        config.setPoolName("PluginSQLitePool");
+
+        this.dataSource = new HikariDataSource(config);
+    }
+
+    public Connection getConnection() throws SQLException {
+        return dataSource.getConnection();
+    }
+
+    public void close() {
+        if (dataSource != null && !dataSource.isClosed()) {
+            dataSource.close();
+        }
+    }
+}
+```
+
+---
+
+## 3. Repositori Asinkron dengan `CompletableFuture`
+
+Buat Data Access Object (DAO) yang memisahkan eksekusi SQL dari logika game:
+
+```java
+package com.example.plugin.database;
+
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+public final class PlayerRepository {
+
+    private final DatabaseManager databaseManager;
+    private final ExecutorService dbExecutor = Executors.newFixedThreadPool(3);
+
+    public PlayerRepository(DatabaseManager databaseManager) {
+        this.databaseManager = databaseManager;
+        createTableIfNotExists();
+    }
+
+    private void createTableIfNotExists() {
+        try (Connection conn = databaseManager.getConnection();
+             PreparedStatement stmt = conn.prepareStatement(
+                 "CREATE TABLE IF NOT EXISTS player_data (" +
+                 "uuid VARCHAR(36) PRIMARY KEY, " +
+                 "coins INT NOT NULL DEFAULT 0, " +
+                 "level INT NOT NULL DEFAULT 1);"
+             )) {
+            stmt.executeUpdate();
+        } catch (SQLException e) {
+            e.printStackTrace();
+        }
+    }
+
+    // Membaca data pemain secara asinkron
+    public CompletableFuture<Integer> getCoinsAsync(UUID uuid) {
+        return CompletableFuture.supplyAsync(() -> {
+            try (Connection conn = databaseManager.getConnection();
+                 PreparedStatement stmt = conn.prepareStatement(
+                     "SELECT coins FROM player_data WHERE uuid = ?"
+                 )) {
+                stmt.setString(1, uuid.toString());
+                try (ResultSet rs = stmt.executeQuery()) {
+                    if (rs.next()) {
+                        return rs.getInt("coins");
+                    }
+                }
+            } catch (SQLException e) {
+                e.printStackTrace();
+            }
+            return 0; // Default jika data belum ada
+        }, dbExecutor);
+    }
+
+    // Menyimpan data pemain secara asinkron (Upsert)
+    public CompletableFuture<Void> setCoinsAsync(UUID uuid, int coins) {
+        return CompletableFuture.runAsync(() -> {
+            try (Connection conn = databaseManager.getConnection();
+                 PreparedStatement stmt = conn.prepareStatement(
+                     "INSERT INTO player_data (uuid, coins) VALUES (?, ?) " +
+                     "ON CONFLICT(uuid) DO UPDATE SET coins = excluded.coins;" // SQLite & Postgres (gunakan ON DUPLICATE KEY UPDATE untuk MySQL)
+                 )) {
+                stmt.setString(1, uuid.toString());
+                stmt.setInt(2, coins);
+                stmt.executeUpdate();
+            } catch (SQLException e) {
+                e.printStackTrace();
+            }
+        }, dbExecutor);
+    }
+
+    public void shutdown() {
+        dbExecutor.shutdown();
+    }
+}
+```
+
+---
+
+## 4. Menggunakan Hasil Database di Event Listener
+
+Saat data selesai di-fetch dari database, gunakan scheduler Folia/Paper pemain untuk menerapkan perubahannya ke objek Bukkit:
+
+```java
+@EventHandler
+public void onPlayerJoin(PlayerJoinEvent event) {
+    Player player = event.getPlayer();
+
+    // Fetch data koin di thread asinkron
+    playerRepository.getCoinsAsync(player.getUniqueId()).thenAccept(coins -> {
+        // Terapkan hasil ke entity pemain di thread region pemain
+        player.getScheduler().run(plugin, task -> {
+            player.sendActionBar(MiniMessage.miniMessage().deserialize(
+                "<gold>Saldo Koin: <yellow>" + coins + "</yellow></gold>"
+            ));
+        }, null);
+    });
+}
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "papermc-skill",
+  "version": "1.0.0",
+  "description": "Interactive CLI and architectural development skill for modern Paper & Folia Minecraft Java plugins",
+  "main": "bin/cli.js",
+  "bin": {
+    "papermc-skill": "bin/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "templates",
+    "docs",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "minecraft",
+    "paper",
+    "papermc",
+    "folia",
+    "minecraft-plugin",
+    "adventure-api",
+    "minimessage",
+    "spigot",
+    "bukkit",
+    "npx"
+  ],
+  "author": "Ardian Ryan <https://github.com/ardianryan>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ardianryan/papermc-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ardianryan/papermc-skill/issues"
+  },
+  "homepage": "https://github.com/ardianryan/papermc-skill#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/paper-plugin-dev/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: paper-plugin-dev
+description: Expert guidelines, modern standards, and architectural blueprints for developing Minecraft Java server plugins using the PaperMC API (1.20-1.21+), Folia, Adventure API, MiniMessage, and Paperweight.
+---
+
+# Paper Minecraft Plugin Development Skill
+
+Skill ini memberikan panduan otoritatif, standar arsitektur modern, dan resep coding siap pakai untuk membuat atau memodifikasi plugin Minecraft Java Server berbasis **PaperMC (1.20.6 / 1.21+)** dan **Folia (Threaded Regions)**.
+
+---
+
+## 1. Prasyarat Lingkungan & Dependensi
+
+| Komponen | Versi yang Dibutuhkan | Catatan |
+| :--- | :--- | :--- |
+| **Java SDK** | **Java 21 (LTS)** atau lebih baru | Minecraft 1.20.5+ dan Paper modern **wajib** Java 21+. |
+| **Gradle** | **Gradle 8.5+** (Disarankan 8.10+ / 9.x) | Gunakan Gradle Wrapper bawaan (`./gradlew`). |
+| **Paper API** | `io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT` | Repositori: `https://repo.papermc.io/repository/maven-public/` |
+| **Mojang Mappings** | `io.papermc.paperweight.userdev` | Hanya jika membutuhkan akses langsung ke internal `net.minecraft.*`. |
+
+---
+
+## 2. Alur Kerja Standar (Workflow) untuk AI / Developer
+
+Saat diminta membuat fitur atau plugin Paper baru, ikuti urutan berikut:
+
+1. **Tentukan Manifest (`src/main/resources/paper-plugin.yml`)**:
+   - Berikan `folia-supported: true`.
+   - Cantumkan `bootstrapper:` jika menggunakan Paper Brigadier Command.
+2. **Setup PDC Keys (`PluginDataKeys.java`)**:
+   - Buat konstanta `static final NamespacedKey` untuk semua data persisten (jangan instansiasi di dalam event loop).
+3. **Pilih Penanganan Teks (Kyori Adventure)**:
+   - Gunakan `MiniMessage.miniMessage().deserialize(...)`.
+   - Jangan pernah menggunakan `§` atau `org.bukkit.ChatColor`.
+4. **Pilih Pola Concurrency**:
+   - Akses entity/block? Gunakan `RegionScheduler` atau `EntityScheduler`.
+   - File/Database/Network? Gunakan `AsyncScheduler` atau `CompletableFuture`.
+5. **Daftarkan Command & Event**:
+   - Command -> Daftarkan di `BootstrapContext` via `LifecycleEvents.COMMANDS`.
+   - Event -> Daftarkan di `JavaPlugin#onEnable()` via `registerEvents(...)`.
+
+---
+
+## 3. Resep Kode Cepat (Ready-to-Use Recipes)
+
+### Resep A: Manifest Modern (`paper-plugin.yml`)
+```yaml
+name: MyAwesomePlugin
+version: '1.0.0'
+main: com.example.plugin.MyPlugin
+bootstrapper: com.example.plugin.MyPluginBootstrap
+api-version: '1.21'
+folia-supported: true
+authors:
+  - DeveloperName
+```
+
+### Resep B: Brigadier Command Modern (Tanpa `plugin.yml`)
+```java
+// Daftarkan di PluginBootstrap#bootstrap:
+context.getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {
+    event.registrar().register(
+        Commands.literal("warp")
+            .requires(source -> source.getSender().hasPermission("plugin.warp"))
+            .then(Commands.argument("target", StringArgumentType.word())
+                .suggests((ctx, builder) -> {
+                    builder.suggest("spawn");
+                    builder.suggest("arena");
+                    return builder.buildFuture();
+                })
+                .executes(ctx -> {
+                    String target = StringArgumentType.getString(ctx, "target");
+                    ctx.getSource().getSender().sendMessage(
+                        MiniMessage.miniMessage().deserialize("<green>Teleporting to <gold>" + target + "</gold>...</green>")
+                    );
+                    return Command.SINGLE_SUCCESS;
+                })
+            )
+            .build(),
+        "Warp command description",
+        List.of("gotowarp")
+    );
+});
+```
+
+### Resep C: PersistentDataContainer (PDC) Item & Entity
+```java
+// Menyimpan data pada ItemStack
+NamespacedKey KEY = new NamespacedKey(plugin, "item_level");
+meta.getPersistentDataContainer().set(KEY, PersistentDataType.INTEGER, 5);
+
+// Membaca data dengan fallback default:
+int level = meta.getPersistentDataContainer().getOrDefault(KEY, PersistentDataType.INTEGER, 1);
+```
+
+### Resep D: GUI Menu Aman dari Eksploitasi
+```java
+// 1. Buat Custom InventoryHolder
+public class MenuHolder implements InventoryHolder {
+    private final Inventory inv;
+    public MenuHolder(Component title, int size) {
+        this.inv = Bukkit.createInventory(this, size, title);
+    }
+    @Override public Inventory getInventory() { return inv; }
+}
+
+// 2. Di Listener:
+@EventHandler
+public void onMenuClick(InventoryClickEvent event) {
+    if (event.getInventory().getHolder() instanceof MenuHolder) {
+        event.setCancelled(true); // Selalu batalkan pergerakan item
+        ItemStack item = event.getCurrentItem();
+        if (item != null && item.hasItemMeta()) {
+            // Baca aksi dari PDC
+        }
+    }
+}
+```
+
+### Resep E: Universal Folia / Paper Scheduler Adapter
+```java
+public static void runForPlayer(Plugin plugin, Player player, Runnable runnable) {
+    try {
+        Class.forName("io.papermc.paper.threadedregions.RegionizedServer");
+        player.getScheduler().run(plugin, task -> runnable.run(), null);
+    } catch (ClassNotFoundException e) {
+        Bukkit.getScheduler().runTask(plugin, runnable);
+    }
+}
+```
+
+### Resep F: Raycast & Partikel Sihir
+```java
+Location eye = player.getEyeLocation();
+Vector dir = eye.getDirection().normalize();
+
+for (double d = 1; d <= 25; d += 0.5) {
+    Location p = eye.clone().add(dir.clone().multiply(d));
+    player.getWorld().spawnParticle(Particle.FLAME, p, 1, 0, 0, 0, 0);
+}
+```
+
+---
+
+## 4. Anti-Patterns yang Wajib Dihindari
+
+| Jangan Pernah Dilakukan ❌ | Cara yang Benar ✔️ |
+| :--- | :--- |
+| `ChatColor.RED + "Pesan"` | `MiniMessage.miniMessage().deserialize("<red>Pesan</red>")` |
+| `public static Set<Player> players;` | `public static Set<UUID> playerUuids;` (Cegah memory leak) |
+| `Bukkit.getScheduler()` di server Folia | Gunakan `RegionScheduler`, `EntityScheduler`, atau `AsyncScheduler` |
+| `world.getChunkAt(x, z)` acak di loop | `world.getChunkAtAsync(x, z)` |
+| `new NamespacedKey(...)` per hit/tick | Simpan `NamespacedKey` di `public static final` |
+| Mencocokkan nama item lore untuk aksi GUI | Gunakan `PersistentDataContainer` (PDC) pada item |
+| Query database di tick thread | Jalankan via `CompletableFuture.supplyAsync(...)` |
+
+---
+
+## 5. Referensi Kode Asli di Folder `references/`
+
+- **Arsitektur Enterprise & Database Async**: Periksa [`references/luckperms`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/luckperms).
+- **Performa Async Chunks & Schedulers**: Periksa [`references/chunky`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/chunky).
+- **Paperweight & Incendo Cloud Commands**: Periksa [`references/squaremap`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/squaremap).
+- **MiniMessage & Paper Manifest**: Periksa [`references/miniplaceholders`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/miniplaceholders).
+- **Ekonomi & Permissions Hooking**: Periksa [`references/vault-api`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/vault-api).
+- **Setup Server Pengujian Otomatis**: Periksa [`references/run-paper`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/run-paper).
+- **Display Packet & Hologram**: Periksa [`references/decentholograms`](file:///Users/ardianryan/Documents/minecraft-plugin-skill/references/decentholograms).

package/templates/paper-modern-template/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = off

package/templates/paper-modern-template/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Sat Sep 05 14:25:51 UTC 2026
+gradle.version=9.4.1