From 6e2bfedbc92164a8dcdd0c30a5e2c8a08b3bf28d Mon Sep 17 00:00:00 2001
From: alexcrea <42614139+alexcrea@users.noreply.github.com>
Date: Mon, 15 Jul 2024 13:42:50 +0200
Subject: [PATCH] Add Bulk Operations wiki

---
 Register-Bulk-Operations.md | 84 +++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 Register-Bulk-Operations.md

diff --git a/Register-Bulk-Operations.md b/Register-Bulk-Operations.md
new file mode 100644
index 0000000..f54b2e6
--- /dev/null
+++ b/Register-Bulk-Operations.md
@@ -0,0 +1,84 @@
+# Bulk Operations
+By default, Custom Anvil find/clear enchantments by iterating over every enchantment. That is not the most efficient way of working and if it can be optimized via bulk operation. Especially if your enchantment plugin registers a lot of enchantments. \
+You should not implement a bulk operation that iterate over every of your registered enchantment.
+
+If you are using or extending `CABukkitEnchantment` for your Custom Anvil enchantment, then it is already optimized using Bukkit get Enchantments and you do not need to follow this wiki.
+
+You should implement bulk operation only if your implementation does not replicate what Custom Anvil do to unopposed enchantments. \
+(iterating over every of your enchantment to get/clear them).
+
+## Create Bulk Operator
+You need to create a new class implementing `BulkGetEnchantOperation` and/or `BulkCleanEnchantOperation` depending on your need.
+
+```java
+public class BukkitEnchantBulkOperation implements BulkGetEnchantOperation, BulkCleanEnchantOperation {
+
+    @Override
+    public void bulkGet(@NotNull Map<CAEnchantment, Integer> enchantmentList, @NotNull ItemStack item, @NotNull ItemMeta meta) {
+        /* 
+         * Add item enchantment to the provided map.
+         * Value of map should be the enchantment level of the key enchantment on the item.
+         * Item and item meta should not get changed.
+         */
+    }
+
+    @Override
+    public void bulkClear(@NotNull ItemStack item) {
+        /* 
+         * Clear using only the item
+         * Item can be changed changed. Item meta probably should not get created (preferably use next function if you need to use the item meta)
+         * You do not need to repeat clear of enchantment cleared from the next function.
+         */
+    }
+
+    @Override
+    public void bulkClear(@NotNull ItemStack item, @NotNull ItemMeta meta) {
+        /* 
+         * Clear using only the item meta
+         * Item should not get changed. only the item meta should get change.
+         * You do not need to repeat clear of enchantment cleared from the previous function.
+         */ 
+    }
+}
+```
+
+For a more concrete example, you can see the [bulk operator for Bukkit enchantments](https://github.com/alexcrea/CustomAnvil/blob/master/src/main/java/xyz/alexcrea/cuanvil/enchant/bulk/BukkitEnchantBulkOperation.java)
+
+## Adding you Bulk Operator
+
+We assume you we have `MyBulkOperations`. \
+Here is the preferable way to add your bulk operations.
+```java
+@EventHandler
+public void onEnchantmentRegistry(CAEnchantRegistryReadyEvent event){
+    // Register enchantments
+    // ...
+
+    // Add bulk operatotions
+    MyBulkOperations operator = new MyBulkOperations();
+
+    EnchantmentApi.addBulkGet(operator); // Add bulk operation if you implement BulkGetEnchantOperation
+    EnchantmentApi.addBulkClean(operator); // Add bulk operation if you implement BulkCleanEnchantOperation
+
+}
+```
+
+## Mark your enchantment as optimized
+If you add a bulk enchantment, then you need to mark your enchantment as optimized. \
+You only need to override the following function in your enchantment class:
+```java
+// If you added bulk get operator for this enchantment
+@Override 
+public boolean isGetOptimised() {
+    return true;
+}
+
+// If you added bulk clean operator for this enchantment
+@Override
+public boolean isCleanOptimised() {
+    return true;
+}
+```
+
+
+