#1015: Add a tool component to ItemMeta

By: 2008Choco <hawkeboyz2@hotmail.com>
Also-by: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -14,6 +14,7 @@ import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemFlag;
 import org.bukkit.inventory.ItemRarity;
 import org.bukkit.inventory.meta.components.FoodComponent;
+import org.bukkit.inventory.meta.components.ToolComponent;
 import org.bukkit.inventory.meta.tags.CustomItemTagContainer;
 import org.bukkit.persistence.PersistentDataHolder;
 import org.jetbrains.annotations.ApiStatus;
@@ -406,6 +407,11 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
 
     /**
      * Gets the food set on this item, or creates an empty food instance.
+     * <p>
+     * The returned component is a snapshot of its current state and does not
+     * reflect a live view of what is on an item. After changing any value on
+     * this component, it must be set with {@link #setFood(FoodComponent)} to
+     * apply the changes.
      *
      * @return food
      */
@@ -419,6 +425,33 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
      */
     void setFood(@Nullable FoodComponent food);
 
+    /**
+     * Checks if the tool is set.
+     *
+     * @return if a tool is set
+     */
+    boolean hasTool();
+
+    /**
+     * Gets the tool set on this item, or creates an empty tool instance.
+     * <p>
+     * The returned component is a snapshot of its current state and does not
+     * reflect a live view of what is on an item. After changing any value on
+     * this component, it must be set with {@link #setTool(ToolComponent)} to
+     * apply the changes.
+     *
+     * @return tool
+     */
+    @NotNull
+    ToolComponent getTool();
+
+    /**
+     * Sets the item tool.
+     *
+     * @param tool new tool
+     */
+    void setTool(@Nullable ToolComponent tool);
+
     /**
      * Checks for the existence of any AttributeModifiers.
      *

paper-api/src/main/java/org/bukkit/inventory/meta/components/ToolComponent.java

@@ -0,0 +1,204 @@
+package org.bukkit.inventory.meta.components;
+
+import java.util.Collection;
+import java.util.List;
+import org.bukkit.Material;
+import org.bukkit.Tag;
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a component which can turn any item into a tool.
+ */
+@ApiStatus.Experimental
+public interface ToolComponent extends ConfigurationSerializable {
+
+    /**
+     * Get the default mining speed of this tool. This value is used by the tool
+     * if no rule explicitly overrides it. 1.0 is standard mining speed.
+     *
+     * @return the default mining speed
+     * @see ToolRule#getSpeed()
+     */
+    float getDefaultMiningSpeed();
+
+    /**
+     * Set the default mining speed of this tool. This value is used by the tool
+     * if no rule explicitly overrides it. 1.0 is standard mining speed.
+     *
+     * @param speed the speed to set
+     */
+    void setDefaultMiningSpeed(float speed);
+
+    /**
+     * Get the amount of durability to be removed from the tool each time a
+     * block is broken.
+     *
+     * @return the damage per block
+     */
+    int getDamagePerBlock();
+
+    /**
+     * Set the amount of durability to be removed from the tool each time a
+     * block is broken.
+     *
+     * @param damage the damage to set. Must be 0 or a positive integer
+     */
+    void setDamagePerBlock(int damage);
+
+    /**
+     * Get the list of {@link ToolRule ToolRules} that apply to this tool.
+     *
+     * @return all tool rules. The mutability of the returned list cannot be
+     * guaranteed, but its contents are mutable and can have their values
+     * changed
+     */
+    @NotNull
+    List<ToolRule> getRules();
+
+    /**
+     * Set the list of {@link ToolRule ToolRules} to apply to this tool. This
+     * will remove any existing tool rules.
+     *
+     * @param rules the rules to set
+     */
+    void setRules(@NotNull List<ToolRule> rules);
+
+    /**
+     * Add a new rule to this tool component, which provides further information
+     * about a specific block type.
+     *
+     * @param block the block type to which the rule applies
+     * @param speed the mining speed to use when mining the block, or null to
+     * use the default mining speed
+     * @param correctForDrops whether or not this tool, when mining the block,
+     * is considered the optimal tool for the block and will drop its items when
+     * broken, or null to use the default tool checking behavior defined by
+     * Minecraft
+     * @return the {@link ToolRule} instance that was added to this tool
+     */
+    @NotNull
+    ToolRule addRule(@NotNull Material block, @Nullable Float speed, @Nullable Boolean correctForDrops);
+
+    /**
+     * Add a new rule to this tool component, which provides further information
+     * about a collection of block types.
+     *
+     * @param blocks the block types to which the rule applies
+     * @param speed the mining speed to use when mining one of the blocks, or
+     * null to use the default mining speed
+     * @param correctForDrops whether or not this tool, when mining one of the
+     * blocks, is considered the optimal tool for the block and will drop its
+     * items when broken, or null to use the default tool checking behavior
+     * defined by Minecraft
+     * @return the {@link ToolRule} instance that was added to this tool
+     */
+    @NotNull
+    ToolRule addRule(@NotNull Collection<Material> blocks, @Nullable Float speed, @Nullable Boolean correctForDrops);
+
+    /**
+     * Add a new rule to this tool component, which provides further information
+     * about a collection of block types represented by a block {@link Tag}.
+     *
+     * @param tag the block tag containing block types to which the rule
+     * applies.
+     * @param speed the mining speed to use when mining one of the blocks, or
+     * null to use the default mining speed
+     * @param correctForDrops whether or not this tool, when mining one of the
+     * blocks, is considered the optimal tool for the block and will drop its
+     * items when broken, or null to use the default tool checking behavior
+     * defined by Minecraft
+     * @return the {@link ToolRule} instance that was added to this tool
+     * @throws IllegalArgumentException if the passed {@code tag} is not a block
+     * tag
+     */
+    @NotNull
+    ToolRule addRule(@NotNull Tag<Material> tag, @Nullable Float speed, @Nullable Boolean correctForDrops);
+
+    /**
+     * Remove the given {@link ToolRule} from this tool.
+     *
+     * @param rule the rule to remove
+     * @return true if the rule was removed, false if this component did not
+     * contain a matching rule
+     */
+    boolean removeRule(@NotNull ToolRule rule);
+
+    /**
+     * A rule governing use of this tool and overriding attributes per-block.
+     */
+    public interface ToolRule extends ConfigurationSerializable {
+
+        /**
+         * Get a collection of the block types to which this tool rule applies.
+         *
+         * @return the blocks
+         */
+        @NotNull
+        Collection<Material> getBlocks();
+
+        /**
+         * Set the block type to which this rule applies.
+         *
+         * @param block the block type
+         */
+        void setBlocks(@NotNull Material block);
+
+        /**
+         * Set the block types to which this rule applies.
+         *
+         * @param blocks the block types
+         */
+        void setBlocks(@NotNull Collection<Material> blocks);
+
+        /**
+         * Set the block types (represented as a block {@link Tag}) to which
+         * this rule applies.
+         *
+         * @param tag the block tag
+         * @throws IllegalArgumentException if the passed {@code tag} is not a
+         * block tag
+         */
+        void setBlocks(@NotNull Tag<Material> tag);
+
+        /**
+         * Get the mining speed of this rule. If non-null, this speed value is
+         * used in lieu of the default speed value of the tool. 1.0 is standard
+         * mining speed.
+         *
+         * @return the mining speed, or null if the default speed is used
+         */
+        @Nullable
+        Float getSpeed();
+
+        /**
+         * Set the mining speed of this rule. 1.0 is standard mining speed.
+         *
+         * @param speed the mining speed, or null to use the default speed
+         */
+        void setSpeed(@Nullable Float speed);
+
+        /**
+         * Get whether or not this rule is considered the optimal tool for the
+         * blocks listed by this rule and will drop items. If non-null, this
+         * value is used in lieu of the default tool checking behavior defined
+         * by Minecraft.
+         *
+         * @return true if correct for drops, false otherwise, or null to
+         * fallback to vanilla tool checking behavior
+         */
+        @Nullable
+        Boolean isCorrectForDrops();
+
+        /**
+         * Set whether or not this rule is considered the optimal tool for the
+         * blocks listed by this rule and will drop items.
+         *
+         * @param correct whether or not this rule is correct for drops, or null
+         * to fallback to vanilla tool checking behavior
+         */
+        void setCorrectForDrops(@Nullable Boolean correct);
+    }
+}