Recipe Remainder API

library/item/item_setting/build.gradle

@@ -12,6 +12,14 @@ qslModule {
 		core {
 			api("qsl_base")
 			testmodOnly("resource_loader")
+			testmodOnly("lifecycle_events")
+			testmodOnly("networking")
+		}
+		data {
+			testmodOnly("tags")
+		}
+		item {
+			testmodOnly("item_content_registry")
 		}
 	}
 }

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/api/QuiltCustomItemSettings.java

@@ -19,18 +19,34 @@
 import org.quiltmc.qsl.item.setting.impl.CustomItemSettingImpl;
 
 /**
- * A list of the {@link CustomItemSetting}s that are provided by Quilt
+ * A list of the {@link CustomItemSetting}s that are provided by Quilt.
  */
 public final class QuiltCustomItemSettings {
-	private QuiltCustomItemSettings() {
-	}
+	private QuiltCustomItemSettings() {}
 
 	/**
-	 * The {@link CustomItemSetting} in charge of handing {@link EquipmentSlotProvider}s
+	 * The {@link CustomItemSetting} in charge of handing {@link EquipmentSlotProvider}s.
 	 */
 	public static final CustomItemSetting<EquipmentSlotProvider> EQUIPMENT_SLOT_PROVIDER = CustomItemSettingImpl.EQUIPMENT_SLOT_PROVIDER;
+
 	/**
-	 * The {@link CustomItemSetting} in charge of handing {@link CustomDamageHandler}s
+	 * The {@link CustomItemSetting} in charge of handing {@link CustomDamageHandler}s.
 	 */
 	public static final CustomItemSetting<CustomDamageHandler> CUSTOM_DAMAGE_HANDLER = CustomItemSettingImpl.CUSTOM_DAMAGE_HANDLER;
+
+	/**
+	 * The {@link CustomItemSetting} in charge of handing {@link RecipeRemainderProvider}s. This setting should be used when implementing custom crafting systems to properly handle remainders.
+	 * <p>
+	 * The setting is currently used in the following places:
+	 * <ul>
+	 *     <li>Crafting Table</li>
+	 *     <li>Furnace Fuel</li>
+	 *     <li>Furnace Ingredient</li>
+	 *     <li>Loom Dye Input</li>
+	 *     <li>Brewing Stand Ingredient</li>
+	 *     <li>Smithing Table Addition</li>
+	 *     <li>Stone Cutter Ingredient</li>
+	 * </ul>
+	 */
+	public static final CustomItemSetting<RecipeRemainderProvider> RECIPE_REMAINDER_PROVIDER = CustomItemSettingImpl.RECIPE_REMAINDER_PROVIDER;
 }

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/api/QuiltItemSettings.java

@@ -17,6 +17,8 @@
 
 package org.quiltmc.qsl.item.setting.api;
 
+import org.jetbrains.annotations.Contract;
+
 import net.minecraft.entity.EquipmentSlot;
 import net.minecraft.item.FoodComponent;
 import net.minecraft.item.Item;
@@ -65,6 +67,55 @@ public QuiltItemSettings customDamage(CustomDamageHandler handler) {
 		return this.customSetting(QuiltCustomItemSettings.CUSTOM_DAMAGE_HANDLER, handler);
 	}
 
+	/**
+	 * Sets the stack-aware recipe remainder provider of the item.
+	 */
+	public QuiltItemSettings recipeRemainder(RecipeRemainderProvider provider) {
+		return this.customSetting(QuiltCustomItemSettings.RECIPE_REMAINDER_PROVIDER, provider);
+	}
+
+	/**
+	 * Sets the stack-aware recipe remainder to damage the item by 1 every time it is used in crafting.
+	 */
+	public QuiltItemSettings recipeDamageRemainder() {
+		return this.recipeDamageRemainder(1);
+	}
+
+	/**
+	 * Sets the stack-aware recipe remainder to return the item itself.
+	 */
+	public QuiltItemSettings recipeSelfRemainder() {
+		return this.recipeDamageRemainder(0);
+	}
+
+	/**
+	 * Sets the stack-aware recipe remainder to damage the item by a certain amount every time it is used in crafting.
+	 *
+	 * @param by the amount
+	 */
+	public QuiltItemSettings recipeDamageRemainder(int by) {
+		if (by == 0) {
+			return this.recipeRemainder((original, recipe) -> original.copy());
+		}
+
+		return this.recipeRemainder((original, recipe) -> {
+			if (!original.isDamageable()) {
+				return original.copy();
+			}
+
+			ItemStack copy = original.copy();
+
+			copy.setDamage(copy.getDamage() + by);
+
+			if (copy.getDamage() >= copy.getMaxDamage()) {
+				copy.setCount(0);
+				return ItemStack.EMPTY;
+			}
+
+			return copy;
+		});
+	}
+
 	/**
 	 * Sets a custom setting of the item.
 	 *
@@ -84,6 +135,7 @@ public <T> QuiltItemSettings customSetting(CustomItemSetting<T> setting, T value
 	// Overrides of vanilla methods
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings food(FoodComponent foodComponent) {
 		super.food(foodComponent);
 		return this;
@@ -102,30 +154,35 @@ public QuiltItemSettings maxDamageIfAbsent(int maxDamage) {
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings maxDamage(int maxDamage) {
 		super.maxDamage(maxDamage);
 		return this;
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings recipeRemainder(Item recipeRemainder) {
 		super.recipeRemainder(recipeRemainder);
 		return this;
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings group(ItemGroup group) {
 		super.group(group);
 		return this;
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings rarity(Rarity rarity) {
 		super.rarity(rarity);
 		return this;
 	}
 
 	@Override
+	@Contract("->this")
 	public QuiltItemSettings fireproof() {
 		super.fireproof();
 		return this;

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/api/RecipeRemainderLogicHandler.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2022 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.item.setting.api;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Nullable;
+
+import net.minecraft.entity.player.PlayerEntity;
+import net.minecraft.item.ItemStack;
+import net.minecraft.recipe.Recipe;
+import net.minecraft.screen.slot.Slot;
+import net.minecraft.util.collection.DefaultedList;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.world.World;
+
+import org.quiltmc.qsl.item.setting.impl.CustomItemSettingImpl;
+import org.quiltmc.qsl.item.setting.impl.RecipeRemainderLogicHandlerImpl;
+
+/**
+ * Handles most logic for stack-aware recipe remainders.
+ * This can be used by custom {@link Recipe} crafting systems.
+ */
+@ApiStatus.NonExtendable
+public interface RecipeRemainderLogicHandler {
+	/**
+	 * Gets the stack-aware remainder of the provided {@link ItemStack} for the provided {@link Recipe}.
+	 *
+	 * @param original the stack to decrement
+	 * @param recipe the recipe being used
+	 * @return the recipe remainder
+	 */
+	static ItemStack getRemainder(ItemStack original, @Nullable Recipe<?> recipe) {
+		ItemStack remainder = CustomItemSettingImpl.RECIPE_REMAINDER_PROVIDER.get(original.getItem()).getRecipeRemainder(
+				original,
+				recipe
+		);
+
+		return remainder.isEmpty() ? ItemStack.EMPTY : remainder;
+	}
+
+	/**
+	 * Handles the recipe remainder logic for crafts without a {@link PlayerEntity player} present.
+	 * Excess items that cannot be returned to a slot are dropped in the world.
+	 *
+	 * @param input the original item stack
+	 * @param recipe the recipe being used
+	 * @param inventory the inventory
+	 * @param index the index of the original stack in the inventory
+	 * @param world the world
+	 * @param location the location to drop excess remainders
+	 */
+	@Contract(mutates = "param1, param3, param5")
+	static void handleRemainderForNonPlayerCraft(ItemStack input, @Nullable Recipe<?> recipe, DefaultedList<ItemStack> inventory, int index, World world, BlockPos location) {
+		RecipeRemainderLogicHandlerImpl.handleRemainderForNonPlayerCraft(input, recipe, inventory, index, world, location);
+	}
+
+	/**
+	 * Handles the recipe remainder logic for crafts within a {@link net.minecraft.screen.ScreenHandler screen handler}.
+	 * Excess items that cannot be returned to a slot are {@linkplain net.minecraft.entity.player.PlayerInventory#offerOrDrop(ItemStack) offered to the player or dropped}.
+	 *
+	 * @param slot the slot of the original stack
+	 * @param recipe the recipe being used
+	 * @param player the player performing the craft
+	 */
+	@Contract(mutates = "param1, param3")
+	static void handleRemainderForScreenHandler(Slot slot, @Nullable Recipe<?> recipe, PlayerEntity player) {
+		RecipeRemainderLogicHandlerImpl.handleRemainderForScreenHandler(slot, recipe, player);
+	}
+}

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/api/RecipeRemainderProvider.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2022 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.item.setting.api;
+
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Nullable;
+
+import net.minecraft.inventory.Inventory;
+import net.minecraft.item.Item;
+import net.minecraft.item.ItemStack;
+import net.minecraft.recipe.Recipe;
+import net.minecraft.util.collection.DefaultedList;
+
+/**
+ * Allows an item to conditionally specify the recipe remainder.
+ * The recipe remainder is an {@link ItemStack} instead of an {@link Item}.
+ * This can be used to allow your item to get damaged instead of
+ * getting removed when used in crafting.
+ * <p>
+ * Recipe remainder providers can be set with {@link QuiltItemSettings#recipeRemainder(RecipeRemainderProvider)}.
+ */
+@FunctionalInterface
+public interface RecipeRemainderProvider {
+	/**
+	 * An {@link ItemStack} aware version of {@link Item#getRecipeRemainder()}.
+	 *
+	 * @param original the input item stack
+	 * @param recipe the recipe being used
+	 * @return the recipe remainder
+	 */
+	@Contract(value = "_, _ -> new")
+	ItemStack getRecipeRemainder(ItemStack original, @Nullable Recipe<?> recipe);
+
+	static DefaultedList<ItemStack> getRemainingStacks(Inventory inventory, Recipe<?> recipe, DefaultedList<ItemStack> defaultedList) {
+		for (int i = 0; i < defaultedList.size(); ++i) {
+			ItemStack stack = inventory.getStack(i);
+			ItemStack remainder = RecipeRemainderLogicHandler.getRemainder(stack, recipe);
+
+			if (!remainder.isEmpty()) {
+				defaultedList.set(i, remainder);
+			}
+		}
+
+		return defaultedList;
+	}
+}

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/api/package-info.java

@@ -1,12 +1,14 @@
 /**
  * <h2>The Quilt Item Settings API.</h2>
- *
  * <p>
  * <h3>What are {@link net.minecraft.item.Item.Settings}?</h3>
  * {@link net.minecraft.item.Item.Settings} are ways to add specific traits to {@link net.minecraft.item.Item}s without creating a subclass.
  * In addition, these traits are applicable to all {@link net.minecraft.item.Item}s, not just a specific subclass.
  * <p>
- * This API adds two new settings for items, {@link org.quiltmc.qsl.item.setting.api.QuiltCustomItemSettings#CUSTOM_DAMAGE_HANDLER} and {@link org.quiltmc.qsl.item.setting.api.QuiltCustomItemSettings#EQUIPMENT_SLOT_PROVIDER}.
+ * This API adds three new settings for items,
+ * {@link org.quiltmc.qsl.item.setting.api.QuiltItemSettings#customDamage(org.quiltmc.qsl.item.setting.api.CustomDamageHandler)},
+ * {@link org.quiltmc.qsl.item.setting.api.QuiltItemSettings#equipmentSlot(org.quiltmc.qsl.item.setting.api.EquipmentSlotProvider)}, and
+ * {@link org.quiltmc.qsl.item.setting.api.QuiltItemSettings#recipeRemainder(org.quiltmc.qsl.item.setting.api.RecipeRemainderProvider)}.
  * <p>
  * These custom settings make use of the {@link org.quiltmc.qsl.item.setting.api.CustomItemSetting} API provided.
  * This API allows mods to specify their own custom settings in an API.

library/item/item_setting/src/main/java/org/quiltmc/qsl/item/setting/impl/CustomItemSettingImpl.java

@@ -25,16 +25,33 @@
 import java.util.WeakHashMap;
 import java.util.function.Supplier;
 
+import org.jetbrains.annotations.ApiStatus;
+
 import net.minecraft.item.Item;
+import net.minecraft.item.ItemStack;
 
 import org.quiltmc.qsl.item.setting.api.CustomDamageHandler;
 import org.quiltmc.qsl.item.setting.api.CustomItemSetting;
 import org.quiltmc.qsl.item.setting.api.EquipmentSlotProvider;
+import org.quiltmc.qsl.item.setting.api.RecipeRemainderProvider;
 
+@ApiStatus.Internal
 public class CustomItemSettingImpl<T> implements CustomItemSetting<T> {
 	public static final CustomItemSetting<EquipmentSlotProvider> EQUIPMENT_SLOT_PROVIDER = CustomItemSetting.create(() -> null);
 	public static final CustomItemSetting<CustomDamageHandler> CUSTOM_DAMAGE_HANDLER = CustomItemSetting.create(() -> null);
 
+	@SuppressWarnings("ConstantConditions")
+	public static final CustomItemSetting<RecipeRemainderProvider> RECIPE_REMAINDER_PROVIDER = new CustomItemSettingImpl<>(() -> (original, recipe) -> original.getItem().hasRecipeRemainder() ? original.getItem().getRecipeRemainder().getDefaultStack() : ItemStack.EMPTY) {
+		@Override
+		public void apply(Item.Settings settings, Item item) {
+			if (item.hasRecipeRemainder()) {
+				throw new IllegalArgumentException("Item cannot have a standard recipe remainder and a custom recipe remainder");
+			}
+
+			super.apply(settings, item);
+		}
+	};
+
 	private static final Map<Item.Settings, Collection<CustomItemSettingImpl<?>>> CUSTOM_SETTINGS = new WeakHashMap<>();
 
 	private final Map<Item.Settings, T> customSettings = new WeakHashMap<>();