Recipe Remainder API

library/item/item_setting/build.gradle

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

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

@@ -19,6 +19,7 @@
 import java.util.function.Supplier;
 
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
 
 import net.minecraft.item.Item;
 

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

@@ -22,8 +22,7 @@
  * 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
@@ -33,4 +32,18 @@ private QuiltCustomItemSettings() {
 	 * 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;
@@ -39,6 +41,7 @@ public class QuiltItemSettings extends Item.Settings {
 	 * @param equipmentSlotProvider the {@link EquipmentSlotProvider}
 	 * @return this
 	 */
+	@Contract("_->this")
 	public QuiltItemSettings equipmentSlot(EquipmentSlotProvider equipmentSlotProvider) {
 		return this.customSetting(QuiltCustomItemSettings.EQUIPMENT_SLOT_PROVIDER, equipmentSlotProvider);
 	}
@@ -49,6 +52,7 @@ public QuiltItemSettings equipmentSlot(EquipmentSlotProvider equipmentSlotProvid
 	 * @param equipmentSlot the {@link EquipmentSlot}
 	 * @return this
 	 */
+	@Contract("_->this")
 	public QuiltItemSettings equipmentSlot(EquipmentSlot equipmentSlot) {
 		return this.customSetting(QuiltCustomItemSettings.EQUIPMENT_SLOT_PROVIDER, itemStack -> equipmentSlot);
 	}
@@ -61,17 +65,72 @@ public QuiltItemSettings equipmentSlot(EquipmentSlot equipmentSlot) {
 	 * @return this
 	 * @see CustomDamageHandler
 	 */
+	@Contract("_->this")
 	public QuiltItemSettings customDamage(CustomDamageHandler handler) {
 		return this.customSetting(QuiltCustomItemSettings.CUSTOM_DAMAGE_HANDLER, handler);
 	}
 
+	/**
+	 * Sets the stack-aware recipe remainder provider of the item.
+	 */
+	@Contract("_->this")
+	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.
+	 */
+	@Contract("->this")
+	public QuiltItemSettings damageIfUsedInCrafting() {
+		return this.damageIfUsedInCrafting(1);
+	}
+
+	/**
+	 * Sets the stack-aware recipe remainder to return the item itself.
+	 */
+	@Contract("->this")
+	public QuiltItemSettings returnSelfInCrafting() {
+		return this.damageIfUsedInCrafting(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
+	 */
+	@Contract("_->this")
+	public QuiltItemSettings damageIfUsedInCrafting(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.
 	 *
 	 * @param setting the unique type for this setting
 	 * @param value   the object containing the setting itself
 	 * @return this builder
 	 */
+	@Contract("_, _->this")
 	public <T> QuiltItemSettings customSetting(CustomItemSetting<T> setting, T value) {
 		if (!(setting instanceof CustomItemSettingImpl)) {
 			throw new UnsupportedOperationException("CustomItemSetting should not be custom class " + setting.getClass().getSimpleName());
@@ -84,48 +143,56 @@ 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;
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings maxCount(int maxCount) {
 		super.maxCount(maxCount);
 		return this;
 	}
 
 	@Override
+	@Contract("_->this")
 	public QuiltItemSettings maxDamageIfAbsent(int maxDamage) {
 		super.maxDamageIfAbsent(maxDamage);
 		return this;
 	}
 
 	@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/RecipeRemainderProvider.java

@@ -0,0 +1,62 @@
+/*
+ * 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;
+
+import org.quiltmc.qsl.item.setting.impl.CustomItemSettingImpl;
+
+/**
+ * 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)}.</p>
+ */
+@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 = CustomItemSettingImpl.RECIPE_REMAINDER_PROVIDER.get(stack.getItem()).getRecipeRemainder(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

@@ -6,7 +6,10 @@
  * {@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

@@ -26,15 +26,28 @@
 import java.util.function.Supplier;
 
 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;
 
 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<>();

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

@@ -0,0 +1,70 @@
+/*
+ * 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.impl;
+
+import net.minecraft.entity.player.PlayerEntity;
+import net.minecraft.item.ItemStack;
+import net.minecraft.recipe.Recipe;
+import net.minecraft.util.ItemScatterer;
+import net.minecraft.util.collection.DefaultedList;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.world.World;
+
+public class RecipeRemainderLogicHandler {
+	private static boolean tryReturnItemToInventory(ItemStack remainder, DefaultedList<ItemStack> inventory, int slot) {
+		ItemStack leftovers = inventory.get(slot);
+		if (leftovers.isEmpty()) {
+			inventory.set(slot, remainder);
+			return false;
+		} else if (ItemStack.canCombine(remainder, leftovers)) {
+			int toTake = Math.min(leftovers.getMaxCount() - leftovers.getCount(), remainder.getCount());
+			remainder.decrement(toTake);
+			leftovers.increment(toTake);
+			return !remainder.isEmpty();
+		}
+		return true;
+	}
+
+	public static ItemStack getRemainder(ItemStack usedItem, Recipe<?> recipe) {
+		ItemStack remainder = CustomItemSettingImpl.RECIPE_REMAINDER_PROVIDER.get(usedItem.getItem()).getRecipeRemainder(
+				usedItem,
+				recipe
+		);
+
+		return remainder.isEmpty() ? ItemStack.EMPTY : remainder;
+	}
+
+	public static void handleRemainderForNonPlayerCraft(ItemStack remainder, DefaultedList<ItemStack> inventory, int slot, World world, BlockPos location) {
+		if (remainder.isEmpty()) {
+			return;
+		}
+
+		if (tryReturnItemToInventory(remainder, inventory, slot)) {
+			ItemScatterer.spawn(world, location.getX(), location.getY(), location.getZ(), remainder);
+		}
+	}
+
+	public static void handleRemainderForPlayerCraft(ItemStack remainder, DefaultedList<ItemStack> inventory, int slot, PlayerEntity player) {
+		if (remainder.isEmpty()) {
+			return;
+		}
+
+		if (tryReturnItemToInventory(remainder, inventory, slot)) {
+			player.getInventory().offerOrDrop(remainder);
+		}
+	}
+}