API Usage (For Developers) - mehboss/CustomRecipes GitHub Wiki

RecipeUtil API Usage Guide

This guide will help you understand how to use the RecipeUtil class for creating and managing custom recipes in your plugin. The RecipeUtil class allows for easy addition, removal, and retrieval of recipes, along with handling their ingredients and crafting results.

1. Overview of the RecipeUtil Class

The RecipeUtil class contains methods to manage recipes, including adding, removing, and retrieving them. Each recipe can have a name, a set of ingredients, a result item, and additional metadata like tags.

Key Components:

  • Recipe Management: Add, remove, and retrieve recipes.
  • Ingredient Handling: Define and manage the ingredients needed for crafting.
  • Recipe Types: Support for SHAPELESS, SHAPED, FURNACE, BLASTFURNACE, SMOKER, CAMPFIRE, ANVIL, and STONECUTTER recipes.
  • NBT Support: Set custom tags on items using NBT (Named Binary Tag).

2. Adding a Recipe

Step 1: Create an Instance of RecipeUtil

Before you can add a recipe, you need to get an instance of the RecipeUtil class.

import me.mehboss.recipe.YourPlugin;
import me.mehboss.utils.RecipeUtil;
import me.mehboss.utils.RecipeUtil.Recipe;
import org.bukkit.Bukkit;
import org.bukkit.Material;

public class OtherPlugin {

    public void addCustomRecipe() {
        // Access CustomRecipes instance
        Plugin plugin = Bukkit.getPluginManager().getPlugin("CustomRecipes");
        
        if (plugin != null) {
            // Get the RecipeUtil instance from CR
            RecipeUtil recipeUtil = plugin.getRecipeUtil();

            // Create a new recipe and add it
            Recipe newRecipe = new Recipe("my_custom_recipe");
            newRecipe.setResult(new ItemStack(Material.DIAMOND));
            recipeUtil.addRecipe(newRecipe);

            plugin.getLogger().info("Custom recipe added by OtherPlugin!");
        } else {
            Bukkit.getLogger().warning("CustomRecipes plugin not found!");
        }
    }
}

Step 2: Define a Recipe

To define a recipe, create an instance of the Recipe class and set its properties, including ingredients, the result item, recipe type, furnace experience, and cook time.

Recipe recipe = new Recipe("custom_crafting");
recipe.setRow(1, "XIX");
recipe.setRow(2, "IGI");
recipe.setRow(3, "XIX");
recipe.setType(Recipe.RecipeType.SHAPED); // Set the recipe type

// Define the result item
ItemStack resultItem = new ItemStack(Material.DIAMOND);
recipe.setResult(resultItem);

// Define ingredients
Ingredient ironIngredient = new Ingredient(Material.IRON_INGOT);
ironIngredient.setAbbreviation("I");

Ingredient goldIngredient = new Ingredient(Material.GOLD_INGOT);
goldIngredient.setAbbreviation("G");
goldIngredient.setDisplayName("Pure Gold"); // Adds display name requirement

// Add the ingredients to the recipe
recipe.addIngredient(goldIngredient);
recipe.addIngredient(ironIngredient);

// Set the cook time and furnace experience for furnace recipes
recipe.setCookTime(200); // Set the cook time (in ticks)
recipe.setExperience(1.0f); // Set the furnace experience

// Set a Key (NamespacedKey - Required)
recipe.setKey("my_custom_tag");
// Tags the recipe with special NBT data
recipe.setTagged(true);

Step 3: Add the Recipe to RecipeUtil

After defining the recipe, add it to the RecipeUtil instance:

recipeUtil.addRecipe(recipe);

3. Error Handling for Invalid Recipes

The createRecipe method in the RecipeUtil class throws special exceptions if there are any issues with the recipe being created:

  • Null or Missing NameSpacedKey: Throws InvalidRecipeException if the recipe is null or does not have a NameSpacedKey set.
  • Incorrect Recipe Type: Throws InvalidRecipeException if the recipe is SHAPED or SHAPELESS and does not have 9 ingredients.
  • Invalid Recipe Type: Throws InvalidRecipeException if the recipe types have more than 2 ingredients.
  • Invalid Result Item: Throws InvalidRecipeException if the recipe result is null or set to AIR.
  • Null Rows in Shaped Recipes: Throws InvalidRecipeException if any row of a shaped recipe is null.

4. Retrieving a Recipe

You can retrieve a recipe by its name using the getRecipe method:

Recipe retrievedRecipe = recipeUtil.getRecipe("custom_crafting");
if (retrievedRecipe != null) {
    // Do something with the recipe
}

5. Removing a Recipe

To remove a recipe, simply call the removeRecipe method with the recipe name:

recipeUtil.removeRecipe("custom_crafting");

6. Accessing All Recipes

You can get a list of all recipes stored in the RecipeUtil instance:

HashMap<String, Recipe> allRecipes = recipeUtil.getRecipeList();
for (String recipeName : allRecipes.keySet()) {
    System.out.println("Recipe Name: " + recipeName);
}

7. Handling Recipe Results

To get all results from the recipes, use the getRecipeResults method:

Collection<ItemStack> results = recipeUtil.getRecipeResults();
for (ItemStack result : results) {
    System.out.println("Recipe Result: " + result.getType());
}

8. Adding Recipes

Once you're done creating the recipes, you can add them to the server.

recipeUtil.reloadRecipes();

9. Ingredient Class

Creating Ingredients

You can create ingredients using the Ingredient class. Each ingredient can have properties like material, abbreviation, display name, and amount:

Ingredient ingredient = new Ingredient("X", Material.IRON_INGOT);
ingredient.setDisplayName("Iron Ingot"); // Displayname requirement for crafting
ingredient.setAmount(1); // Amount requirement for crafting
ingredient.setIdentifier("EnchantedDiamond"); // Identifier requirement for crafting. Matches to an existing Recipe and its set tag

Accessing Ingredient Properties

You can access various properties of the ingredient:

Material material = ingredient.getMaterial(); // Get the material
String abbreviation = ingredient.getAbbreviation(); // Get the abbreviation
int amount = ingredient.getAmount(); // Get the amount
String displayName = ingredient.getDisplayName(); // Get the display name

10. Example Usage

Here’s a complete example that shows how to add a recipe and print all recipes in the console:

public void setupRecipes() {
    RecipeUtil recipeUtil = new RecipeUtil();

    // Create a new recipe
    Recipe recipe = new Recipe("custom_crafting");
    recipe.setRow(1, "XXX");
    recipe.setRow(2, "XYX");
    recipe.setRow(3, "XXX");
    recipe.setType(Recipe.RecipeType.SHAPED);
    recipe.setResult(new ItemStack(Material.DIAMOND));
    recipe.setTag("custom_crafting");

    // Add ingredients
    Ingredient customIron = new Ingredient("X", Material.IRON_INGOT);
    customIron.setSlot(1);
    customIron.setSlot(2);
    customIron.setSlot(3);
    customIron.setSlot(4);
    customIron.setSlot(6);
    customIron.setSlot(7);
    customIron.setSlot(8);
    customIron.setSlot(9);
    recipe.addIngredient(customIron));

    Ingredient customGold = new Ingredient("Y", Material.GOLD_INGOT);
    customGold.setSlot(5);
    recipe.addIngredient(customGold);
    
    // Set cook time and furnace experience if it was a furnace recipe
    recipe.setCookTime(200);
    recipe.setExperience(1.0f);
    
    // Add the recipe to the RecipeUtil
    recipeUtil.addRecipe(recipe);
    // Adds the recipe to the server
    recipeUtil.reloadRecipes();

    // Print all recipes
    for (String name : recipeUtil.getRecipeNames()) {
        System.out.println("Recipe: " + name);
    }
}

11. Getters and Setters

Here’s a list of all the getters and setters you can use in the RecipeUtil and Ingredient classes:

1. RecipeUtil Getters and Setters

ArrayList<ItemStack> getAllResults()
HashMap<String, Recipe> getAllRecipes()
Recipe getRecipe(String recipeName)
Set<String> getRecipeNames()
Recipe getRecipeFromResult(ItemStack item)
ItemStack getResultFromKey(String key)
Recipe getRecipeFromKey(String key)

void createRecipe(Recipe recipe)
void removeRecipe(String recipeName)
void addRecipe(Recipe recipe)
void reloadRecipes()

2. Recipe Getters and Setters

String getName()
String getRow(int i)
String getPerm()
RecipeType getType()
String getTag()
ItemStack getResult()
List<Ingredient> getIngredients()
Integer getIngredientSize()
List<String> getDisabledWorlds()
Long getCooldown()
Ingredient getSlot()
String getBookCategory()

Float getExperience()
Integer getCookTime()
Integer getRepairCost()

boolean isDiscoverable()
boolean isExactChoice()
boolean hasCooldown()
boolean isConsume()
boolean isPlaceable()
boolean hasRepairCost()

void setBookCategory(String category)
void setDiscoverable(Boolean discoverable)
void setExactChoice(Boolean exactChoice)
void addDisabledWorld(String world)
void setPerm(String permission)
void setRow(int i, String row)
void setType(RecipeType type)
void setTag(String tag)
void setResult(ItemStack result)
void addIngredient(Ingredient ingredient)
void setIgnoreData(boolean ignoreData)
void setIgnoreModelData(boolean ignoreModelData)
void setPlaceable(Boolean placeable)
void setCooldown(long i)
void setConsume(boolean consume)

void setCookTime(int cooktime)
void setExperience(float experience)
void setRepairCost(int cost)

3. Ingredient Getters and Setters

Material getMaterial()
String getAbbreviation()
String getDisplayName()
String getIdentifier()
int getSlot()
int getAmount()
boolean isEmpty()
boolean hasDisplayName()
boolean hasIdentifier()

void setAbbreviation(String abbreviation)
void setDisplayName(String displayName)
void setIdentifier(String identifier)
void setSlot(int slot)
void setAmount(int amount)
void setEmpty(boolean isEmpty)
⚠️ **GitHub.com Fallback** ⚠️