Add PlayerRecipeDiscoverEvent and methods to (un/)discover recipes

By: Parker Hawke <hawkeboyz2@hotmail.com>

paper-api/src/main/java/org/bukkit/entity/HumanEntity.java

@@ -1,8 +1,10 @@
 package org.bukkit.entity;
 
+import java.util.Collection;
 import org.bukkit.GameMode;
 import org.bukkit.Location;
 import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
 import org.bukkit.inventory.MainHand;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Inventory;
@@ -256,6 +258,57 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
      */
     public int getExpToLevel();
 
+    /**
+     * Discover a recipe for this player such that it has not already been
+     * discovered. This method will add the key's associated recipe to the
+     * player's recipe book.
+     *
+     * @param recipe the key of the recipe to discover
+     *
+     * @return whether or not the recipe was newly discovered
+     */
+    public boolean discoverRecipe(NamespacedKey recipe);
+
+    /**
+     * Discover a collection of recipes for this player such that they have not
+     * already been discovered. This method will add the keys' associated
+     * recipes to the player's recipe book. If a recipe in the provided
+     * collection has already been discovered, it will be silently ignored.
+     *
+     * @param recipes the keys of the recipes to discover
+     *
+     * @return the amount of newly discovered recipes where 0 indicates that
+     * none were newly discovered and a number equal to {@code recipes.size()}
+     * indicates that all were new
+     */
+    public int discoverRecipes(Collection<NamespacedKey> recipes);
+
+    /**
+     * Undiscover a recipe for this player such that it has already been
+     * discovered. This method will remove the key's associated recipe from the
+     * player's recipe book.
+     *
+     * @param recipe the key of the recipe to undiscover
+     *
+     * @return whether or not the recipe was successfully undiscovered (i.e. it
+     * was previously discovered)
+     */
+    public boolean undiscoverRecipe(NamespacedKey recipe);
+
+    /**
+     * Undiscover a collection of recipes for this player such that they have
+     * already been discovered. This method will remove the keys' associated
+     * recipes from the player's recipe book. If a recipe in the provided
+     * collection has not yet been discovered, it will be silently ignored.
+     *
+     * @param recipes the keys of the recipes to undiscover
+     *
+     * @return the amount of undiscovered recipes where 0 indicates that none
+     * were undiscovered and a number equal to {@code recipes.size()} indicates
+     * that all were undiscovered
+     */
+    public int undiscoverRecipes(Collection<NamespacedKey> recipes);
+
     /**
      * Gets the entity currently perched on the left shoulder or null if no
      * entity.

paper-api/src/main/java/org/bukkit/event/player/PlayerRecipeDiscoverEvent.java

@@ -0,0 +1,50 @@
+package org.bukkit.event.player;
+
+import org.bukkit.NamespacedKey;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called when a player discovers a new recipe in the recipe book.
+ */
+public class PlayerRecipeDiscoverEvent extends PlayerEvent implements Cancellable {
+
+    private static final HandlerList handlers = new HandlerList();
+
+    private boolean cancel = false;
+    private final NamespacedKey recipe;
+
+    public PlayerRecipeDiscoverEvent(Player who, NamespacedKey recipe) {
+        super(who);
+        this.recipe = recipe;
+    }
+
+    /**
+     * Get the namespaced key of the discovered recipe.
+     *
+     * @return the discovered recipe
+     */
+    public NamespacedKey getRecipe() {
+        return recipe;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancel;
+    }
+
+    @Override
+    public void setCancelled(boolean cancel) {
+        this.cancel = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}