papermc-skill 1.0.1 → 1.2.0

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

@@ -1,32 +1,32 @@
-# Penyimpanan Database Asinkron: SQLite & HikariCP di Paper
+# Asynchronous Database Storage: SQLite & HikariCP in 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.
+Storing player profiles (economy balances, levels, custom inventories, quests) directly into YAML files (`config.yml` or `player.yml`) degrades performance rapidly and invites file corruption when scaling to thousands of unique users.
 
-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).
+The industry standard for production storage is relational databases (**SQLite** for standalone single servers, or **MySQL / PostgreSQL via HikariCP** for multi-server BungeeCord/Velocity networks).
 
 ---
 
-## 1. Aturan Emas Database di Minecraft
+## 1. The Golden Rule of Minecraft Database Access
 
-> **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.
+> **NEVER open database connections, execute `SELECT` queries, or run `INSERT/UPDATE` statements on the main or region tick threads.**
+> A single query taking 50ms immediately causes TPS drops, player rubberbanding, and tick watchdog warnings.
 
-Gunakan selalu **Asynchronous Execution (`CompletableFuture`)** yang me-return hasil ke thread region pemain saat selesai.
+Always execute database operations via **Asynchronous Threads (`CompletableFuture`)**, and dispatch results back to the player's entity scheduler when mutating game state.
 
 ---
 
-## 2. Menyiapkan HikariCP (Connection Pooling)
+## 2. Configuring HikariCP (High-Performance Connection Pooling)
 
-HikariCP adalah library connection pool tercepat di ekosistem Java (digunakan secara ekstensif oleh **LuckPerms**).
+HikariCP is the fastest connection pool in the Java ecosystem (utilized extensively by **LuckPerms**).
 
-### Dependensi Gradle:
+### Gradle Dependency:
 ```kotlin
 dependencies {
     implementation("com.zaxxer:HikariCP:5.1.0")
 }
 ```
 
-### Inisialisasi DataSource:
+### Initializing the DataSource:
 ```java
 package com.example.plugin.database;
 
@@ -46,12 +46,12 @@ public final class DatabaseManager {
         config.setUsername(user);
         config.setPassword(password);
 
-        // Pengaturan Pool HikariCP yang Direkomendasikan
+        // Recommended HikariCP Pool Settings
         config.setMaximumPoolSize(10);
         config.setMinimumIdle(2);
-        config.setConnectionTimeout(10000); // 10 detik
-        config.setIdleTimeout(600000);      // 10 menit
-        config.setMaxLifetime(1800000);     // 30 menit
+        config.setConnectionTimeout(10000); // 10 seconds
+        config.setIdleTimeout(600000);      // 10 minutes
+        config.setMaxLifetime(1800000);     // 30 minutes
         config.setPoolName("PluginHikariPool");
 
         this.dataSource = new HikariDataSource(config);
@@ -60,7 +60,7 @@ public final class DatabaseManager {
     public void initSQLite(String filePath) {
         HikariConfig config = new HikariConfig();
         config.setJdbcUrl("jdbc:sqlite:" + filePath);
-        config.setMaximumPoolSize(1); // SQLite hanya boleh 1 writer pool
+        config.setMaximumPoolSize(1); // SQLite only supports a single writer
         config.setPoolName("PluginSQLitePool");
 
         this.dataSource = new HikariDataSource(config);
@@ -80,9 +80,9 @@ public final class DatabaseManager {
 
 ---
 
-## 3. Repositori Asinkron dengan `CompletableFuture`
+## 3. Asynchronous DAO Pattern with `CompletableFuture`
 
-Buat Data Access Object (DAO) yang memisahkan eksekusi SQL dari logika game:
+Construct a Data Access Object (DAO) to cleanly decouple raw SQL execution from in-game mechanics:
 
 ```java
 package com.example.plugin.database;
@@ -120,7 +120,7 @@ public final class PlayerRepository {
         }
     }
 
-    // Membaca data pemain secara asinkron
+    // Read player balance asynchronously
     public CompletableFuture<Integer> getCoinsAsync(UUID uuid) {
         return CompletableFuture.supplyAsync(() -> {
             try (Connection conn = databaseManager.getConnection();
@@ -136,17 +136,17 @@ public final class PlayerRepository {
             } catch (SQLException e) {
                 e.printStackTrace();
             }
-            return 0; // Default jika data belum ada
+            return 0; // Default fallback
         }, dbExecutor);
     }
 
-    // Menyimpan data pemain secara asinkron (Upsert)
+    // Persist player balance asynchronously
     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)
+                     "ON CONFLICT(uuid) DO UPDATE SET coins = excluded.coins;" // SQLite / PostgreSQL
                  )) {
                 stmt.setString(1, uuid.toString());
                 stmt.setInt(2, coins);
@@ -165,21 +165,21 @@ public final class PlayerRepository {
 
 ---
 
-## 4. Menggunakan Hasil Database di Event Listener
+## 4. Applying Query Results in Event Listeners
 
-Saat data selesai di-fetch dari database, gunakan scheduler Folia/Paper pemain untuk menerapkan perubahannya ke objek Bukkit:
+When asynchronous database queries resolve, schedule execution back to the player's entity scheduler to mutate Bukkit state:
 
 ```java
 @EventHandler
 public void onPlayerJoin(PlayerJoinEvent event) {
     Player player = event.getPlayer();
 
-    // Fetch data koin di thread asinkron
+    // Fetch coins asynchronously off the tick thread
     playerRepository.getCoinsAsync(player.getUniqueId()).thenAccept(coins -> {
-        // Terapkan hasil ke entity pemain di thread region pemain
+        // Dispatch result safely onto the player's entity region thread
         player.getScheduler().run(plugin, task -> {
             player.sendActionBar(MiniMessage.miniMessage().deserialize(
-                "<gold>Saldo Koin: <yellow>" + coins + "</yellow></gold>"
+                "<gold>Balance: <yellow>" + coins + " Coins</yellow></gold>"
             ));
         }, null);
     });

package/docs/11-security-and-exploit-prevention.md

@@ -0,0 +1,233 @@
+# Masterclass Guide: Security & Exploit Prevention in Paper & Folia Plugins
+
+Public Minecraft servers face hostile environments: modified clients (*hacked clients*), automated packet bots, and malicious players probing for item duplication glitches (*dupe exploits*) or server-crashing packet freezes. This masterclass guide provides authoritative architectural patterns to ensure your Paper and Folia plugins remain completely exploit-proof.
+
+---
+
+## 1. Item Duplication Prevention (Dupe Glitch Elimination)
+
+Item duplication exploits almost universally originate from *race conditions* between inventory interface events, fast clicking, or off-thread asynchronous mutations.
+
+### Hazard 1: Off-Thread / Asynchronous Inventory Mutation
+```java
+// ❌ CRITICAL HAZARD: Mutating inventory off-thread!
+CompletableFuture.runAsync(() -> {
+    player.getInventory().removeItem(item); // Race condition! Can duplicate if clicked concurrently
+});
+```
+**Absolute Rule**: Minecraft's inventory state is **not thread-safe**. Whenever querying, removing, or adding items to a player, execution **must** occur on the player's entity region thread:
+```java
+// ✔️ SAFE: Execute on the Entity Scheduler
+player.getScheduler().run(plugin, task -> {
+    if (player.getInventory().containsAtLeast(item, requiredAmount)) {
+        player.getInventory().removeItem(item);
+        // Proceed with transaction
+    }
+}, null);
+```
+
+### Hazard 2: Inventory Drag & Fast-Click Race Conditions
+Cheating clients can emit rapid click or drag packets to pick up an item before cancellation handlers finish evaluating.
+```java
+@EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
+public void onInventoryClick(InventoryClickEvent event) {
+    if (!(event.getInventory().getHolder() instanceof CustomMenuHolder)) {
+        return;
+    }
+
+    // 1. Cancel the event immediately
+    event.setCancelled(true);
+
+    // 2. Prevent fast-click exploits via per-player debounce
+    Player player = (Player) event.getWhoClicked();
+    if (!DebounceManager.canClick(player.getUniqueId(), 200)) {
+        return;
+    }
+
+    // 3. Process only top menu slot actions
+    if (event.getClickedInventory() == event.getInventory()) {
+        processMenuButton(player, event.getSlot());
+    }
+}
+
+@EventHandler
+public void onInventoryDrag(InventoryDragEvent event) {
+    if (event.getInventory().getHolder() instanceof CustomMenuHolder) {
+        event.setCancelled(true); // Always cancel drag events in custom menus
+    }
+}
+```
+
+---
+
+## 2. Monetary Safety & Numeric Bounds Validation
+
+Floating-point precision errors and lack of numeric validation are among the most common causes of server economic collapse.
+
+### Exploitation Vectors: `NaN`, `Infinity`, and Negative Numbers
+Malicious players enter unexpected inputs in payment or shop commands, such as:
+- `/pay Alice -1000000` (deducts money from the receiver and credits the sender)
+- `/pay Alice NaN` (corrupts player balance to `NaN` permanently, breaking database constraints)
+- `/pay Alice 99999999999999999999` (overflows 64-bit integers, wrapping amounts into negatives)
+
+### 🟢 Solution: Strict Numeric Bounds Validator
+```java
+public final class EconomyValidator {
+
+    private static final double MIN_TRANSACTION = 0.01;
+    private static final double MAX_TRANSACTION = 1_000_000_000.0;
+
+    public static double validateAmount(double amount) throws IllegalArgumentException {
+        if (!Double.isFinite(amount)) {
+            throw new IllegalArgumentException("Invalid monetary amount (NaN or Infinity)!");
+        }
+        if (amount < MIN_TRANSACTION) {
+            throw new IllegalArgumentException("Minimum transaction amount is $" + MIN_TRANSACTION);
+        }
+        if (amount > MAX_TRANSACTION) {
+            throw new IllegalArgumentException("Transaction amount exceeds allowable limit!");
+        }
+        // Round to 2 decimal places (cents)
+        return Math.round(amount * 100.0) / 100.0;
+    }
+}
+```
+
+---
+
+## 3. PersistentDataContainer (PDC) Anti-Tamper & Cryptographic Hashing
+
+Never rely on an item's `DisplayName` or `Lore` to determine whether an item possesses custom abilities or rare server tiers.
+
+### 🔴 The Vulnerability
+Players can rename normal items using anvils or packet injection to mimic custom gear titles and lore text.
+
+### 🟢 Solution: PDC Verification with Cryptographic Salt
+Store immutable identifiers and cryptographic signatures inside the item's PDC:
+```java
+public class SecureItemManager {
+    private static NamespacedKey KEY_ID;
+    private static NamespacedKey KEY_HASH;
+    private static final String SERVER_SALT = "MySecretSaltKey_2026";
+
+    public static void init(Plugin plugin) {
+        KEY_ID = new NamespacedKey(plugin, "custom_id");
+        KEY_HASH = new NamespacedKey(plugin, "integrity_hash");
+    }
+
+    public static void signItem(ItemStack item, String customId) {
+        item.editMeta(meta -> {
+            String hash = generateSignature(customId, SERVER_SALT);
+            PersistentDataContainer pdc = meta.getPersistentDataContainer();
+            pdc.set(KEY_ID, PersistentDataType.STRING, customId);
+            pdc.set(KEY_HASH, PersistentDataType.STRING, hash);
+        });
+    }
+
+    public static boolean verifyItem(ItemStack item, String expectedId) {
+        if (item == null || !item.hasItemMeta()) return false;
+        PersistentDataContainer pdc = item.getItemMeta().getPersistentDataContainer();
+        String id = pdc.get(KEY_ID, PersistentDataType.STRING);
+        String hash = pdc.get(KEY_HASH, PersistentDataType.STRING);
+
+        if (id == null || hash == null || !id.equals(expectedId)) {
+            return false;
+        }
+        return hash.equals(generateSignature(id, SERVER_SALT));
+    }
+
+    private static String generateSignature(String data, String salt) {
+        return Integer.toHexString((data + salt).hashCode());
+    }
+}
+```
+
+---
+
+## 4. Mitigating Denial of Service (DoS) from Synchronous Chunk Freezes
+
+If a plugin allows teleportation to arbitrary coordinates (e.g. random teleport or `/tppos`), malicious players can request far-flung coordinates (like 30,000,000) to freeze the server main thread while loading dozens of chunks from disk.
+
+### 🟢 Solution: Asynchronous Chunk Teleportation
+```java
+public static CompletableFuture<Boolean> safeTeleportAsync(Player player, Location target) {
+    World world = target.getWorld();
+    int chunkX = target.getBlockX() >> 4;
+    int chunkZ = target.getBlockZ() >> 4;
+
+    // 1. Load target chunk asynchronously without blocking game ticks
+    return world.getChunkAtAsync(chunkX, chunkZ, true).thenCompose(chunk -> {
+        // 2. Once chunk is loaded, execute teleport on player entity scheduler
+        CompletableFuture<Boolean> tpResult = new CompletableFuture<>();
+        player.getScheduler().run(plugin, task -> {
+            boolean success = player.teleport(target);
+            tpResult.complete(success);
+        }, null);
+        return tpResult;
+    });
+}
+```
+
+---
+
+## 5. Preventing SQL Injection & Connection Pool Starvation
+
+### 🔴 The SQL Injection Vulnerability
+```java
+// CRITICAL HAZARD: SQL Injection if input contains quotes
+String sql = "SELECT * FROM users WHERE name = '" + playerName + "'";
+statement.executeQuery(sql);
+```
+
+### 🟢 Solution: PreparedStatements & HikariCP Pool
+```java
+String sql = "SELECT * FROM users WHERE uuid = ?";
+try (Connection conn = dataSource.getConnection();
+     PreparedStatement stmt = conn.prepareStatement(sql)) {
+    stmt.setString(1, playerUuid.toString());
+    try (ResultSet rs = stmt.executeQuery()) {
+        if (rs.next()) {
+            // Process record safely
+        }
+    }
+} catch (SQLException e) {
+    logger.severe("Database error: " + e.getMessage());
+}
+```
+
+---
+
+## 6. Eliminating Memory Leaks from Lingering Bukkit References
+
+Holding references to `Player`, `World`, or `Chunk` instances in static collections prevents the JVM Garbage Collector from freeing gigabytes of world and network connection data:
+
+### 🔴 Memory Leak Pattern
+```java
+public static Map<Player, Long> lastAction = new HashMap<>(); // LEAK: Player never garbage collected!
+```
+
+### 🟢 Clean Architecture
+```java
+// 1. Store UUID primitives only
+public static Map<UUID, Long> lastAction = new ConcurrentHashMap<>();
+
+// 2. Invalidate on PlayerQuitEvent
+@EventHandler
+public void onQuit(PlayerQuitEvent event) {
+    lastAction.remove(event.getPlayer().getUniqueId());
+}
+```
+
+---
+
+## 7. The Exploit-Proof Verification Checklist
+
+- [x] **Zero asynchronous player inventory modifications.**
+- [x] **Inventory click debounce (150-200ms) enforced.**
+- [x] **Monetary inputs validated against `!Double.isFinite()` and bounds.**
+- [x] **Custom items identified via PDC rather than display lore.**
+- [x] **Asynchronous chunk loading used for all dynamic coordinates.**
+- [x] **PreparedStatements used for all database queries.**
+- [x] **UUIDs stored rather than `Player` instances in static caches.**
+- [x] **Player caches invalidated on `PlayerQuitEvent`.**
+- [x] **`folia-supported: true` declared with proper regional scheduling.**

package/docs/12-data-components-and-display-entities.md

@@ -0,0 +1,264 @@
+# 12. Modern Data Components & Display Entities (MC 1.20.5 — 26.x)
+
+## 📌 Paradigm Shift: From Legacy NBT & ItemMeta to Data Components
+
+Beginning with **Minecraft 1.20.5** and continuing through **Minecraft 1.21+ and 26.x**, Mojang completely overhauled the item stack architecture.
+- **Legacy NBT tags on ItemStacks are gone**.
+- In their place is the **Data Component System**: a strictly-typed, immutable, performant, and schema-validated component pipeline.
+- Paper exposes this via `io.papermc.paper.datacomponent.DataComponentTypes` and modern item manipulation methods directly on `ItemStack`.
+
+> [!IMPORTANT]
+> Never use legacy `net.minecraft.nbt` or reflection to modify item properties in modern Paper plugins. Use `ItemStack#setData(DataComponentType, Object)` or `ItemStack#getData(DataComponentType)`.
+
+---
+
+## 🛠️ 1. Modern Data Components in Action
+
+### A. Modifying Data Components Directly on ItemStack
+Paper allows direct mutation of components without cloning `ItemMeta`:
+
+```java
+package com.example.paperplugin.item;
+
+import io.papermc.paper.datacomponent.DataComponentTypes;
+import io.papermc.paper.datacomponent.item.CustomModelData;
+import io.papermc.paper.datacomponent.item.FoodProperties;
+import io.papermc.paper.datacomponent.item.ItemLore;
+import io.papermc.paper.datacomponent.item.Tool;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import net.kyori.adventure.text.format.TextDecoration;
+import org.bukkit.Material;
+import org.bukkit.inventory.ItemStack;
+
+import java.util.List;
+
+public final class ModernItemFactory {
+
+    public static ItemStack createMythicBlade() {
+        ItemStack blade = ItemStack.of(Material.NETHERITE_SWORD);
+
+        // 1. Direct Item Name (styled with MiniMessage/Adventure)
+        blade.setData(DataComponentTypes.ITEM_NAME, Component.text("Voidreaver Blade", NamedTextColor.LIGHT_PURPLE, TextDecoration.BOLD));
+
+        // 2. Direct Item Lore
+        blade.setData(DataComponentTypes.LORE, ItemLore.lore(List.of(
+            Component.text("Forged in the heart of the End dimension.", NamedTextColor.GRAY),
+            Component.empty(),
+            Component.text("⚡ Right-click to discharge void kinetic energy.", NamedTextColor.DARK_PURPLE)
+        )));
+
+        // 3. Custom Model Data (Modern float/flag/string/int support)
+        blade.setData(DataComponentTypes.CUSTOM_MODEL_DATA, CustomModelData.customModelData()
+            .addFloat(1.5f)
+            .addFlag(true)
+            .addString("mythic_blade_tier_3")
+            .build()
+        );
+
+        // 4. Custom Max Stack Size
+        blade.setData(DataComponentTypes.MAX_STACK_SIZE, 1);
+
+        // 5. Enchantment Glint Override (Glow without dummy enchantments!)
+        blade.setData(DataComponentTypes.ENCHANTMENT_GLINT_OVERRIDE, true);
+
+        // 6. Unbreakable Flag
+        blade.setData(DataComponentTypes.UNBREAKABLE, true);
+
+        return blade;
+    }
+
+    public static ItemStack createEnchantedGoldenBerry() {
+        ItemStack berry = ItemStack.of(Material.SWEET_BERRIES);
+
+        // Set custom edible Food Properties on ANY item!
+        bladeLikeFood(berry);
+
+        return berry;
+    }
+
+    private static void bladeLikeFood(ItemStack item) {
+        item.setData(DataComponentTypes.FOOD, FoodProperties.food()
+            .nutrition(6)
+            .saturation(10.0f)
+            .canAlwaysEat() // Can eat even when hunger bar is full
+            .build()
+        );
+        item.setData(DataComponentTypes.ITEM_NAME, Component.text("Aetheria Nectar Berry", NamedTextColor.GOLD));
+    }
+}
+```
+
+---
+
+## 🎭 2. Display Entities: Zero-Lag Visual FX & Holograms
+
+In legacy plugins, floating text and custom visuals required invisible `ArmorStand` entities. 
+**Armor stands are notoriously laggy**: they tick gravity, collisions, equipment slots, and poses every server tick.
+
+**Display Entities** (`TextDisplay`, `ItemDisplay`, `BlockDisplay`) introduced in modern Minecraft are:
+1. **Zero-Tick Lag**: Display entities do not have AI or physics ticking loops.
+2. **Smooth Interpolation**: The Minecraft client natively interpolates translation, rotation, and scale at full client framerate (60-240 FPS).
+3. **Billboarding**: Automatic camera tracking (`CENTER`, `VERTICAL`, `HORIZONTAL`).
+
+### Smooth Matrix Transformations (`org.joml.Matrix4f`)
+Paper integrates the high-performance **JOML** (Java OpenGL Math Library) for 3D transformations.
+
+```java
+package com.example.paperplugin.display;
+
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import net.kyori.adventure.text.format.TextDecoration;
+import org.bukkit.Color;
+import org.bukkit.Location;
+import org.bukkit.Material;
+import org.bukkit.entity.Display;
+import org.bukkit.entity.ItemDisplay;
+import org.bukkit.entity.TextDisplay;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.util.Transformation;
+import org.joml.AxisAngle4f;
+import org.joml.Vector3f;
+
+public final class HologramManager {
+
+    /**
+     * Spawns a floating holographic sign with smooth client-side interpolation.
+     */
+    public static TextDisplay spawnFloatingTitle(Location loc, Component text) {
+        return loc.getWorld().spawn(loc, TextDisplay.class, display -> {
+            display.text(text);
+            display.setBillboard(Display.Billboard.CENTER); // Always faces player
+            display.setDefaultBackground(false);
+            display.setBackgroundColor(Color.fromARGB(140, 15, 15, 25));
+            display.setShadowed(true);
+            display.setSeeThrough(false);
+
+            // Display view distance
+            display.setViewRange(0.8f);
+
+            // Initial scale & position transformation
+            Transformation transform = new Transformation(
+                new Vector3f(0f, 0f, 0f),                      // Translation
+                new AxisAngle4f(0f, 0f, 1f, 0f),              // Left rotation
+                new Vector3f(1.2f, 1.2f, 1.2f),               // Scale (120%)
+                new AxisAngle4f(0f, 0f, 1f, 0f)               // Right rotation
+            );
+            display.setTransformation(transform);
+        });
+    }
+
+    /**
+     * Spawns a spinning, floating 3D item icon above a pedestal.
+     */
+    public static ItemDisplay spawnRotatingPedestalItem(Location loc, ItemStack item) {
+        return loc.getWorld().spawn(loc, ItemDisplay.class, display -> {
+            display.setItemStack(item);
+            display.setItemDisplayTransform(ItemDisplay.ItemDisplayTransform.GROUND);
+            display.setBillboard(Display.Billboard.FIXED);
+
+            // Set up client-side 20-tick smooth interpolation
+            display.setInterpolationDuration(20);
+            display.setInterpolationDelay(0);
+
+            // Initial transformation
+            Transformation initial = new Transformation(
+                new Vector3f(0f, 0.5f, 0f),
+                new AxisAngle4f(0f, 0f, 1f, 0f),
+                new Vector3f(1.5f, 1.5f, 1.5f),
+                new AxisAngle4f(0f, 0f, 1f, 0f)
+            );
+            display.setTransformation(initial);
+        });
+    }
+
+    /**
+     * Smoothly rotates the display entity over time using client interpolation.
+     */
+    public static void rotateDisplaySmoothly(Display display, float angleRadians, int durationTicks) {
+        display.setInterpolationDuration(durationTicks);
+        display.setInterpolationDelay(0);
+
+        Transformation current = display.getTransformation();
+        Transformation next = new Transformation(
+            current.getTranslation(),
+            new AxisAngle4f(angleRadians, 0f, 1f, 0f), // Rotate around Y axis
+            current.getScale(),
+            current.getRightRotation()
+        );
+
+        display.setTransformation(next);
+    }
+}
+```
+
+---
+
+## ⚡ 3. 1.21 Tricky Trials & Mace Combat Kinematics
+
+Minecraft 1.21 introduced the **Mace**, **Wind Charges**, and dynamic physics combat mechanics.
+
+### Mace Kinetic Smash Mechanics
+The Mace scales damage dynamically based on fall distance, resetting the attacker's fall distance upon a successful hit:
+
+```java
+package com.example.paperplugin.combat;
+
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.Location;
+import org.bukkit.Material;
+import org.bukkit.Particle;
+import org.bukkit.Sound;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.entity.EntityDamageByEntityEvent;
+import org.bukkit.util.Vector;
+
+public final class ModernCombatListener implements Listener {
+
+    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)
+    public void onMaceSmash(EntityDamageByEntityEvent event) {
+        if (!(event.getDamager() instanceof Player attacker)) return;
+        if (!(event.getEntity() instanceof LivingEntity victim)) return;
+
+        // Verify weapon
+        if (attacker.getInventory().getItemInMainHand().getType() != Material.MACE) return;
+
+        float fallDistance = attacker.getFallDistance();
+        if (fallDistance > 1.5f) {
+            // Smash attack succeeded!
+            double bonusDamage = Math.min(fallDistance * 3.5, 40.0); // Safe numeric cap
+            event.setDamage(event.getDamage() + bonusDamage);
+
+            Location hitLoc = victim.getLocation();
+
+            // Spawn modern Tricky Trials visual & acoustic feedback
+            hitLoc.getWorld().spawnParticle(Particle.TRIAL_SPAWNER_DETECTION, hitLoc.add(0, 0.5, 0), 25, 0.4, 0.2, 0.4, 0.05);
+            hitLoc.getWorld().playSound(hitLoc, Sound.ITEM_MACE_SMASH_GROUND, 1.2f, 1.0f);
+
+            // Produce kinetic radial shockwave knockback on nearby hostile entities
+            hitLoc.getWorld().getNearbyLivingEntities(hitLoc, 4.0, e -> !e.equals(attacker) && !e.equals(victim))
+                .forEach(nearby -> {
+                    Vector impulse = nearby.getLocation().toVector().subtract(hitLoc.toVector()).normalize().multiply(1.2).setY(0.4);
+                    nearby.setVelocity(impulse);
+                });
+
+            attacker.sendActionBar(Component.text("⚡ KINETIC SMASH: +" + String.format("%.1f", bonusDamage) + " DMG", NamedTextColor.GOLD));
+        }
+    }
+}
+```
+
+---
+
+## 🛡️ Best Practices & Gotchas
+
+1. **Never Cast Data Components**: Always check `itemStack.hasData(DataComponentTypes.XXX)` before reading `itemStack.getData(DataComponentTypes.XXX)`.
+2. **Clean Display Entity Lifecycles**: When removing holograms, always invoke `display.remove()` and clean up stored entity UUIDs. Never store `TextDisplay` references in static collections.
+3. **JOML Thread Safety**: `Matrix4f`, `Vector3f`, and `Transformation` are value objects. Create them locally on demand rather than sharing mutable instances across async threads.
+4. **Folia Compatibility**: Always execute `world.spawn(loc, Display.class, ...)` on the Folia region scheduler corresponding to `loc`.