Revamp crafting API

Author: Kazzuk

api/src/main/java/org/cloudburstmc/api/crafting/ComplexRecipe.java

@@ -0,0 +1,8 @@
+package org.cloudburstmc.api.crafting;
+
+/**
+ * Marker interface for recipes whose output is computed dynamically at runtime
+ * rather than being a fixed item stack.
+ */
+public interface ComplexRecipe extends Recipe {
+}

api/src/main/java/org/cloudburstmc/api/crafting/CookingRecipe.java

@@ -0,0 +1,29 @@
+package org.cloudburstmc.api.crafting;
+
+import org.cloudburstmc.api.item.ItemStack;
+
+/**
+ * A recipe processed by a cooking station (furnace, blast furnace, smoker, campfire).
+ * The specific station is identified by {@link #getBlock()}.
+ */
+public interface CookingRecipe extends Recipe {
+
+    /**
+     * Returns the ingredient descriptor for the input slot.
+     * Can be a tag-based ingredient for recipes that accept a category of items.
+     */
+    RecipeIngredient getInput();
+
+    /**
+     * Returns a representative {@link ItemStack} for the input slot.
+     * Useful for display and item-based recipe matching.
+     * For tag-based inputs this returns a representative concrete item that satisfies the tag.
+     */
+    ItemStack getInputItem();
+
+    /**
+     * Returns the priority used to order this recipe in the recipe book display.
+     * Lower values are preferred over higher values when multiple cooking recipes match the same input.
+     */
+    int getPriority();
+}

api/src/main/java/org/cloudburstmc/api/crafting/CraftingRecipe.java

@@ -5,25 +5,41 @@
 import java.util.List;
 
 /**
- * @author CreeperFace
+ * A recipe crafted in a crafting grid, either the 2x2 inventory grid or a 3x3 crafting table.
+ * Subtypes include {@link ShapedRecipe}, {@link ShapelessRecipe}, and {@link ShulkerBoxRecipe}.
  */
 public interface CraftingRecipe extends Recipe {
 
+    /**
+     * Returns {@code true} if this recipe requires a 3x3 crafting grid (crafting table).
+     * Returns {@code false} if it can be crafted in the 2x2 inventory grid.
+     */
     boolean requiresCraftingTable();
 
+    /**
+     * Returns the secondary output items produced alongside the primary result.
+     * Does not include the primary result ({@link #getResult()}).
+     * Returns an empty list if there are no secondary outputs.
+     */
     List<? extends ItemStack> getExtraResults();
 
+    /**
+     * Returns all output items: the primary result followed by any secondary outputs.
+     * Equivalent to prepending {@link #getResult()} to {@link #getExtraResults()}.
+     */
     List<? extends ItemStack> getAllResults();
 
+    /**
+     * Returns the priority used to order this recipe in the recipe book display.
+     * Lower values are preferred over higher values when multiple recipes share the same inputs.
+     */
     int getPriority();
 
     /**
-     * Returns whether the specified list of crafting grid inputs and outputs matches this recipe. Outputs DO NOT
-     * include the primary result item.
-     *
-     * @param input  2D array of items taken from the crafting grid
-     * @param output 2D array of items put back into the crafting grid (secondary results)
-     * @return bool
+     * Returns the context under which this recipe is automatically unlocked in the recipe book.
+     * Defaults to {@link RecipeUnlockContext#ALWAYS_UNLOCKED}.
      */
-    boolean matchItems(ItemStack[][] input, ItemStack[][] output);
+    default RecipeUnlockContext getUnlockContext() {
+        return RecipeUnlockContext.ALWAYS_UNLOCKED;
+    }
 }

api/src/main/java/org/cloudburstmc/api/crafting/MixRecipe.java

@@ -1,48 +1,29 @@
 package org.cloudburstmc.api.crafting;
 
-import lombok.ToString;
 import org.cloudburstmc.api.item.ItemStack;
-import org.cloudburstmc.api.util.Identifier;
 
-@ToString
-public abstract class MixRecipe implements Recipe {
-
-    private final ItemStack input;
-    private final ItemStack ingredient;
-    private final ItemStack output;
-    private final Identifier recipeId;
-
-    public MixRecipe(Identifier id, ItemStack input, ItemStack ingredient, ItemStack output) {
-        this.recipeId = id;
-        this.input = input;
-        this.ingredient = ingredient;
-        this.output = output;
-    }
-
-    @Override
-    public Identifier getId() {
-        return this.recipeId;
-    }
-
-    public ItemStack getIngredient() {
-        return ingredient;
-    }
-
-    public ItemStack getInput() {
-        return input;
-    }
-
-    public ItemStack getResult() {
-        return output;
-    }
-
-    @Override
-    public RecipeType getType() {
-        throw new UnsupportedOperationException();
-    }
-
-    @Override
-    public Identifier getBlock() {
-        throw new UnsupportedOperationException();
-    }
-}
+/**
+ * A brewing stand recipe where one input item and one reagent combine to produce one output item.
+ *
+ * <p>Used for two distinct recipe categories, distinguished by {@link #getType()}:
+ * <ul>
+ *   <li>{@link RecipeType#POTION}: potion brewing, combining a base potion with a reagent item.
+ *   <li>{@link RecipeType#POTION_CONTAINER}: container transformation, changing the container type of the potion
+ *       (e.g. converting a regular potion into a splash potion).
+ * </ul>
+ * Both use the brewing stand as their station.
+ */
+public interface MixRecipe extends Recipe {
+
+    /**
+     * Returns the base input item for this recipe.
+     * Always a specific item stack rather than a tag-based ingredient.
+     */
+    ItemStack getInput();
+
+    /**
+     * Returns the reagent item placed in the top slot of the brewing stand.
+     * Always a specific item stack rather than a tag-based ingredient.
+     */
+    ItemStack getIngredient();
+}

api/src/main/java/org/cloudburstmc/api/crafting/Recipe.java

@@ -1,14 +1,45 @@
 package org.cloudburstmc.api.crafting;
 
+import org.cloudburstmc.api.block.BlockIds;
 import org.cloudburstmc.api.item.ItemStack;
 import org.cloudburstmc.api.util.Identifier;
 
+/**
+ * Base interface for all recipes. Every recipe has a unique identifier, a result item,
+ * a type that categorizes it, and an associated crafting station.
+ */
 public interface Recipe {
+
+    /**
+     * Returns the unique identifier for this recipe.
+     */
     Identifier getId();
 
+    /**
+     * Returns the item produced when this recipe is completed.
+     */
     ItemStack getResult();
 
+    /**
+     * Returns the type of this recipe, indicating which crafting mechanic it belongs to.
+     */
     RecipeType getType();
 
+    /**
+     * Returns the identifier of the crafting station this recipe belongs to, or {@code null}
+     * if no station is associated.
+     *
+     * <p>Common values by recipe category:
+     * <ul>
+     *   <li>Crafting recipes ({@link ShapedRecipe}, {@link ShapelessRecipe}): {@code minecraft:crafting_table}
+     *       for 3x3 recipes, or a specific block identifier for station-specific recipes.
+     *   <li>Cooking recipes ({@link CookingRecipe}): {@code minecraft:furnace}, {@code minecraft:blast_furnace},
+     *       {@code minecraft:smoker}, or {@code minecraft:campfire}.
+     *   <li>Smithing recipes ({@link SmithingRecipe}): {@code minecraft:smithing_table}.
+     *   <li>Stonecutting recipes ({@link StonecuttingRecipe}): {@code minecraft:stonecutter}.
+     *   <li>Brewing recipes ({@link MixRecipe}): {@code minecraft:brewing_stand}.
+     *   <li>Complex recipes ({@link ComplexRecipe}): {@link BlockIds#AIR}, no physical station.
+     * </ul>
+     */
     Identifier getBlock();
 }

api/src/main/java/org/cloudburstmc/api/crafting/RecipeIngredient.java

@@ -0,0 +1,45 @@
+package org.cloudburstmc.api.crafting;
+
+import org.cloudburstmc.api.item.ItemStack;
+import org.cloudburstmc.api.util.Identifier;
+
+import java.util.function.Predicate;
+
+/**
+ * An ingredient slot in a recipe.
+ *
+ * <p>Use pattern matching to branch on the concrete type:
+ * <pre>{@code
+ * switch (ingredient) {
+ *     case RecipeIngredient.Exact(var item) -> // one specific item
+ *     case RecipeIngredient.Tag(var tag)    -> // any item carrying the given tag
+ * }
+ * }</pre>
+ *
+ * <p>{@code test(ItemStack)} works on {@code Exact} variants. On a {@code Tag} variant it
+ * always returns {@code false} because tag membership requires registry access that is not
+ * available through this interface.
+ */
+public sealed interface RecipeIngredient extends Predicate<ItemStack> permits RecipeIngredient.Exact, RecipeIngredient.Tag {
+
+    /**
+     * An ingredient that requires one specific item type.
+     */
+    record Exact(Identifier item) implements RecipeIngredient {
+        @Override
+        public boolean test(ItemStack stack) {
+            return !stack.isEmpty() && stack.getType().getId().equals(item);
+        }
+    }
+
+    /**
+     * An ingredient satisfied by any item carrying the given tag.
+     * {@code test} always returns {@code false} for this variant.
+     */
+    record Tag(Identifier tag) implements RecipeIngredient {
+        @Override
+        public boolean test(ItemStack stack) {
+            return false;
+        }
+    }
+}

api/src/main/java/org/cloudburstmc/api/crafting/RecipeType.java

@@ -1,18 +1,55 @@
 package org.cloudburstmc.api.crafting;
 
+/**
+ * Identifies the crafting mechanic a recipe belongs to.
+ */
 public enum RecipeType {
+    /**
+     * A recipe with unordered ingredients placed anywhere in the crafting grid.
+     */
     SHAPELESS,
+    /**
+     * A recipe where ingredients must be placed in a specific grid arrangement.
+     */
     SHAPED,
-    FURNACE,
-    FURNACE_DATA,
-    MULTI,
+    /**
+     * A recipe processed by a cooking station: furnace, blast furnace, smoker, or campfire.
+     */
+    COOKING,
+    /**
+     * A recipe whose output is computed at runtime rather than being a fixed item, such as firework crafting.
+     */
+    COMPLEX,
+    /**
+     * A shapeless recipe that recolors a shulker box by combining it with a dye.
+     */
     SHULKER_BOX,
+    /**
+     * A shapeless recipe used for chemistry-based crafting. Behaves identically to {@link #SHAPELESS}.
+     */
     SHAPELESS_CHEMISTRY,
+    /**
+     * A shaped recipe used for chemistry-based crafting. Behaves identically to {@link #SHAPED}.
+     */
     SHAPED_CHEMISTRY,
+    /**
+     * A smithing table recipe that transforms a base item into a new item using a template and an addition material.
+     */
     SMITHING_TRANSFORM,
+    /**
+     * A smithing table recipe that applies a decorative trim pattern to a piece of armor.
+     */
     SMITHING_TRIM,
-
-    //Internal Use
+    /**
+     * A recipe processed by the stonecutter, producing one specific cut output from a stone-type input.
+     */
+    STONECUTTING,
+    /**
+     * A brewing stand recipe that combines a base potion with a reagent to produce a new potion.
+     */
     POTION,
-    CONTAINER
+    /**
+     * A brewing stand recipe that changes the container type of the potion, such as converting a regular potion to a splash potion.
+     */
+    POTION_CONTAINER
 }

api/src/main/java/org/cloudburstmc/api/crafting/RecipeUnlockContext.java

@@ -0,0 +1,28 @@
+package org.cloudburstmc.api.crafting;
+
+/**
+ * Controls when a crafting recipe is made visible to players in the recipe book.
+ *
+ * <p>The default for all built-in recipes is {@link #ALWAYS_UNLOCKED}. Use
+ * {@link #PLAYER_IN_WATER} or {@link #PLAYER_HAS_MANY_ITEMS} for recipes that should only
+ * appear when specific conditions are met, or {@link #NONE} to suppress automatic unlocking
+ * entirely and handle discovery manually.
+ */
+public enum RecipeUnlockContext {
+    /**
+     * The recipe is never automatically unlocked. Discovery must be handled explicitly.
+     */
+    NONE,
+    /**
+     * The recipe is always visible in the recipe book without any condition.
+     */
+    ALWAYS_UNLOCKED,
+    /**
+     * The recipe becomes visible when the player enters water.
+     */
+    PLAYER_IN_WATER,
+    /**
+     * The recipe becomes visible when the player has collected many different item types.
+     */
+    PLAYER_HAS_MANY_ITEMS
+}