Skip to content

Custom Ingredient System

Jump to bottom
Traqueur edited this page Oct 5, 2024 · 4 revisions

Custom Ingredient System

The custom ingredient system in the Recipes API allows for flexibility when defining recipe ingredients, supporting both standard items and custom items from external plugins. You can even implement your own custom ingredient types to fit your needs. This guide will walk you through the available options and show you how to implement them both in Java and YAML.

Ingredient Types

The Recipes API supports multiple ingredient types, each represented by different classes.

Here is a table summarizing the different ingredient types available in the recipe system, along with their corresponding classes and an explanation of their usage:

Ingredient Type Corresponding Class Description
ItemStackIngredient ItemStackIngredient Verifies the ItemStack type and certain metadata like lore and custom model data, but does not check the item name.
ItemStackStrictIngredient ItemStackStrictIngredient Performs an exact match on the ItemStack, checking everything: type, amount, lore, custom model data, and the name.
TagIngredient TagIngredient Allows the use of tags to include multiple materials in the verification (e.g., all types of wood planks). Great for flexible recipe matching.
MaterialIngredient MaterialIngredient Only verifies the type (Material) of the ItemStack, ignoring lore, custom data, and other metadata.
ItemsAdderIngredient ItemsAdderIngredient Uses ItemsAdder IDs to verify a custom item. Ideal for servers using custom items created with the ItemsAdder plugin.
OraxenIngredient OraxenIngredient Similar to ItemsAdderIngredient, but works with items created using the Oraxen plugin. Verifies custom item IDs from Oraxen.

Class Details:

  • ItemStackIngredient: This class is used when you need to verify specific properties of an ItemStack, such as its lore or custom model data, without requiring an exact match on the item's name.

  • ItemStackStrictIngredient: Ideal for strict verification, this class ensures that all aspects of the ItemStack match, including the item name. Only the exact version of the item will be accepted.

  • TagIngredient: This class is useful for recipes that can accept multiple types of items. For example, if you want the recipe to accept all types of wood (oak, spruce, etc.), you can use tags.

  • MaterialIngredient: When you only need to check the type of the ItemStack (e.g., ensuring the item is a DIAMOND), this class is the simplest option. It does not account for other properties such as lore or custom model data.

  • ItemsAdderIngredient: This class integrates with the ItemsAdder plugin to allow custom items created with it to be used in recipes. It verifies the custom item using its ItemsAdder ID.

  • OraxenIngredient: Similar to ItemsAdderIngredient, but for the Oraxen plugin. It allows custom items from Oraxen to be used in recipes by verifying their Oraxen-specific item IDs.

This table provides an overview of the various ingredient customization options for your recipe system, from basic items to more complex custom items introduced by third-party plugins.

You can create and register your own custom ingredient classes by implementing the Ingredient interface.

Defining Ingredients in YAML

When defining a recipe in YAML, ingredients can be specified using Base64-encoded ItemStacks. This encoding allows custom items, metadata, and attributes to be preserved and properly recognized within the recipe.

For ingredients that come from a third-party plugin (e.g., ItemsAdder), you must follow the format <plugin_name>:, where is the custom implementation for the third-party plugin.

So for ItemStack replace <plugin_name> by "itemstack" and use base64 format, for tag replace by "tag", for material use "material".

You can view the implementation in RecipeConfiguration Class.

Below is an example YAML configuration for a crafting recipe:

# Type of the recipe
type: CRAFTING_SHAPED

# Group and category
group: example
category: MISC

# Crafting pattern
pattern:
  - "##"
  - "##"

# Result ItemStack (Base64 encoded for custom items)
result:
  item: "base64encodeditemstack"  # This is the base64-encoded item representation
  amount: 64

# Ingredients (Base64 encoded)
ingredients:
  - item: "base64encodedstone"
    sign: '#'

The result and ingredients are provided as Base64-encoded ItemStacks, which allows full control over the item properties, including custom names, lore, enchantments, and more.

Creating Custom Ingredients

The Recipes API supports adding your own custom ingredient types by implementing the Ingredient interface. Below is an example interface for custom ingredients:

import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.RecipeChoice;

/**
 * Represents an ingredient.
 */
public interface Ingredient {

    /**
     * Check if the item is similar to the ingredient.
     * @param item The item to check.
     * @return true if the item is similar to the ingredient, false otherwise.
     */
    boolean isSimilar(ItemStack item);

    /**
     * Get the choice of the ingredient.
     * @return The choice of the ingredient.
     */
    RecipeChoice choice();

    /**
     * Get the sign of the ingredient.
     * @return The sign of the ingredient.
     */
    Character sign();
}

To define a new custom ingredient, extend this Ingredient interface or extend this BaseIngredient and implement the required methods to handle the item checks and choices. You can now use this custom ingredient in your recipes. This allows you to further customize and extend the plugin’s functionality to suit your server’s needs.

By leveraging the custom ingredient system, you can integrate both standard Minecraft items and items from plugins such as ItemsAdder, and even create your own custom ingredients to fully control the crafting experience on your server. The Base64 encoding in YAML ensures that all item data is preserved when defining recipes.

Clone this wiki locally