SPIGOT-2272: Add API for virtual Merchants

By: Lukas Hennig <lukas@wirsindwir.de>

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -29,6 +29,7 @@ import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.map.MapView;
 import org.bukkit.permissions.Permissible;
@@ -931,6 +932,17 @@ public final class Bukkit {
         return server.createInventory(owner, size, title);
     }
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @param title the title of the corresponding merchant inventory, displayed
+     * when the merchant inventory is viewed
+     * @return a new merchant
+     */
+    public static Merchant createMerchant(String title) {
+        return server.createMerchant(title);
+    }
+
     /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.

paper-api/src/main/java/org/bukkit/Server.java

@@ -29,6 +29,7 @@ import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.map.MapView;
 import org.bukkit.permissions.Permissible;
@@ -761,6 +762,15 @@ public interface Server extends PluginMessageRecipient {
      */
     Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException;
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @param title the title of the corresponding merchant inventory, displayed
+     * when the merchant inventory is viewed
+     * @return a new merchant
+     */
+    Merchant createMerchant(String title);
+
     /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.

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

@@ -3,6 +3,7 @@ package org.bukkit.entity;
 import org.bukkit.GameMode;
 import org.bukkit.Location;
 import org.bukkit.inventory.MainHand;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.InventoryView;
@@ -117,6 +118,19 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
      */
     public InventoryView openMerchant(Villager trader, boolean force);
 
+    /**
+     * Starts a trade between the player and the merchant.
+     *
+     * Note that only one player may trade with a merchant at once. You must use
+     * the force parameter for this.
+     *
+     * @param merchant The merchant to trade with. Cannot be null.
+     * @param force whether to force the trade even if another player is trading
+     * @return The newly opened inventory view, or null if it could not be
+     * opened.
+     */
+    public InventoryView openMerchant(Merchant merchant, boolean force);
+
     /**
      * Force-closes the currently open inventory view for this player, if any.
      */

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

@@ -1,14 +1,13 @@
 package org.bukkit.entity;
 
-import java.util.List;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
-import org.bukkit.inventory.MerchantRecipe;
+import org.bukkit.inventory.Merchant;
 
 /**
  * Represents a villager NPC
  */
-public interface Villager extends Ageable, NPC, InventoryHolder {
+public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
 
     /**
      * Gets the current profession of this villager.
@@ -24,48 +23,6 @@ public interface Villager extends Ageable, NPC, InventoryHolder {
      */
     public void setProfession(Profession profession);
 
-    /**
-     * Get a list of trades currently available from this villager.
-     *
-     * @return an immutable list of trades
-     */
-    List<MerchantRecipe> getRecipes();
-
-    /**
-     * Set the list of trades currently available from this villager.
-     * <br>
-     * This will not change the selected trades of players currently trading
-     * with this villager.
-     *
-     * @param recipes a list of recipes
-     */
-    void setRecipes(List<MerchantRecipe> recipes);
-
-    /**
-     * Get the recipe at a certain index of this villager's trade list.
-     *
-     * @param i the index
-     * @return the recipe
-     * @throws IndexOutOfBoundsException
-     */
-    MerchantRecipe getRecipe(int i) throws IndexOutOfBoundsException;
-
-    /**
-     * Set the recipe at a certain index of this villager's trade list.
-     *
-     * @param i the index
-     * @param recipe the recipe
-     * @throws IndexOutOfBoundsException
-     */
-    void setRecipe(int i, MerchantRecipe recipe) throws IndexOutOfBoundsException;
-
-    /**
-     * Get the number of trades this villager currently has available.
-     *
-     * @return the recipe count
-     */
-    int getRecipeCount();
-
     /**
      * Gets this villager's inventory.
      * <br>
@@ -77,21 +34,6 @@ public interface Villager extends Ageable, NPC, InventoryHolder {
     @Override
     Inventory getInventory();
 
-    /**
-     * Gets whether this villager is currently trading.
-     *
-     * @return whether the villager is trading
-     */
-    boolean isTrading();
-
-    /**
-     * Gets the player this villager is trading with, or null if it is not
-     * currently trading.
-     *
-     * @return the trader, or null
-     */
-    HumanEntity getTrader();
-
     /**
      * Gets this villager's riches, the number of emeralds this villager has
      * been given.

paper-api/src/main/java/org/bukkit/inventory/Merchant.java

@@ -0,0 +1,69 @@
+package org.bukkit.inventory;
+
+import java.util.List;
+
+import org.bukkit.entity.HumanEntity;
+
+/**
+ * Represents a merchant. A merchant is a special type of inventory which can
+ * facilitate custom trades between items.
+ */
+public interface Merchant {
+
+    /**
+     * Get a list of trades currently available from this merchant.
+     *
+     * @return an immutable list of trades
+     */
+    List<MerchantRecipe> getRecipes();
+
+    /**
+     * Set the list of trades currently available from this merchant.
+     * <br>
+     * This will not change the selected trades of players currently trading
+     * with this merchant.
+     *
+     * @param recipes a list of recipes
+     */
+    void setRecipes(List<MerchantRecipe> recipes);
+
+    /**
+     * Get the recipe at a certain index of this merchant's trade list.
+     *
+     * @param i the index
+     * @return the recipe
+     * @throws IndexOutOfBoundsException
+     */
+    MerchantRecipe getRecipe(int i) throws IndexOutOfBoundsException;
+
+    /**
+     * Set the recipe at a certain index of this merchant's trade list.
+     *
+     * @param i the index
+     * @param recipe the recipe
+     * @throws IndexOutOfBoundsException
+     */
+    void setRecipe(int i, MerchantRecipe recipe) throws IndexOutOfBoundsException;
+
+    /**
+     * Get the number of trades this merchant currently has available.
+     *
+     * @return the recipe count
+     */
+    int getRecipeCount();
+
+    /**
+     * Gets whether this merchant is currently trading.
+     *
+     * @return whether the merchant is trading
+     */
+    boolean isTrading();
+
+    /**
+     * Gets the player this merchant is trading with, or null if it is not
+     * currently trading.
+     *
+     * @return the trader, or null
+     */
+    HumanEntity getTrader();
+}

paper-api/src/main/java/org/bukkit/inventory/MerchantInventory.java

@@ -1,9 +1,10 @@
 package org.bukkit.inventory;
 
 /**
- * Represents a trading inventory between a player and a villager.
+ * Represents a trading inventory between a player and a merchant.
  * <br>
- * The holder of this Inventory is the owning Villager.
+ * The holder of this Inventory is the owning Villager, or null if the player is
+ * trading with a merchant created by a plugin.
  */
 public interface MerchantInventory extends Inventory {
 

paper-api/src/main/java/org/bukkit/inventory/MerchantRecipe.java

@@ -5,7 +5,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Represents a Villager's trade.
+ * Represents a merchant's trade.
  *
  * Trades can take one or two ingredients, and provide one result. The
  * ingredients' Itemstack amounts are respected in the trade.
@@ -43,7 +43,7 @@ public class MerchantRecipe implements Recipe {
     }
 
     public void addIngredient(ItemStack item) {
-        Preconditions.checkState(ingredients.size() < 2, "Merchant can only have 2 ingredients");
+        Preconditions.checkState(ingredients.size() < 2, "MerchantRecipe can only have 2 ingredients");
         ingredients.add(item.clone());
     }
 
@@ -88,7 +88,7 @@ public class MerchantRecipe implements Recipe {
      * Get the maximum number of uses this trade has.
      * <br>
      * The maximum uses of this trade may increase when a player trades with the
-     * owning villager.
+     * owning merchant.
      *
      * @return the maximum number of uses
      */