papermc-skill 1.0.0 → 1.1.0

package/docs/01-modern-paper-architecture.md

@@ -1,55 +1,52 @@
-# Arsitektur Modern Plugin Paper Minecraft Java
+# Modern Minecraft Java Plugin Architecture (Paper & Folia)
 
-Dokumen ini membahas arsitektur modern pembuatan plugin untuk server Paper Minecraft Java (khususnya versi 1.20+ dan 1.21+), mencakup build tools, konfigurasi manifest, lifecycle bootstrapping, dan sistem pemetaan (Mojang mappings).
+This guide explores the modern architectural patterns for building Minecraft Java plugins on PaperMC (specifically versions 1.20+ and 1.21+), covering build tooling, manifest configuration, lifecycle bootstrapping, and native Mojang mappings.
 
 ---
 
-## 1. Evolusi Arsitektur: Spigot vs Modern Paper
+## 1. Architectural Evolution: Legacy Spigot vs Modern Paper
 
-Secara historis, plugin Minecraft dibuat di atas Bukkit/Spigot API dengan `plugin.yml` dan Maven/Gradle sederhana. Namun, ekosistem Paper modern telah merevolusi cara kerja plugin:
+Historically, plugins were built on the Bukkit/Spigot API using `plugin.yml` and straightforward Maven/Gradle configurations. However, modern Paper has revolutionized plugin architecture:
 
-| Fitur | Spigot Legacy | Modern Paper (1.20.6+ / 1.21+) |
+| Feature | Legacy Spigot | Modern Paper (1.20.6+ / 1.21+) |
 | :--- | :--- | :--- |
-| **Manifest File** | `plugin.yml` | `paper-plugin.yml` (atau hybrid) |
-| **Text Handling** | `ChatColor` & legacy string formatting (`§a`) | Kyori Adventure & MiniMessage (`Component`) |
-| **Lifecycle Hook** | Hanya `JavaPlugin.onLoad` & `onEnable` | `PluginBootstrap` + `JavaPlugin` + `LifecycleEvents` |
-| **Command System** | `getCommand("...").setExecutor(...)` | Paper Brigadier Native (`LifecycleEvents.COMMANDS`) atau Cloud |
-| **Mapping NMS** | Obfuscated Spigot mapping (`reobf`) | Mojang Mappings langsung di runtime (1.20.5+) via Paperweight |
-| **Multi-threading** | Single main thread (`BukkitScheduler`) | Multi-thread regionized ready (Folia & Schedulers terpisah) |
+| **Manifest File** | `plugin.yml` | `paper-plugin.yml` (or hybrid) |
+| **Text Handling** | `ChatColor` & legacy formatting (`§a`) | Kyori Adventure & MiniMessage (`Component`) |
+| **Lifecycle Hooks** | Only `JavaPlugin.onLoad` & `onEnable` | `PluginBootstrap` + `JavaPlugin` + `LifecycleEvents` |
+| **Command Engine** | `getCommand("...").setExecutor(...)` | Paper Native Brigadier (`LifecycleEvents.COMMANDS`) or Cloud |
+| **NMS Mappings** | Obfuscated Spigot mappings (`reobf`) | Runtime Mojang Mappings (1.20.5+) via Paperweight |
+| **Multi-Threading** | Single main thread (`BukkitScheduler`) | Multi-threaded region ticking (Folia & region schedulers) |
 
 ---
 
 ## 2. Build Tooling: Gradle & Paperweight Userdev
 
-Standard industri modern untuk proyek Paper adalah **Gradle (Kotlin DSL - `.gradle.kts`)** menggunakan plugin **`paperweight-userdev`** dari PaperMC.
+The modern industry standard for Paper projects is **Gradle (Kotlin DSL - `.gradle.kts`)** using PaperMC's **`paperweight-userdev`** plugin.
 
-### Keunggulan Paperweight Userdev:
-- Menyediakan akses ke **Mojang Mappings (NMS)** langsung tanpa alat deobfuscation eksternal yang rumit.
-- Sejak Paper 1.20.5+, server Paper menjalankan Mojang Mappings secara native di runtime.
-- Terintegrasi dengan plugin `xyz.jpenilla.run-paper` untuk menjalankan test server Paper/Folia langsung dengan satu perintah gradle (`./gradlew runServer`).
+### Key Benefits of Paperweight Userdev:
+- Direct access to **Mojang Mappings (NMS)** without cumbersome external deobfuscation workflows.
+- Starting from Paper 1.20.5+, Paper servers run native Mojang Mappings in production at runtime.
+- Seamless integration with `xyz.jpenilla.run-paper` to launch automated Paper/Folia test servers with a single command (`./gradlew runServer`).
 
-### Contoh `build.gradle.kts`:
+### Example `build.gradle.kts`:
 
 ```kotlin
 plugins {
     `java-library`
     id("io.papermc.paperweight.userdev") version "2.0.0-beta.21"
-    id("xyz.jpenilla.run-paper") version "3.0.2" // Task ./gradlew runServer
-    id("com.gradleup.shadow") version "8.3.6"    // Shadow jar bila menggunakan dependensi eksternal
+    id("xyz.jpenilla.run-paper") version "3.1.0" // Task: ./gradlew runServer
+    id("com.gradleup.shadow") version "8.3.6"    // Shadow jar for bundled external libraries
 }
 
 group = "com.example"
 version = "1.0.0-SNAPSHOT"
 
 java {
-    toolchain.languageVersion.set(JavaLanguageVersion.of(21)) // Minecraft 1.20.5+ membutuhkan minimal Java 21
+    toolchain.languageVersion.set(JavaLanguageVersion.of(21)) // Minecraft 1.20.5+ requires Java 21+
 }
 
 dependencies {
-    paperweight.paperDevBundle("1.21.4-R0.1-SNAPSHOT")
-    
-    // Contoh library umum
-    // implementation("org.incendo:cloud-paper:2.0.0-beta.10")
+    paperweight.paperDevBundle("1.21.11-R0.1-SNAPSHOT")
 }
 
 tasks {
@@ -59,8 +56,8 @@ tasks {
     }
     
     shadowJar {
-        archiveClassifier.set("") // Menjadikan output shadow jar sebagai artifact utama
-        // relocate package eksternal agar tidak bentrok dengan plugin lain
+        archiveClassifier.set("") // Set shaded jar as default artifact output
+        // Relocate external packages to prevent classpath collisions:
         // relocate("org.incendo.cloud", "com.example.plugin.libs.cloud")
     }
 }
@@ -68,16 +65,16 @@ tasks {
 
 ---
 
-## 3. Konfigurasi `paper-plugin.yml`
+## 3. Manifest Configuration: `paper-plugin.yml`
 
-Modern Paper menggunakan manifest `paper-plugin.yml` yang terletak di `src/main/resources/paper-plugin.yml`.
+Modern Paper introduces the `paper-plugin.yml` manifest located at `src/main/resources/paper-plugin.yml`.
 
-### Keuntungan `paper-plugin.yml`:
-- Dukungan dependency loading yang jauh lebih fleksibel (bootstrapper dependencies, server dependencies).
-- Mendukung deklarasi bootstrapper class (`bootstrapper`).
-- Kompatibilitas multi-threaded Folia (`folia-supported: true`).
+### Advantages of `paper-plugin.yml`:
+- Granular dependency management (bootstrapper dependencies vs server runtime dependencies).
+- Declarative bootstrapper class definition (`bootstrapper`).
+- Explicit multi-threaded Folia compatibility (`folia-supported: true`).
 
-### Contoh Struktur `paper-plugin.yml`:
+### Example `paper-plugin.yml` Structure:
 
 ```yaml
 name: ExamplePlugin
@@ -92,7 +89,7 @@ authors:
 
 dependencies:
   bootstrap:
-    # Dependensi yang dibutuhkan pada fase bootstrap
+    # Dependencies required during the bootstrap phase
   server:
     Vault:
       load: BEFORE
@@ -105,21 +102,21 @@ dependencies:
 
 ---
 
-## 4. Lifecycle Baru: `PluginBootstrap` vs `JavaPlugin`
+## 4. Modern Lifecycle: `PluginBootstrap` vs `JavaPlugin`
 
-Paper memperkenalkan antarmuka `io.papermc.paper.plugin.bootstrap.PluginBootstrap`.
+Paper introduces the `io.papermc.paper.plugin.bootstrap.PluginBootstrap` interface.
 
-### Urutan Lifecycle Server Paper:
-1. **Plugin Loader Creation**: Resolusi classpath dan dependensi.
+### Server Lifecycle Sequence:
+1. **Plugin Loader Creation**: Classpath resolution and dependency wiring.
 2. **Bootstrap Phase (`PluginBootstrap#bootstrap`)**:
-   - Berjalan sangat awal sebelum world di-load.
-   - Digunakan untuk meregistrasi **Brigadier Commands**, modifikasi konfigurasi registry, dan setup resource global.
-3. **Plugin Instantiation**: Instance `JavaPlugin` dibuat.
-4. **`onLoad()`**: Mirip fase Spigot tradisional.
-5. **`onEnable()`**: Registrasi listener event, scheduler, inisialisasi database, dan setup UI/Game logic.
-6. **`onDisable()`**: Graceful shutdown, flush queue database, dan pembatalan task.
+   - Executes before worlds are loaded.
+   - Used to register **Brigadier Commands**, modify registry configurations, and set up global resources.
+3. **Plugin Instantiation**: The `JavaPlugin` instance is created.
+4. **`onLoad()`**: Equivalent to the legacy Bukkit phase.
+5. **`onEnable()`**: Event listener registration, schedulers, database connection pools, and UI/game logic setup.
+6. **`onDisable()`**: Graceful shutdown, database queue flushing, and task cancellation.
 
-### Contoh Implementasi Bootstrapper:
+### Bootstrapper Implementation Example:
 
 ```java
 package com.example.plugin;
@@ -134,16 +131,16 @@ public final class ExampleBootstrap implements PluginBootstrap {
 
     @Override
     public void bootstrap(final BootstrapContext context) {
-        // Registrasi Lifecycle Events seperti command handler modern
+        // Register Lifecycle Events such as modern Brigadier command handlers
         context.getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {
             final var registrar = event.registrar();
-            // Registrasi syntax Brigadier di sini
+            // Register Brigadier command nodes here
         });
     }
 }
 ```
 
-### Contoh Implementasi Main Plugin (`JavaPlugin`):
+### Main Plugin Implementation (`JavaPlugin`):
 
 ```java
 package com.example.plugin;
@@ -156,16 +153,16 @@ public final class ExamplePlugin extends JavaPlugin {
 
     @Override
     public void onEnable() {
-        // Menggunakan ComponentLogger modern Paper
+        // Using Paper's modern ComponentLogger
         getComponentLogger().info(
-            Component.text("ExamplePlugin berhasil diaktifkan!", NamedTextColor.GREEN)
+            Component.text("ExamplePlugin successfully enabled!", NamedTextColor.GREEN)
         );
     }
 
     @Override
     public void onDisable() {
         getComponentLogger().info(
-            Component.text("ExamplePlugin dimatikan secara aman.", NamedTextColor.RED)
+            Component.text("ExamplePlugin safely disabled.", NamedTextColor.RED)
         );
     }
 }

package/docs/02-adventure-and-minimessage.md

@@ -1,21 +1,21 @@
-# Adventure API & MiniMessage di Paper Minecraft
+# Adventure API & MiniMessage in Modern Paper
 
-Paper mengintegrasikan **Kyori Adventure** secara native sebagai antarmuka pemrosesan teks. Pendekatan lama yang menggunakan tanda warna section (`§a`, `§l`) atau `org.bukkit.ChatColor` telah **ditinggalkan (deprecated)** karena rentan merusak format teks, tidak mendukung RGB hex secara fleksibel, dan tidak modular.
+Paper integrates **Kyori Adventure** natively as its primary text interface. Legacy color formatting using section signs (`§a`, `§l`) or `org.bukkit.ChatColor` has been **deprecated** because it corrupts formatting across modern clients, lacks modularity, and cannot express 24-bit TrueColor RGB gradients cleanly.
 
 ---
 
-## 1. Mengapa Adventure & MiniMessage?
+## 1. Why Kyori Adventure & MiniMessage?
 
-- **Type-Safe Components**: Teks bukan sekadar string biasa melainkan hierarki objek `Component` yang immutable.
-- **Dukungan Warna Penuh**: Mendukung warna 24-bit TrueColor / Hex (`#FF5555`), Gradients, dan Rainbows.
-- **Interaktivitas Kaya**: Event klik (`run_command`, `suggest_command`, `open_url`), hover tooltip (`show_text`, `show_item`, `show_entity`), dan font kustom.
-- **MiniMessage Format**: String format yang sangat mudah dibaca manusia berbasis tag XML-like, aman dari injeksi formatting.
+- **Type-Safe Components**: Text is represented as an immutable hierarchy of `Component` objects rather than brittle strings.
+- **Full TrueColor Support**: Native 24-bit Hex colors (`#FF5555`), dynamic Gradients, and Rainbow transitions.
+- **Rich Interactivity**: Click events (`run_command`, `suggest_command`, `open_url`), hover tooltips (`show_text`, `show_item`, `show_entity`), and custom typography fonts.
+- **MiniMessage Format**: A human-readable XML-like syntax that prevents formatting injection vulnerabilities.
 
 ---
 
-## 2. Format Dasar MiniMessage
+## 2. Basic MiniMessage Usage
 
-Gunakan `net.kyori.adventure.text.minimessage.MiniMessage`:
+Use `net.kyori.adventure.text.minimessage.MiniMessage`:
 
 ```java
 import net.kyori.adventure.text.Component;
@@ -23,25 +23,25 @@ import net.kyori.adventure.text.minimessage.MiniMessage;
 
 final MiniMessage mm = MiniMessage.miniMessage();
 
-// Contoh teks berwarna dan bergradasi
-Component c1 = mm.deserialize("<gradient:#ff007f:#7f00ff><bold>Server RPG Terhebat</bold></gradient>");
-Component c2 = mm.deserialize("<gray>Klik <green><click:run_command:'/spawn'>DI SINI</click></green> untuk kembali ke spawn.</gray>");
-Component c3 = mm.deserialize("<hover:show_text:'<yellow>Status: Aktif</yellow>'>Arahkan kursor ke sini</hover>");
+// Colored and gradient text examples
+Component c1 = mm.deserialize("<gradient:#ff007f:#7f00ff><bold>Legendary RPG Server</bold></gradient>");
+Component c2 = mm.deserialize("<gray>Click <green><click:run_command:'/spawn'>HERE</click></green> to return to spawn.</gray>");
+Component c3 = mm.deserialize("<hover:show_text:'<yellow>Status: Online</yellow>'>Hover over me</hover>");
 ```
 
-### Tag MiniMessage Populer:
-- Warna bawaan: `<red>`, `<green>`, `<gold>`, `<aqua>`, `<dark_purple>`, `<white>`, dll.
-- Warna Hex: `<#rrggbb>` atau `<color:#rrggbb>`.
-- Format style: `<bold>` (`<b>`), `<italic>` (`<i>`), `<underlined>` (`<u>`), `<strikethrough>` (`<s>`), `<obfuscated>` (`<obf>`).
-- Gradasi warna: `<gradient:#55cdfc:#f7a8b8:#ffffff>Trans Rights</gradient>`.
-- Pelangi: `<rainbow>Teks pelangi dinamis</rainbow>`.
-- Reset gaya: `<reset>` atau penutupan tag `</red>`.
+### Popular MiniMessage Tags:
+- Named colors: `<red>`, `<green>`, `<gold>`, `<aqua>`, `<dark_purple>`, `<white>`, etc.
+- Hex colors: `<#rrggbb>` or `<color:#rrggbb>`.
+- Text styling: `<bold>` (`<b>`), `<italic>` (`<i>`), `<underlined>` (`<u>`), `<strikethrough>` (`<s>`), `<obfuscated>` (`<obf>`).
+- Gradients: `<gradient:#55cdfc:#f7a8b8:#ffffff>Trans Rights</gradient>`.
+- Rainbow: `<rainbow>Dynamic rainbow text</rainbow>`.
+- Style resets: `<reset>` or explicit closing tags like `</red>`.
 
 ---
 
-## 3. Dynamic Tag Resolvers (Placeholder Kustom)
+## 3. Dynamic Tag Resolvers (Custom Placeholders)
 
-MiniMessage menyediakan `TagResolver` untuk memasukkan variabel secara dinamis tanpa merusak parsing atau membuka celah string injection:
+MiniMessage provides `TagResolver` to insert dynamic variables safely without risking formatting injection:
 
 ```java
 import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;
@@ -50,7 +50,7 @@ import org.bukkit.entity.Player;
 
 public Component createWelcomeMessage(Player player, int coins) {
     return MiniMessage.miniMessage().deserialize(
-        "<gold>Selamat datang, <yellow><player_name></yellow>! Koin Anda: <green><coins></green></gold>",
+        "<gold>Welcome, <yellow><player_name></yellow>! Balance: <green><coins></green></gold>",
         TagResolver.resolver(
             Placeholder.component("player_name", player.displayName()),
             Placeholder.unparsed("coins", String.valueOf(coins))
@@ -59,28 +59,28 @@ public Component createWelcomeMessage(Player player, int coins) {
 }
 ```
 
-> **Perbedaan `component` vs `unparsed`**:
-> - `Placeholder.component(...)`: Menyisipkan child component yang sudah di-parse, mempertahankan format.
-> - `Placeholder.unparsed(...)`: Menyisipkan teks murni. Tag apapun di dalamnya **tidak** akan di-evaluasi sebagai tag MiniMessage (aman untuk input dari user/chat chatbox).
+> **`component` vs `unparsed`**:
+> - `Placeholder.component(...)`: Inserts an already-parsed child component, preserving rich formatting.
+> - `Placeholder.unparsed(...)`: Inserts raw literal text. Any formatting tags inside are **not** evaluated as MiniMessage tags (crucial for sanitizing chat input).
 
 ---
 
-## 4. Mengirim Pesan ke Audience
+## 4. Sending Messages to Audiences
 
-Di Paper, setiap entitas yang bisa menerima pesan mengimplementasikan antarmuka `net.kyori.adventure.audience.Audience` (termasuk `Player`, `ConsoleCommandSender`, dan `Server`).
+In Paper, every message receiver implements the `net.kyori.adventure.audience.Audience` interface (including `Player`, `ConsoleCommandSender`, and `Server`).
 
-### Chat Biasa & Console Logging
+### Standard Chat & Console Logging
 ```java
-// Mengirim ke pemain
-player.sendMessage(MiniMessage.miniMessage().deserialize("<aqua>Pesan masuk!</aqua>"));
+// Send to player
+player.sendMessage(MiniMessage.miniMessage().deserialize("<aqua>Incoming message!</aqua>"));
 
-// Mengirim via ComponentLogger pada plugin
-getComponentLogger().info(MiniMessage.miniMessage().deserialize("<green>Plugin siap melayani pemain!</green>"));
+// Send via ComponentLogger on the plugin instance
+getComponentLogger().info(MiniMessage.miniMessage().deserialize("<green>Plugin ready for connections!</green>"));
 ```
 
 ### Action Bar
 ```java
-player.sendActionBar(MiniMessage.miniMessage().deserialize("<red>Zona Bahaya!</red>"));
+player.sendActionBar(MiniMessage.miniMessage().deserialize("<red>Hazard Zone!</red>"));
 ```
 
 ### Titles & Subtitles
@@ -89,8 +89,8 @@ import net.kyori.adventure.title.Title;
 import java.time.Duration;
 
 final Title title = Title.title(
-    MiniMessage.miniMessage().deserialize("<gold><bold>KEMENANGAN!</bold></gold>"),
-    MiniMessage.miniMessage().deserialize("<gray>Anda memenangkan ronde ini</gray>"),
+    MiniMessage.miniMessage().deserialize("<gold><bold>VICTORY!</bold></gold>"),
+    MiniMessage.miniMessage().deserialize("<gray>You won this match</gray>"),
     Title.Times.times(Duration.ofMillis(500), Duration.ofSeconds(3), Duration.ofMillis(1000))
 );
 
@@ -102,16 +102,16 @@ player.showTitle(title);
 import net.kyori.adventure.bossbar.BossBar;
 
 BossBar bossBar = BossBar.bossBar(
-    MiniMessage.miniMessage().deserialize("<dark_red>Ender Dragon HP</dark_red>"),
+    MiniMessage.miniMessage().deserialize("<dark_red>Ender Dragon Health</dark_red>"),
     0.75f, // 75%
     BossBar.Color.RED,
     BossBar.Overlay.PROGRESS
 );
 
-// Tampilkan bossbar
+// Display boss bar
 player.showBossBar(bossBar);
 
-// Hapus bila sudah selesai
+// Remove when completed
 player.hideBossBar(bossBar);
 ```
 
@@ -132,9 +132,9 @@ player.playSound(sound);
 
 ---
 
-## 5. Serialisasi Item & Lore dengan Adventure
+## 5. Item Serialization & Lore with Adventure
 
-Saat membuat `ItemStack`, gunakan metode komponen `Component` alih-alih String lama:
+When constructing `ItemStack` instances, use `Component` methods instead of legacy raw strings:
 
 ```java
 import org.bukkit.Material;
@@ -143,18 +143,14 @@ import org.bukkit.inventory.meta.ItemMeta;
 import java.util.List;
 
 ItemStack sword = new ItemStack(Material.DIAMOND_SWORD);
-ItemMeta meta = sword.getItemMeta();
-
-if (meta != null) {
-    // Custom name menggunakan Component
-    meta.displayName(MiniMessage.miniMessage().deserialize("<gradient:#00c6ff:#0072ff><bold>Pedang Es Legendaris</bold></gradient>"));
+sword.editMeta(meta -> {
+    // Custom name using Component
+    meta.displayName(MiniMessage.miniMessage().deserialize("<gradient:#00c6ff:#0072ff><bold>Frostmourne Blade</bold></gradient>"));
     
-    // Lore menggunakan List<Component>
+    // Lore using List<Component>
     meta.lore(List.of(
-        MiniMessage.miniMessage().deserialize("<gray>Memberikan efek <aqua>Freeze</aqua> saat menyerang.</gray>"),
-        MiniMessage.miniMessage().deserialize("<dark_gray>Level: <gold>★★★★★</gold></dark_gray>")
+        MiniMessage.miniMessage().deserialize("<gray>Applies <aqua>Freeze</aqua> on hit.</gray>"),
+        MiniMessage.miniMessage().deserialize("<dark_gray>Tier: <gold>★★★★★</gold></dark_gray>")
     ));
-    
-    sword.setItemMeta(meta);
-}
+});
 ```

package/docs/03-persistent-data-container.md

@@ -1,19 +1,19 @@
-# PersistentDataContainer (PDC) di Paper Minecraft
+# PersistentDataContainer (PDC) in Modern Paper
 
-`PersistentDataContainer` (PDC) adalah API resmi Bukkit/Paper untuk menyimpan data kustom secara permanen pada objek dalam game seperti:
-- **Item (`ItemMeta`)**
-- **Entity (`Entity`, `LivingEntity`, `Player`)**
-- **Block State / Tile Entity (`TileState`)**
-- **Chunk (`Chunk`)**
-- **World (`World`)**
+`PersistentDataContainer` (PDC) is the official, type-safe Bukkit/Paper API for storing custom persistent metadata directly on in-game Minecraft objects, including:
+- **ItemStacks (`ItemMeta`)**
+- **Entities (`Entity`, `LivingEntity`, `Player`)**
+- **Block States / Tile Entities (`TileState`)**
+- **Chunks (`Chunk`)**
+- **Worlds (`World`)**
 
-PDC menggantikan ketergantungan pada library NBT pihak ketiga (seperti NBTAPI) atau pembacaan lore tersembunyi yang rapuh. Data yang disimpan di PDC disimpan langsung dalam NBT vanilla Minecraft dan otomatis disimpan/di-load bersama world data.
+PDC eliminates brittle dependencies on legacy third-party NBT libraries (like NBTAPI) or parsing hidden lore strings. Data placed in PDC is serialized natively into Minecraft's vanilla NBT and automatically saved and loaded alongside world saves.
 
 ---
 
-## 1. Konsep Kunci: NamespacedKey
+## 1. Key Concept: NamespacedKey
 
-Setiap nilai yang disimpan di PDC diidentifikasi oleh `NamespacedKey` unik yang terdiri dari `namespace` (biasanya nama plugin berhuruf kecil) dan `key`:
+Every value stored in PDC is addressed by a unique `NamespacedKey` comprising a `namespace` (typically your lowercase plugin name) and a `key` identifier:
 
 ```java
 import org.bukkit.NamespacedKey;
@@ -34,40 +34,37 @@ public final class DataKeys {
 
 ---
 
-## 2. Menyimpan & Membaca Tipe Data Primitif
+## 2. Storing & Reading Primitive Data Types
 
-PDC mendukung berbagai tipe bawaan melalui enum `PersistentDataType`:
+PDC supports standard primitive types via the `PersistentDataType` interface:
 - `PersistentDataType.STRING`
 - `PersistentDataType.INTEGER`
 - `PersistentDataType.LONG`
 - `PersistentDataType.DOUBLE`
 - `PersistentDataType.FLOAT`
-- `PersistentDataType.BYTE` (boolean sering disimpan sebagai byte `1` / `0`)
+- `PersistentDataType.BYTE` (booleans are stored as byte `1` / `0`)
 - `PersistentDataType.BYTE_ARRAY`
-- `PersistentDataType.TAG_CONTAINER` (PDC bersarang / nested)
+- `PersistentDataType.TAG_CONTAINER` (nested PDC structures)
 
-### Contoh Menyimpan Data pada ItemStack:
+### Example: Storing Metadata on an ItemStack
 ```java
 import org.bukkit.Material;
 import org.bukkit.inventory.ItemStack;
-import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.persistence.PersistentDataContainer;
 import org.bukkit.persistence.PersistentDataType;
 
 public ItemStack createTeleportWand(String wandId) {
     ItemStack wand = new ItemStack(Material.BLAZE_ROD);
-    ItemMeta meta = wand.getItemMeta();
-    if (meta != null) {
+    wand.editMeta(meta -> {
         PersistentDataContainer pdc = meta.getPersistentDataContainer();
         pdc.set(DataKeys.CUSTOM_ID, PersistentDataType.STRING, wandId);
         pdc.set(DataKeys.COOLDOWN_TIMESTAMP, PersistentDataType.LONG, System.currentTimeMillis());
-        wand.setItemMeta(meta);
-    }
+    });
     return wand;
 }
 ```
 
-### Contoh Membaca & Memvalidasi Data pada ItemStack:
+### Example: Reading & Validating ItemStack Metadata
 ```java
 public boolean isCustomWand(ItemStack item) {
     if (item == null || !item.hasItemMeta()) return false;
@@ -84,42 +81,45 @@ public String getWandId(ItemStack item) {
 
 ---
 
-## 3. Menyimpan Data pada Entitas dan Chunk
+## 3. Storing Metadata on Entities and Chunks
 
-PDC juga dapat diakses langsung pada entitas dan chunk tanpa meta terpisah:
+PDC is accessible directly on entities and chunks without wrapping metadata:
 
 ```java
 import org.bukkit.entity.Entity;
 import org.bukkit.Chunk;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
 
-// Menandai entitas khusus (misal Custom Boss)
+// Tagging custom entities (e.g. Dungeon Boss)
 public void markAsCustomBoss(Entity entity, String bossType) {
     entity.getPersistentDataContainer().set(DataKeys.CUSTOM_ID, PersistentDataType.STRING, bossType);
 }
 
-// Menandai chunk yang telah diproses oleh plugin
-public void markChunkProcessed(Chunk chunk) {
-    chunk.getPersistentDataContainer().set(new NamespacedKey("myplugin", "processed"), PersistentDataType.BYTE, (byte) 1);
+// Tagging chunks processed by your world generation systems
+public void markChunkProcessed(Chunk chunk, NamespacedKey key) {
+    chunk.getPersistentDataContainer().set(key, PersistentDataType.BYTE, (byte) 1);
 }
 ```
 
 ---
 
-## 4. Tipe Data Kustom (Complex Object Serialization)
+## 4. Custom Complex Data Types (`PersistentDataType<T, Z>`)
 
-Kita dapat mengimplementasikan antarmuka `PersistentDataType<T, Z>` kustom untuk menyimpan objek kompleks (seperti record/POJO) ke dalam PDC tanpa perlu serialisasi JSON manual di setiap panggilan.
+You can implement custom `PersistentDataType<T, Z>` adapters to store complex Java objects (such as records or POJOs) directly into PDC without manual JSON conversions on every invocation.
 
-### Contoh Record Objek:
+### Object Record:
 ```java
 public record ItemStats(int damageBonus, double critChance, int durability) {}
 ```
 
-### Implementasi `PersistentDataType` Kustom:
+### Custom `PersistentDataType` Adapter:
 ```java
+import org.bukkit.NamespacedKey;
 import org.bukkit.persistence.PersistentDataAdapterContext;
 import org.bukkit.persistence.PersistentDataContainer;
 import org.bukkit.persistence.PersistentDataType;
-import org.bukkit.NamespacedKey;
+import org.bukkit.plugin.Plugin;
 
 public final class ItemStatsDataType implements PersistentDataType<PersistentDataContainer, ItemStats> {
 
@@ -127,7 +127,7 @@ public final class ItemStatsDataType implements PersistentDataType<PersistentDat
     private final NamespacedKey critKey;
     private final NamespacedKey durabilityKey;
 
-    public ItemStatsDataType(org.bukkit.plugin.Plugin plugin) {
+    public ItemStatsDataType(Plugin plugin) {
         this.damageKey = new NamespacedKey(plugin, "damage");
         this.critKey = new NamespacedKey(plugin, "crit");
         this.durabilityKey = new NamespacedKey(plugin, "durability");
@@ -162,18 +162,18 @@ public final class ItemStatsDataType implements PersistentDataType<PersistentDat
 }
 ```
 
-### Penggunaan Langsung:
+### Usage:
 ```java
 ItemStats stats = new ItemStats(25, 0.15, 500);
 pdc.set(DataKeys.ITEM_STATS, new ItemStatsDataType(plugin), stats);
 
-// Membaca kembali:
+// Read back:
 ItemStats loadedStats = pdc.get(DataKeys.ITEM_STATS, new ItemStatsDataType(plugin));
 ```
 
 ---
 
-## 5. Best Practices PDC
-1. **Gunakan Singleton Keys**: Jangan instansiasi `new NamespacedKey(...)` berulang kali di hot-loop (seperti `EntityDamageByEntityEvent`); simpan sebagai static final constants.
-2. **Namespace Konsisten**: Selalu gunakan plugin instance untuk key namespace agar tidak terjadi tabrakan dengan plugin lain.
-3. **Pembersihan Data**: Hapus data yang tidak lagi valid menggunakan `pdc.remove(key)` untuk menghemat ukuran file world/NBT.
+## 5. PDC Best Practices
+1. **Singleton Keys**: Never instantiate `new NamespacedKey(...)` repeatedly in hot event loops; define static final constants.
+2. **Consistent Namespaces**: Always use your plugin instance namespace to prevent collisions with third-party plugins.
+3. **Data Cleanup**: Clean up stale metadata using `pdc.remove(key)` to minimize world save file sizes.