papermc-skill 1.0.1 → 1.1.0

package/docs/04-commands-and-brigadier.md

@@ -1,17 +1,17 @@
-# Command System Modern: Brigadier & Cloud di Paper
+# Modern Command Systems: Native Brigadier & Cloud in Paper
 
-Sistem command di Minecraft Java berevolusi signifikan. Metode lama Bukkit seperti `CommandExecutor`, `TabCompleter`, dan deklarasi perintah di `plugin.yml` kini digantikan oleh:
-1. **Paper Native Brigadier API** (diperkenalkan di Paper 1.20.6+ melalui `LifecycleEvents.COMMANDS`).
-2. **Incendo Cloud Framework** (`cloud-paper`): Standar industri untuk framework command berbasis anotasi / builder yang sangat fleksibel dan multi-platform.
+The Minecraft Java command system has evolved substantially. Legacy Bukkit patterns like `CommandExecutor`, `TabCompleter`, and command declarations in `plugin.yml` have been superseded by:
+1. **Paper Native Brigadier API** (introduced in Paper 1.20.6+ via `LifecycleEvents.COMMANDS`).
+2. **Incendo Cloud Framework** (`cloud-paper`): The enterprise standard for annotation-driven and builder-based multi-platform command handling.
 
 ---
 
 ## 1. Native Paper Brigadier Commands (Paper 1.20.6+)
 
-Mojang Brigadier adalah command dispatcher engine resmi Minecraft. Paper mengekspos API Brigadier secara langsung tanpa perlu hack NMS atau dependensi tambahan.
+Mojang Brigadier is Minecraft's official command dispatcher and parser engine. Paper exposes native Brigadier bindings directly without requiring NMS hacks or external shading.
 
-### Registrasi Melalui Lifecycle Events
-Command didaftarkan saat fase Bootstrap atau saat event `LifecycleEvents.COMMANDS` dipicu:
+### Registering Commands via Lifecycle Events
+Commands are registered during the Bootstrap phase or when the `LifecycleEvents.COMMANDS` event triggers:
 
 ```java
 package com.example.plugin;
@@ -24,7 +24,6 @@ import io.papermc.paper.plugin.bootstrap.BootstrapContext;
 import io.papermc.paper.plugin.bootstrap.PluginBootstrap;
 import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;
 import net.kyori.adventure.text.minimessage.MiniMessage;
-import org.bukkit.entity.Player;
 
 public final class CommandBootstrapper implements PluginBootstrap {
 
@@ -33,11 +32,11 @@ public final class CommandBootstrapper implements PluginBootstrap {
         context.getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {
             final Commands commands = event.registrar();
 
-            // Membangun pohon syntax command /teleportzone <nama> [radius]
+            // Construct syntax tree: /teleportzone <name> [radius]
             commands.register(
                 Commands.literal("teleportzone")
                     .requires(source -> source.getSender().hasPermission("plugin.command.teleportzone"))
-                    .then(Commands.argument("nama", StringArgumentType.word())
+                    .then(Commands.argument("name", StringArgumentType.word())
                         .suggests((ctx, builder) -> {
                             builder.suggest("lobby");
                             builder.suggest("arena");
@@ -47,12 +46,12 @@ public final class CommandBootstrapper implements PluginBootstrap {
                         .then(Commands.argument("radius", IntegerArgumentType.integer(1, 100))
                             .executes(ctx -> {
                                 final CommandSourceStack source = ctx.getSource();
-                                final String zone = StringArgumentType.getString(ctx, "nama");
+                                final String zone = StringArgumentType.getString(ctx, "name");
                                 final int radius = IntegerArgumentType.getInteger(ctx, "radius");
 
                                 source.getSender().sendMessage(
                                     MiniMessage.miniMessage().deserialize(
-                                        "<green>Mempersiapkan teleportasi ke zona <gold>" + zone + "</gold> dengan radius <yellow>" + radius + "</yellow>!</green>"
+                                        "<green>Preparing teleportation to zone <gold>" + zone + "</gold> with radius <yellow>" + radius + "</yellow>!</green>"
                                     )
                                 );
                                 return com.mojang.brigadier.Command.SINGLE_SUCCESS;
@@ -60,43 +59,42 @@ public final class CommandBootstrapper implements PluginBootstrap {
                         )
                         .executes(ctx -> {
                             final CommandSourceStack source = ctx.getSource();
-                            final String zone = StringArgumentType.getString(ctx, "nama");
+                            final String zone = StringArgumentType.getString(ctx, "name");
                             source.getSender().sendMessage(
-                                MiniMessage.miniMessage().deserialize("<green>Teleportasi default ke zona <gold>" + zone + "</gold>!</green>")
+                                MiniMessage.miniMessage().deserialize("<green>Default teleportation to zone <gold>" + zone + "</gold>!</green>")
                             );
                             return com.mojang.brigadier.Command.SINGLE_SUCCESS;
                         })
                     )
                     .build(),
-                "Perintah teleportasi zona modern",
-                java.util.List.of("tpzone") // alias
+                "Modern zone teleportation command",
+                java.util.List.of("tpzone") // aliases
             );
         });
     }
 }
 ```
 
-### Keuntungan Paper Brigadier:
-- **Client-Side Syntax Highlighting**: Minecraft client dapat menandai teks merah saat syntax salah sebelum perintah ditekan.
-- **Auto Tab-Completion**: Tidak perlu menulis logika `TabCompleter` manual yang rumit.
-- **Validasi Tipe Otomatis**: Argument validasi otomatis ditangani (angka out-of-range otomatis ditolak).
+### Advantages of Native Paper Brigadier:
+- **Client-Side Syntax Highlighting**: Minecraft clients highlight syntax errors in real-time before sending the command packet.
+- **Automated Tab-Completion**: Eliminates complex manual `TabCompleter` string matching.
+- **Strict Argument Typing**: Automatically validates argument bounds and rejects invalid types.
 
 ---
 
 ## 2. Incendo Cloud Command Framework (`cloud-paper`)
 
-Untuk plugin yang membutuhkan dependensi injeksi, parsing objek otomatis (seperti `Player`, `OfflinePlayer`, `World`, `Duration`), dan command yang sangat banyak, **Cloud** adalah pilihan terpopuler.
+For large plugin codebases requiring dependency injection, automatic Bukkit argument parsing (`Player`, `OfflinePlayer`, `World`, `Duration`), and hundreds of sub-commands, **Incendo Cloud** is the leading solution.
 
-### Dependensi Gradle:
+### Gradle Dependencies:
 ```kotlin
 dependencies {
     implementation("org.incendo:cloud-paper:2.0.0-beta.10")
-    // atau cloud-annotations jika menyukai gaya @Command
     implementation("org.incendo:cloud-annotations:2.0.0-beta.10")
 }
 ```
 
-### Inisialisasi Cloud PaperCommandManager:
+### Initializing Cloud PaperCommandManager:
 ```java
 import org.incendo.cloud.paper.PaperCommandManager;
 import org.incendo.cloud.execution.ExecutionCoordinator;
@@ -111,8 +109,7 @@ public class PluginCommands {
             ExecutionCoordinator.simpleCoordinator()
         );
 
-        // Daftarkan brigadier mapper jika didukung
-        if (manager.hasCapability(org.incendo.cloud.paper.PaperCommandManager.Capability.BRIGADIER)) {
+        if (manager.hasCapability(PaperCommandManager.Capability.BRIGADIER)) {
             manager.registerBrigadier();
         }
 
@@ -121,7 +118,7 @@ public class PluginCommands {
 }
 ```
 
-### Contoh Perintah dengan Cloud Builder:
+### Building Commands with Cloud:
 ```java
 import org.incendo.cloud.paper.PaperCommandManager;
 import org.incendo.cloud.bukkit.parser.PlayerParser;
@@ -138,8 +135,8 @@ public void registerGiveRewardCommand(PaperCommandManager<CommandSender> manager
                 CommandSender sender = commandContext.sender();
                 Player target = commandContext.get("target");
 
-                target.sendMessage(MiniMessage.miniMessage().deserialize("<gold>Kamu menerima hadiah spesial!</gold>"));
-                sender.sendMessage(MiniMessage.miniMessage().deserialize("<green>Hadiah terkirim ke " + target.getName() + ".</green>"));
+                target.sendMessage(MiniMessage.miniMessage().deserialize("<gold>You received a special reward!</gold>"));
+                sender.sendMessage(MiniMessage.miniMessage().deserialize("<green>Reward dispatched to " + target.getName() + ".</green>"));
             })
     );
 }
@@ -147,11 +144,11 @@ public void registerGiveRewardCommand(PaperCommandManager<CommandSender> manager
 
 ---
 
-## 3. Komparasi: Kapan Memilih Apa?
+## 3. Comparison: When to Use Which?
 
-| Aspek | Paper Native Brigadier | Incendo Cloud |
+| Aspect | Paper Native Brigadier | Incendo Cloud |
 | :--- | :--- | :--- |
-| **Ukuran Jar** | Zero-dependency (bawaan Paper) | Menambahkan lib ~300KB-800KB (butuh shadow/relocate) |
-| **Kemudahan** | Cocok untuk command sederhana-menengah | Sangat baik untuk ratusan sub-command |
-| **Argument Parser** | Perlu mapping manual untuk tipe Bukkit | Built-in parser untuk Player, Location, Selector, dll |
-| **Portabilitas** | Hanya berjalan di Paper 1.20.6+ | Mendukung Velocity, Bungee, Fabric, Paper |
+| **Artifact Overhead** | Zero-dependency (built directly into Paper) | Adds ~300KB-800KB (requires shadowing & relocating) |
+| **Complexity Fit** | Best for small-to-medium command suites | Best for complex enterprise command structures |
+| **Parsers** | Requires manual mapping for Bukkit types | Built-in parsers for Players, Locations, Selectors, etc. |
+| **Portability** | Paper 1.20.6+ exclusive | Cross-platform (Velocity, BungeeCord, Fabric, Paper) |

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

@@ -1,38 +1,38 @@
-# Konkurensi, Threading & Kompatibilitas Folia
+# Concurrency, Threading & Folia Multi-Thread Compatibility
 
-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**).
+One of the most revolutionary milestones in the PaperMC ecosystem is the emergence of **Folia**. Folia breaks Minecraft's monolithic "Server Main Thread" into hundreds of independent regional threads (**Threaded Regions**).
 
-Konsekuensinya, metode konkurensi lama seperti `Bukkit.getScheduler()` atau mengakses state world dari sembarang thread akan menyebabkan **`IllegalStateException` atau crash fatal** di Folia.
+Consequently, legacy Bukkit concurrency assumptions like `Bukkit.getScheduler()` or mutating world state from arbitrary threads result in **`IllegalStateException` crashes or data corruption** on Folia.
 
 ---
 
-## 1. Model Threading: Bukkit vs Paper vs Folia
+## 1. Threading Architecture: 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 ──>
+Single Main Thread ─── Ticks All Worlds, Entities, Blocks, Redstone, AI, Chunks ───>
+
+[Folia Regionized Multi-Threading]
+Region Thread 1  ─── Ticks Overworld Region A (Chunks 0..32, 0..32) ───>
+Region Thread 2  ─── Ticks Overworld Region B (Chunks 64..96, 64..96) ──>
+Region Thread 3  ─── Ticks Nether Region C ────────────────────────────>
+Global Thread    ─── Ticks 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`.
+In Folia:
+- There is no single "Main Thread".
+- `World`, `Entity`, and `Block` instances may only be queried or mutated on the **region thread owning that coordinate/chunk**.
+- Accessing an entity from a foreign region thread throws `IllegalStateException: Plugin attempted to access entity from wrong thread`.
 
 ---
 
-## 2. Hirarki Scheduler Modern di Folia & Paper
+## 2. Modern Scheduler Hierarchy in Paper & Folia
 
-Paper memperkenalkan scheduler baru yang kompatibel dengan Folia dan Paper standar:
+Paper introduces clean scheduler primitives that operate seamlessly across both multi-threaded Folia and single-threaded Paper:
 
 ### 1. `RegionScheduler`
-Digunakan untuk mengeksekusi task pada lokasi dunia atau koordinat chunk tertentu.
+Used to execute tasks bound to specific world coordinates or chunks:
 
 ```java
 import org.bukkit.Bukkit;
@@ -41,59 +41,59 @@ import org.bukkit.plugin.Plugin;
 
 Location loc = player.getLocation();
 
-// Menjalankan task 1-kali pada thread region lokasi tersebut
+// Run a one-time task on the region thread owning this location
 Bukkit.getRegionScheduler().execute(plugin, loc, () -> {
     loc.getBlock().setType(org.bukkit.Material.GOLD_BLOCK);
 });
 
-// Menjalankan task berulang (repeating) pada region
+// Run a repeating task on the region thread
 Bukkit.getRegionScheduler().runAtFixedRate(plugin, loc, task -> {
     loc.getWorld().spawnParticle(org.bukkit.Particle.FLAME, loc, 5);
-}, 20L, 20L); // delay 20 tick, period 20 tick
+}, 20L, 20L); // 20 ticks initial delay, 20 ticks period
 ```
 
 ### 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.
+Every `Entity` owns its own dedicated scheduler. Tasks execute directly on whichever region thread the entity currently occupies, even across chunk border transitions:
 
 ```java
 player.getScheduler().run(plugin, task -> {
     player.giveExp(10);
-    player.sendMessage("Bonus EXP didapatkan!");
+    player.sendMessage("Bonus EXP received!");
 }, () -> {
-    // Callback jika entity telah mati atau tidak valid sebelum task sempat berjalan
-    plugin.getLogger().warning("Pemain logout sebelum exp diberikan.");
+    // Retired callback if entity is dead or invalidated before execution
+    plugin.getLogger().warning("Player disconnected before reward was applied.");
 });
 ```
 
 ### 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).
+Used for server-wide tasks unconfined to specific coordinates (e.g., global announcements, world time, or weather):
 
 ```java
 Bukkit.getGlobalRegionScheduler().runAtFixedRate(plugin, task -> {
-    Bukkit.broadcast(MiniMessage.miniMessage().deserialize("<gold>[Pengumuman] Kunjungi discord kami!</gold>"));
+    Bukkit.broadcast(MiniMessage.miniMessage().deserialize("<gold>[Announcement] Join our Discord server!</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:
+Used for I/O, database interactions, HTTP calls, and non-Bukkit mathematical computations. Operates using wall-clock time (`java.time.TimeUnit`) rather than game ticks:
 
 ```java
 import java.util.concurrent.TimeUnit;
 
 Bukkit.getAsyncScheduler().runDelayed(plugin, task -> {
-    // Menjalankan query database MySQL / SQLite
+    // Run database query off the game thread
     database.savePlayerData(uuid, data);
 }, 5, TimeUnit.SECONDS);
 ```
 
 ---
 
-## 3. Pola Abstraksi Scheduler Universal (Paper + Folia)
+## 3. Universal Scheduler Abstraction Pattern (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**:
+Most production plugins must run identically on standard single-threaded Paper and multi-threaded Folia. The recommended approach is an abstraction layer (as pioneered by **Chunky** and **squaremap**):
 
 ```java
-public final class PlatformScheduler {
+public final class UniversalScheduler {
 
     private static final boolean IS_FOLIA = checkFolia();
 
@@ -110,7 +110,7 @@ public final class PlatformScheduler {
         return IS_FOLIA;
     }
 
-    public static void runLocation(Plugin plugin, Location location, Runnable runnable) {
+    public static void runAtLocation(Plugin plugin, Location location, Runnable runnable) {
         if (IS_FOLIA) {
             Bukkit.getRegionScheduler().execute(plugin, location, runnable);
         } else {
@@ -118,7 +118,7 @@ public final class PlatformScheduler {
         }
     }
 
-    public static void runEntity(Plugin plugin, Entity entity, Runnable runnable) {
+    public static void runForEntity(Plugin plugin, Entity entity, Runnable runnable) {
         if (IS_FOLIA) {
             entity.getScheduler().run(plugin, task -> runnable.run(), null);
         } else {
@@ -138,13 +138,13 @@ public final class PlatformScheduler {
 
 ---
 
-## 4. Aturan Wajib untuk Kompatibilitas Folia
+## 4. Mandatory Folia Compatibility Rules
 
-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.
+1. **Declare Compatibility in Manifest**:
+   Always include `folia-supported: true` in `paper-plugin.yml`. Without this, Folia flags your plugin as potentially hazardous upon boot.
+2. **Never Read Chunks/Blocks Synchronously Off-Thread**:
+   Always invoke `world.getChunkAtAsync(x, z)` which returns a `CompletableFuture<Chunk>`.
+3. **Use TeleportAsync**:
+   Always call `entity.teleportAsync(location)` instead of `entity.teleport(location)`. Across Folia, cross-region movement must be processed asynchronously.
+4. **Avoid Global Mutable Static Collections**:
+   Static lists of active players or entities experience severe race conditions when mutated by multiple region threads concurrently. Use thread-safe structures (`ConcurrentHashMap`) or delegate state to player PDC.

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

@@ -1,12 +1,12 @@
-# Sistem Event & Listener di Paper
+# Event System & Paper Listeners
 
-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.
+The event bus is Paper's primary reactive mechanism for responding to player interactions, world updates, entity behaviors, and server lifecycle states. Paper provides exclusive high-performance events along with native Kyori Adventure Component integration.
 
 ---
 
-## 1. Anatomi Listener Standar
+## 1. Anatomy of a Modern Listener
 
-Listener mengimplementasikan antarmuka `org.bukkit.event.Listener` dan menggunakan anotasi `@EventHandler`:
+Listeners implement the `org.bukkit.event.Listener` interface and decorate handler methods with `@EventHandler`:
 
 ```java
 import org.bukkit.event.Listener;
@@ -26,35 +26,35 @@ public final class PlayerJoinListener implements Listener {
 
     @EventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)
     public void onPlayerJoin(PlayerJoinEvent event) {
-        // Paper menggunakan Adventure Component untuk joinMessage
+        // Paper natively uses Adventure Components for join messages
         event.joinMessage(
             MiniMessage.miniMessage().deserialize(
-                "<gray>[<green>+</green>] <yellow>" + event.getPlayer().getName() + "</yellow> bergabung ke server!</gray>"
+                "<gray>[<green>+</green>] <yellow>" + event.getPlayer().getName() + "</yellow> joined the server!</gray>"
             )
         );
     }
 }
 ```
 
-### Memahami `EventPriority`:
-Urutan eksekusi event dari pertama hingga terakhir:
-1. `LOWEST` (dijalankan paling awal, bagus untuk observasi mentah)
+### Understanding `EventPriority`:
+Execution sequence from first to last:
+1. `LOWEST` (Runs first, ideal for raw observation or early preprocessing)
 2. `LOW`
-3. `NORMAL` (default)
+3. `NORMAL` (Default priority)
 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).
+5. `HIGHEST` (Runs last before final decision)
+6. `MONITOR` (**READ-ONLY / LOGGING ONLY**; strictly forbidden from modifying or cancelling events, as downstream plugins cannot observe changes).
 
-> **Penting**: Selalu tambahkan `ignoreCancelled = true` jika listener Anda tidak perlu memproses aksi yang sudah dibatalkan oleh plugin proteksi area (seperti WorldGuard/GriefPrevention).
+> **Important**: Always specify `ignoreCancelled = true` if your listener does not need to process interactions already prevented by land protection plugins (such as WorldGuard or GriefPrevention).
 
 ---
 
-## 2. Event Modern Eksklusif Paper
+## 2. Modern Paper-Exclusive Events
 
-Paper mengganti atau melengkapi beberapa event Bukkit lama dengan alternatif yang lebih efisien dan modern:
+Paper introduces modern, high-performance replacements for legacy Bukkit events:
 
-### `AsyncChatEvent` (Menggantikan `AsyncPlayerChatEvent`)
-Paper menggunakan `io.papermc.paper.event.player.AsyncChatEvent` yang bekerja langsung dengan `Component` dan MiniMessage:
+### `AsyncChatEvent` (Replaces `AsyncPlayerChatEvent`)
+Paper's `io.papermc.paper.event.player.AsyncChatEvent` operates directly with `Component` and MiniMessage:
 
 ```java
 import io.papermc.paper.event.player.AsyncChatEvent;
@@ -63,7 +63,7 @@ import net.kyori.adventure.text.minimessage.MiniMessage;
 
 @EventHandler
 public void onChat(AsyncChatEvent event) {
-    // Memodifikasi format pesan dengan Adventure
+    // Format chat messages cleanly using Adventure
     event.renderer((source, sourceDisplayName, message, viewer) -> 
         MiniMessage.miniMessage().deserialize("<gray>[Member] </gray>")
             .append(sourceDisplayName)
@@ -74,18 +74,18 @@ public void onChat(AsyncChatEvent event) {
 ```
 
 ### `PrePlayerAttackEntityEvent`
-Dijalankan sebelum kalkulasi serangan vanilla terjadi. Sangat ideal untuk sistem combat kustom, cooldown attack senjata khusus, atau verifikasi proteksi PvP.
+Fires prior to vanilla attack calculations. Essential for custom combat mechanics, weapon cooldown verification, or anti-griefing checks.
 
 ### `ServerTickStartEvent` & `ServerTickEndEvent`
-Memonitor performa server secara presisi per-tick tanpa membebani scheduler.
+Provides cycle-accurate server performance metrics per-tick without adding scheduler overhead.
 
 ---
 
-## 3. Membuat Custom Event
+## 3. Creating Custom Events
 
-Anda dapat membuat event sendiri untuk mengekspos API plugin Anda kepada developer lain (seperti yang dilakukan oleh LuckPerms atau WorldGuard).
+You can create custom events to expose an extensible public API for other plugins (following the design of LuckPerms or WorldGuard):
 
-### Contoh Custom Event:
+### Custom Event Example:
 ```java
 package com.example.plugin.event;
 
@@ -103,7 +103,7 @@ public final class PlayerLevelUpEvent extends Event implements Cancellable {
     private boolean cancelled = false;
 
     public PlayerLevelUpEvent(Player player, int newLevel) {
-        // false jika berjalan di main/region thread (Sync), true jika Async
+        // false for synchronous execution on main/region thread, true for asynchronous
         super(false);
         this.player = player;
         this.newLevel = newLevel;
@@ -140,24 +140,23 @@ public final class PlayerLevelUpEvent extends Event implements Cancellable {
 }
 ```
 
-### Memanggil (Dispatch) Event:
+### Dispatching the Custom 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>"));
+    player.sendActionBar(MiniMessage.miniMessage().deserialize("<green>Congratulations, you leveled up!</green>"));
 }
 ```
 
 ---
 
-## 4. Unregistering Event & Pembersihan
+## 4. Listener Unregistration & Memory Hygiene
 
-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:
+To prevent memory leaks across plugin reload or disable cycles:
+- All listeners registered via `pluginManager.registerEvents(listener, this)` are unregistered automatically upon `onDisable()`.
+- If you register dynamic short-lived listeners (such as for a temporary minigame session), unregister them explicitly upon session completion:
   ```java
   HandlerList.unregisterAll(matchListener);
   ```