Add wiki and javadocs to IntProviderIngredient and IntProviderFluidIngredient (#3539)

Author: DilithiumThoride

docs/content/Modpacks/Other-Topics/Adding-and-Removing-Recipes.md

@@ -98,9 +98,11 @@ ServerEvents.recipes(event => {
         - `.itemOutput()`
         - `.itemOutputs()`
         - `.chancedOutput()`
+        - `.outputItemsRanged()`
     - Fluids:
         - `.outputFluids()`
         - `.chancedFluidOutput()`
+        - `.outputFluidsRanged()`
 - Energy:
     - `.inputEU()`:  
       Makes the recipe consume a lump sum of EU to start the recipe. Most often seen in fusion reactor recipes.
@@ -109,6 +111,26 @@ ServerEvents.recipes(event => {
     - `.EUt()`:  
       Takes a numerical value representing an EU amount. Positive values will make the recipe consume energy per tick,
       negative ones will make it generate energy per tick.
+- Chanced Ingredients:
+  - Ingredients that are not consumed/produced on every run of a recipe. Can be expressed as either a fraction, or as an
+    integer chance out of 10,000.
+  - Assigning an Input ingredient with a Chance of `0` causes that ingredient to be flagged as `Non-Consumed` in EMI. 
+  This can also be done more easily using `.notConsumable()`.
+  - Recipes with chanced ingredients can also have a Chance Logic designated for each of their input/output sets, using 
+  one or more of the functions `.chancedItemInputLogic()`, `.chancedFluidInputLogic()`, `.chancedTickInputLogic()`,
+  `.chancedItemOutputLogic()`, `.chancedFluidOutputLogic()`, `.chancedTickOutputLogic()`
+  - Valid options for chanced logic are:
+    - `or` - (default) Any item/fluid which succeeds on its chance roll is produced/consumed.
+    - `and` - If _all_ items/fluids succeed on their chance roll, all are produced/consumed together. Otherwise, none are. 
+    - `xor` - Guarantees that exactly one of the chanced items/fluids will be produced/consumed on every run. 
+    Behavior was changed in 7.0.0.
+    - `first` - Makes a chance roll for each item/fluid, in order of registration. Only the first item which succeeds 
+    on its roll is returned. Prior to 7.0.0, this was the behavior of `xor` logic.
+- Ranged Outputs:
+  - Item or Fluid outputs that will produce a random amount within a `min, max` range (inclusive).
+- Circuits
+  - Many GT recipes use a `Programmed Circuit` item with a Configuration value of `1-32` as a `Non-Consumed` input,
+  to distinguish them from other recipes in the same machine with similar ingredients. `.circuit()` adds one to a recipe.
 - More granular functionality:
     - `.perTick()`:  
       Using this will enable you to control whether a recipe input/output is consumed/produced per tick the recipe is

src/main/java/com/gregtechceu/gtceu/api/recipe/ingredient/IntProviderFluidIngredient.java

@@ -12,22 +12,37 @@
 import net.minecraft.util.valueproviders.UniformInt;
 import net.minecraftforge.fluids.FluidStack;
 
+import com.google.errorprone.annotations.DoNotCall;
 import com.google.gson.*;
 import com.mojang.serialization.Codec;
 import com.mojang.serialization.JsonOps;
 import lombok.Getter;
 import lombok.Setter;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Allows a {@link FluidIngredient} to be created with a ranged {@code amount}, which will be randomly rolled upon
+ * recipe completion.
+ * Only valid as a recipe fluid {@code output}.
+ * Instantiated using {@link IntProviderFluidIngredient#of()}, with a {@link FluidIngredient}
+ * and either an {@link IntProvider} or {@code int, int} range bounds (inclusive).
+ * Functions similarly to {@link IntProviderIngredient}.
+ */
 public class IntProviderFluidIngredient extends FluidIngredient {
 
     public static final Codec<IntProviderFluidIngredient> CODEC = ExtraCodecs.JSON
             .xmap(IntProviderFluidIngredient::fromJson, IntProviderFluidIngredient::toJson);
 
     @Getter
     private final IntProvider countProvider;
+    /**
+     * The last result of {@link IntProviderFluidIngredient#getSampledCount()}. -1 if not rolled.
+     */
     @Setter
     protected int sampledCount = -1;
+    /**
+     * The {@link FluidIngredient} to have a ranged amount.
+     */
     @Getter
     private final FluidIngredient inner;
     @Setter
@@ -46,11 +61,23 @@ public IntProviderFluidIngredient copy() {
         return ipfi;
     }
 
+    /**
+     * An {@link IntProviderFluidIngredient} does not have an amount.
+     * You probably want either {@link IntProviderFluidIngredient#getStacks()} or
+     * {@link IntProviderFluidIngredient#getMaxSizeStack()}.
+     */
+    @DoNotCall
     @Override
     public int getAmount() {
         return -1;
     }
 
+    /**
+     * Gets a usable {@link FluidStack FluidStack[]} from this {@link IntProviderFluidIngredient}.
+     * If this ingredient has not yet had its {@link IntProviderFluidIngredient#sampledCount} rolled, rolls it.
+     *
+     * @return a {@link FluidStack FluidStack[]} with amount {@link IntProviderFluidIngredient#sampledCount}
+     */
     @Override
     public FluidStack[] getStacks() {
         if (fluidStacks == null) {
@@ -68,12 +95,40 @@ public FluidStack[] getStacks() {
         return fluidStacks;
     }
 
+    /**
+     * Gets a {@link FluidStack} containing the maximum possible output from this {@link IntProviderFluidIngredient}.
+     * Mainly used for things like Recipe provider simulations to see if there is enough tank space to handle
+     * the recipe output.
+     *
+     * @return a {@link FluidStack} with amount {@link IntProvider#getMaxValue()}
+     */
     public @NotNull FluidStack getMaxSizeStack() {
         FluidStack[] in = inner.getStacks();
         if (in.length == 0) return FluidStack.EMPTY;
         return new FluidStack(in[0], countProvider.getMaxValue());
     }
 
+    /**
+     * If this ingredient has not yet had its {@link IntProviderFluidIngredient#sampledCount} rolled, rolls it and
+     * returns the roll.
+     * If it has, returns the existing roll.
+     * Passthrough method, invokes {@link IntProviderFluidIngredient#getSampledCount(RandomSource)} using the threadsafe
+     * {@link GTValues#RNG}.
+     *
+     * @return the amount rolled
+     */
+    public int getSampledCount() {
+        return getSampledCount(GTValues.RNG);
+    }
+
+    /**
+     * If this ingredient has not yet had its {@link IntProviderFluidIngredient#sampledCount} rolled, rolls it and
+     * returns the roll.
+     * If it has, returns the existing roll.
+     *
+     * @param random {@link RandomSource}, must be threadsafe, usually called using {@link GTValues#RNG}.
+     * @return the amount rolled
+     */
     public int getSampledCount(@NotNull RandomSource random) {
         if (sampledCount == -1) {
             sampledCount = countProvider.sample(random);
@@ -86,6 +141,10 @@ public boolean isEmpty() {
         return inner.isEmpty();
     }
 
+    /**
+     * @param inner    {@link FluidIngredient}
+     * @param provider usually as {@link UniformInt#of(int, int)}
+     */
     public static IntProviderFluidIngredient of(FluidIngredient inner, IntProvider provider) {
         return new IntProviderFluidIngredient(inner, provider);
     }
@@ -94,6 +153,13 @@ public static IntProviderFluidIngredient of(FluidStack inner, int min, int max)
         return IntProviderFluidIngredient.of(FluidIngredient.of(inner), UniformInt.of(min, max));
     }
 
+    /**
+     * Properties:
+     * <ul>
+     * <li>{@code count_provider}</li>
+     * <li>{@code inner}</li>
+     * </ul>
+     */
     @Override
     public @NotNull JsonElement toJson() {
         JsonObject json = new JsonObject();
@@ -103,6 +169,13 @@ public static IntProviderFluidIngredient of(FluidStack inner, int min, int max)
         return json;
     }
 
+    /**
+     * @param json containing
+     *             <ul>
+     *             <li>{@code count_provider}</li>
+     *             <li>{@code inner}</li>
+     *             </ul>
+     */
     public static IntProviderFluidIngredient fromJson(JsonElement json) {
         if (json == null || json.isJsonNull()) {
             throw new JsonSyntaxException("Fluid ingredient cannot be null");

src/main/java/com/gregtechceu/gtceu/api/recipe/ingredient/IntProviderIngredient.java

@@ -26,15 +26,29 @@
 
 import java.util.stream.Stream;
 
+/**
+ * Allows an {@link Ingredient} to be created with a ranged {@code count}, which will be randomly rolled upon recipe
+ * completion.
+ * Only valid as a recipe item {@code output}.
+ * Instantiated using {@link IntProviderIngredient#of()}, with a {@link Ingredient} or {@link ItemStack},
+ * and an {@link IntProvider}.
+ * Functions similarly to {@link IntProviderFluidIngredient}.
+ */
 public class IntProviderIngredient extends Ingredient {
 
     public static final ResourceLocation TYPE = GTCEu.id("int_provider");
     public static final ItemStack[] EMPTY_STACK_ARRAY = new ItemStack[0];
 
     @Getter
     protected final IntProvider countProvider;
+    /**
+     * The last result of {@link IntProviderIngredient#getSampledCount(RandomSource)}. -1 if not rolled.
+     */
     @Setter
     protected int sampledCount = -1;
+    /**
+     * The {@link Ingredient} to have a ranged amount.
+     */
     @Getter
     protected final Ingredient inner;
     @Setter
@@ -46,12 +60,20 @@ protected IntProviderIngredient(Ingredient inner, IntProvider countProvider) {
         this.countProvider = countProvider;
     }
 
+    /**
+     * @param inner         {@link Ingredient}
+     * @param countProvider usually as {@link net.minecraft.util.valueproviders.UniformInt#of(int, int)}
+     */
     public static IntProviderIngredient of(Ingredient inner, IntProvider countProvider) {
         Preconditions.checkArgument(countProvider.getMinValue() >= 0,
                 "IntProviderIngredient must have a min value of at least 0.");
         return new IntProviderIngredient(inner, countProvider);
     }
 
+    /**
+     * @param stack         {@link ItemStack}
+     * @param countProvider usually as {@link net.minecraft.util.valueproviders.UniformInt#of(int, int)}
+     */
     public static IntProviderIngredient of(ItemStack stack, IntProvider countProvider) {
         Ingredient inner = stack.hasTag() ? StrictNBTIngredient.of(stack) : Ingredient.of(stack);
         return of(inner, countProvider);
@@ -62,6 +84,12 @@ public boolean test(@Nullable ItemStack stack) {
         return inner.test(stack);
     }
 
+    /**
+     * Gets a usable {@link ItemStack ItemStack[]} from this {@link IntProviderIngredient}.
+     * If this ingredient has not yet had its {@link IntProviderIngredient#sampledCount} rolled, rolls it.
+     * 
+     * @return a {@link ItemStack ItemStack[]} with count {@link IntProviderIngredient#sampledCount}
+     */
     @Override
     public ItemStack @NotNull [] getItems() {
         if (itemStacks == null) {
@@ -78,11 +106,26 @@ public boolean test(@Nullable ItemStack stack) {
         return itemStacks;
     }
 
+    /**
+     * Gets a {@link ItemStack} containing the maximum possible output from this {@link IntProviderIngredient}.
+     * Mainly used for things like Recipe provider simulations to see if there is enough inventory space to handle
+     * the recipe output.
+     * 
+     * @return a {@link ItemStack} with count {@link IntProvider#getMaxValue()}
+     */
     public @NotNull ItemStack getMaxSizeStack() {
         if (inner.getItems().length == 0) return ItemStack.EMPTY;
         else return inner.getItems()[0].copyWithCount(countProvider.getMaxValue());
     }
 
+    /**
+     * If this ingredient has not yet had its {@link IntProviderIngredient#sampledCount} rolled, rolls it and returns
+     * the roll.
+     * If it has, returns the existing roll.
+     * 
+     * @param random {@link RandomSource}, must be threadsafe, usually called using {@link GTValues#RNG}.
+     * @return the count rolled
+     */
     public int getSampledCount(@NotNull RandomSource random) {
         if (sampledCount == -1) {
             sampledCount = countProvider.sample(random);
@@ -106,10 +149,26 @@ public IIngredientSerializer<? extends Ingredient> getSerializer() {
         return SERIALIZER;
     }
 
+    /**
+     * @param json containing
+     *             <ul>
+     *             <li>{@code type}</li>
+     *             <li>{@code count_provider}</li>
+     *             <li>{@code ingredient}</li>
+     *             </ul>
+     */
     public static IntProviderIngredient fromJson(JsonObject json) {
         return SERIALIZER.parse(json);
     }
 
+    /**
+     * Properties:
+     * <ul>
+     * <li>{@code type}</li>
+     * <li>{@code count_provider}</li>
+     * <li>{@code ingredient}</li>
+     * </ul>
+     */
     @Override
     public @NotNull JsonElement toJson() {
         JsonObject json = new JsonObject();