From 9623935b5541a223a3bd4f04a5680b86ff5c7bdf Mon Sep 17 00:00:00 2001 From: Frank Date: Mon, 1 Aug 2022 19:30:36 +0200 Subject: [PATCH] Some JavaDoc --- .../recipes/AbstractAdvancementRecipe.java | 126 +++++++++++++++++- 1 file changed, 120 insertions(+), 6 deletions(-) diff --git a/src/main/java/org/betterx/bclib/recipes/AbstractAdvancementRecipe.java b/src/main/java/org/betterx/bclib/recipes/AbstractAdvancementRecipe.java index 3139a51b..8170f479 100644 --- a/src/main/java/org/betterx/bclib/recipes/AbstractAdvancementRecipe.java +++ b/src/main/java/org/betterx/bclib/recipes/AbstractAdvancementRecipe.java @@ -17,11 +17,29 @@ import net.minecraft.world.level.block.Block; import java.util.Arrays; import java.util.stream.Collectors; +/** + * Simple extension class that allows Recipe-builders to automatically generated Recipe-Avancements. + *

+ * Implementing classes need to call {@link #createAdvancement(ResourceLocation, boolean)} or + * {@link #createAdvancement(ResourceLocation, ItemLike)} to enable an advncement and + * {@link #registerAdvancement(Recipe)} to finalize and register the new Advancement. + *

+ * After that the unlockedBy-Methods can bes used to add Items that will unlock the Recipe (and prompt the unlock) + */ public class AbstractAdvancementRecipe { protected AdvancementManager.Builder advancement; boolean hasUnlockTrigger = false; boolean generateAdvancement = false; + /** + * Your implementing class should call this method to prepare a new {@link AdvancementManager.Builder} + *

+ * For Example {@link FurnaceRecipe} will call this in the + * {@link FurnaceRecipe#make(String, String, ItemLike, ItemLike)}-Method + * + * @param id {@link ResourceLocation} for this advancement + * @param isTool true, if this is registered for a tool + */ protected void createAdvancement(ResourceLocation id, boolean isTool) { hasUnlockTrigger = false; generateAdvancement = true; @@ -33,12 +51,35 @@ public class AbstractAdvancementRecipe { ); } + + /** + * Your implementing class should call this method to prepare a new {@link AdvancementManager.Builder} + *

+ * For Example {@link GridRecipe} will call this in the {@link GridRecipe#make(ResourceLocation, ItemLike)}-Method. + *

+ * This method will call {@link #createAdvancement(ResourceLocation, boolean)}. The output object is used to + * determine wether or not this is a tool recipe. + * + * @param id {@link ResourceLocation} for this advancement + * @param output Used to determine wether or not this is a tool recipe. + */ protected void createAdvancement(ResourceLocation id, ItemLike output) { createAdvancement(id, (output.asItem() instanceof TieredItem || output.asItem() instanceof ArmorItem)); } private int nameCounter = 0; + /** + * The Recipe will be unlocked by one of the passed Items. As sonn als players have one in their Inventory + * the recipe will unlock. Those Items are mostly the input Items for the recipe. + *

+ * If you need to use other unlock-Criteria, you can get the {@link AdvancementManager.Builder}-Instance + * using {@link #getAdvancementBuilder()} + *

+ * This method will automatically get the Items from the stacl and call {@link #unlockedBy(ItemLike...)} + * + * @param stacks {@link ItemStack}s that will unlock the recipe. The count is ignored. + */ public void unlockedBy(ItemStack... stacks) { ItemLike[] items = Arrays.stream(stacks) .filter(stack -> stack.getCount() > 0) @@ -48,6 +89,18 @@ public class AbstractAdvancementRecipe { unlockedBy(items); } + /** + * The Recipe will be unlocked by one of the passed Items. As sonn als players have one in their Inventory + * the recipe will unlock. Those Items are mostly the input Items for the recipe. + *

+ * If you need to use other unlock-Criteria, you can get the {@link AdvancementManager.Builder}-Instance + * using {@link #getAdvancementBuilder()} + *

+ * This method will automatically derive a unique name for the criterion and call + * {@link #unlockedBy(String, ItemLike...)} + * + * @param items {@link Item}s or {@link Block}s that will unlock the recipe. + */ public void unlockedBy(ItemLike... items) { String name = "has_" + (nameCounter++) + "_" + Arrays.stream(items) @@ -61,6 +114,18 @@ public class AbstractAdvancementRecipe { unlockedBy(name, items); } + /** + * The Recipe will be unlocked by one of the passed Items. As sonn als players have one in their Inventory + * the recipe will unlock. Those Items are mostly the input Items for the recipe. + *

+ * If you need to use other unlock-Criteria, you can get the {@link AdvancementManager.Builder}-Instance + * using {@link #getAdvancementBuilder()} + *

+ * This method will automatically derive a unique name for the criterion and call + * {@link #unlockedBy(String, TagKey)} + * + * @param tag All items from this Tag will unlock the recipe + */ public void unlockedBy(TagKey tag) { ResourceLocation id = tag.location(); if (id != null) { @@ -68,27 +133,76 @@ public class AbstractAdvancementRecipe { } } + + /** + * The Recipe will be unlocked by one of the passed Items. As sonn als players have one in their Inventory + * the recipe will unlock. Those Items are mostly the input Items for the recipe. + *

+ * If you need to use other unlock-Criteria, you can get the {@link AdvancementManager.Builder}-Instance + * using {@link #getAdvancementBuilder()} + * + * @param name The name for this unlock-Criteria + * @param items {@link Item}s or {@link Block}s that will unlock the recipe. + */ public void unlockedBy(String name, ItemLike... items) { - hasUnlockTrigger = true; - advancement.addInventoryChangedCriterion(name, items); + if (advancement != null) { + hasUnlockTrigger = true; + advancement.addInventoryChangedCriterion(name, items); + } } + /** + * The Recipe will be unlocked by one of the passed Items. As sonn als players have one in their Inventory + * the recipe will unlock. Those Items are mostly the input Items for the recipe. + *

+ * If you need to use other unlock-Criteria, you can get the {@link AdvancementManager.Builder}-Instance + * using {@link #getAdvancementBuilder()} + * + * @param name The name for this unlock-Criteria + * @param tag All items from this Tag will unlock the recipe + */ public void unlockedBy(String name, TagKey tag) { - hasUnlockTrigger = true; - advancement.addInventoryChangedCriterion(name, tag); + if (advancement != null) { + hasUnlockTrigger = true; + advancement.addInventoryChangedCriterion(name, tag); + } } + /** + * Disables the generation of an advancement + */ public void noAdvancement() { generateAdvancement = false; } - public void clearAdvancementCriteria() { + /** + * Resets the advancement. This is usefully when you need more controll but the Recipe Builder + * (like {@link GridRecipe} is automatically adding Items to the criterion list. + */ + public void resetAdvancement() { if (advancement != null) advancement = AdvancementManager.Builder.createEmptyCopy(advancement); } + /** + * Returns the underlying Builder Instance + * + * @return null or The underlying builder Instance + */ + public AdvancementManager.Builder getAdvancementBuilder() { + return advancement; + } + + + /** + * Your implementing class should calls this method to finalize the advancement and register it. + *

+ * For Example {@link GridRecipe} will call this in the {@link GridRecipe#build()}-Method + * + * @param recipe The generated recipe that need to be linked to the Advancement + */ protected void registerAdvancement(Recipe recipe) { - if (hasUnlockTrigger && generateAdvancement) { + if (hasUnlockTrigger && generateAdvancement && advancement != null) { advancement .startDisplay(recipe.getResultItem().getItem()) .hideFromChat()