1.3

Implemented pickaxe skins api

Author: Jan Kluka

src/main/java/dev/drawethree/xprison/api/XPrisonAPI.java

@@ -11,6 +11,7 @@
 import dev.drawethree.xprison.api.miningstats.XPrisonMiningStatsAPI;
 import dev.drawethree.xprison.api.multipliers.XPrisonMultipliersAPI;
 import dev.drawethree.xprison.api.pickaxelevels.XPrisonPickaxeLevelsAPI;
+import dev.drawethree.xprison.api.pickaxeskins.XPrisonPickaxeSkinsAPI;
 import dev.drawethree.xprison.api.prestiges.XPrisonPrestigesAPI;
 import dev.drawethree.xprison.api.ranks.XPrisonRanksAPI;
 import org.jetbrains.annotations.NotNull;
@@ -124,6 +125,14 @@ public interface XPrisonAPI {
     @NotNull
     XPrisonMiningStatsAPI getMiningStatsApi();
 
+    /**
+     * Gets the pickaxe skins API
+     *
+     * @return the Pickaxe Skins API instance
+     */
+    @NotNull
+    XPrisonPickaxeSkinsAPI getPickaxeSkinsApi();
+
     /**
      * Gets the singleton instance of the XPrisonAPI.
      *

src/main/java/dev/drawethree/xprison/api/pickaxeskins/XPrisonPickaxeSkinsAPI.java

@@ -0,0 +1,55 @@
+package dev.drawethree.xprison.api.pickaxeskins;
+
+import dev.drawethree.xprison.api.pickaxeskins.model.PickaxeSkin;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemStack;
+
+import java.util.Optional;
+
+/**
+ * API for managing pickaxe skins in XPrison.
+ * <p>
+ * This interface allows external plugins to retrieve, apply, or manipulate
+ * cosmetic pickaxe skins which may provide gameplay multipliers (money, tokens, gems).
+ */
+public interface XPrisonPickaxeSkinsAPI {
+
+	/**
+	 * Retrieves the {@link PickaxeSkin} applied to the given pickaxe item.
+	 * <p>
+	 * This checks for skin metadata (e.g., via CustomModelData or NBT tags) stored in the item.
+	 *
+	 * @param item the ItemStack representing the pickaxe
+	 * @return an {@link Optional} containing the PickaxeSkin if one is applied; otherwise, empty
+	 */
+	Optional<PickaxeSkin> getPickaxeSkin(ItemStack item);
+
+	/**
+	 * Retrieves the {@link PickaxeSkin} currently applied to the item the player is holding.
+	 *
+	 * @param player the player whose held item will be checked
+	 * @return an {@link Optional} containing the PickaxeSkin if found; otherwise, empty
+	 */
+	Optional<PickaxeSkin> getPickaxeSkin(Player player);
+
+	/**
+	 * Retrieves a {@link PickaxeSkin} by its unique identifier.
+	 * <p>
+	 * Skin IDs correspond to the keys defined in your configuration (e.g., "legendary", "neon").
+	 *
+	 * @param id the ID of the skin to fetch
+	 * @return an {@link Optional} containing the PickaxeSkin if it exists; otherwise, empty
+	 */
+	Optional<PickaxeSkin> getPickaxeSkin(String id);
+
+	/**
+	 * Applies a {@link PickaxeSkin} to a given item for a specific player.
+	 * <p>
+	 * This typically modifies the item's CustomModelData or NBT to reflect the skin.
+	 *
+	 * @param player the player applying the skin
+	 * @param item the ItemStack to modify (must be a valid pickaxe)
+	 * @param skin the PickaxeSkin to apply to the item
+	 */
+	void setPickaxeSkin(Player player, ItemStack item, PickaxeSkin skin);
+}

src/main/java/dev/drawethree/xprison/api/pickaxeskins/model/PickaxeSkin.java

@@ -0,0 +1,65 @@
+package dev.drawethree.xprison.api.pickaxeskins.model;
+
+import java.util.Map;
+
+/**
+ * Represents a customizable pickaxe skin used within the XPrison system.
+ * Each skin has a unique ID, display name, custom model data (for resource packs),
+ * and a set of currency multipliers that affect gameplay (e.g., tokens, money, gems).
+ *
+ * This interface provides access to all properties of a skin,
+ * and allows multiplier lookups by currency name.
+ */
+public interface PickaxeSkin {
+
+    /**
+     * Gets the unique identifier for this skin.
+     *
+     * @return the internal ID of the skin (e.g., "legendary", "neon")
+     */
+    String getId();
+
+    /**
+     * Gets the display name of this skin, usually with color codes.
+     *
+     * @return the name shown to players (e.g., "§6Legendary Skin")
+     */
+    String getName();
+
+    /**
+     * Gets the description of this skin, usually with color codes.
+     *
+     * @return the description shown to players
+     */
+    String getDescription();
+
+    /**
+     * Gets the custom model data value used for applying the resource pack model.
+     *
+     * @return the CustomModelData integer for this skin
+     */
+    int getCustomModelData();
+
+    /**
+     * Gets the map of multipliers applied by this skin.
+     * Each entry maps a currency (e.g., "tokens") to a multiplier value.
+     *
+     * @return a map of currency multipliers
+     */
+    Map<String, Double> getMultipliers();
+
+    /**
+     * Gets the permission string required to use or unlock this skin.
+     *
+     * @return the permission node (e.g., "pickaxeskins.skin.legendary")
+     */
+    String getPermission();
+
+    /**
+     * Gets the multiplier for the specified currency.
+     *
+     * @param currencyName the currency to get the multiplier for (e.g., "tokens", "money")
+     * @return the multiplier for the currency, or 0.0 if not defined
+     */
+    double getMultiplier(String currencyName);
+}