/* * Copyright (c) Forge Development LLC and contributors * SPDX-License-Identifier: LGPL-2.1-only */ package net.minecraftforge.items; import net.minecraft.world.Container; import net.minecraft.world.item.ItemStack; import net.minecraftforge.common.capabilities.AutoRegisterCapability; import net.minecraftforge.fluids.FluidStack; import net.minecraftforge.fluids.capability.IFluidHandler; import org.jetbrains.annotations.NotNull; @AutoRegisterCapability public interface IItemHandler { /** * Returns the number of slots available * * @return The number of slots available **/ int getSlots(); /** * Returns the ItemStack in a given slot. * * The result's stack size may be greater than the itemstack's max size. * * If the result is empty, then the slot is empty. * *

* IMPORTANT: This ItemStack MUST NOT be modified. This method is not for * altering an inventory's contents. Any implementers who are able to detect * modification through this method should throw an exception. *

*

* SERIOUSLY: DO NOT MODIFY THE RETURNED ITEMSTACK *

* * @param slot Slot to query * @return ItemStack in given slot. Empty Itemstack if the slot is empty. **/ @NotNull ItemStack getStackInSlot(int slot); /** *

* Inserts an ItemStack into the given slot and return the remainder. * The ItemStack should not be modified in this function! *

* Note: This behaviour is subtly different from {@link IFluidHandler#fill(FluidStack, IFluidHandler.FluidAction)} * * @param slot Slot to insert into. * @param stack ItemStack to insert. This must not be modified by the item handler. * @param simulate If true, the insertion is only simulated * @return The remaining ItemStack that was not inserted (if the entire stack is accepted, then return an empty ItemStack). * May be the same as the input ItemStack if unchanged, otherwise a new ItemStack. * The returned ItemStack can be safely modified after. **/ @NotNull ItemStack insertItem(int slot, @NotNull ItemStack stack, boolean simulate); /** * Extracts an ItemStack from the given slot. *

* The returned value must be empty if nothing is extracted, * otherwise its stack size must be less than or equal to {@code amount} and {@link ItemStack#getMaxStackSize()}. *

* * @param slot Slot to extract from. * @param amount Amount to extract (may be greater than the current stack's max limit) * @param simulate If true, the extraction is only simulated * @return ItemStack extracted from the slot, must be empty if nothing can be extracted. * The returned ItemStack can be safely modified after, so item handlers should return a new or copied stack. **/ @NotNull ItemStack extractItem(int slot, int amount, boolean simulate); /** * Retrieves the maximum stack size allowed to exist in the given slot. * * @param slot Slot to query. * @return The maximum stack size allowed in the slot. */ int getSlotLimit(int slot); /** *

* This function re-implements the vanilla function {@link Container#canPlaceItem(int, ItemStack)}. * It should be used instead of simulated insertions in cases where the contents and state of the inventory are * irrelevant, mainly for the purpose of automation and logic (for instance, testing if a minecart can wait * to deposit its items into a full inventory, or if the items in the minecart can never be placed into the * inventory and should move on). *

* * @param slot Slot to query for validity * @param stack Stack to test with for validity * * @return true if the slot can insert the ItemStack, not considering the current state of the inventory. * false if the slot can never insert the ItemStack in any situation. */ boolean isItemValid(int slot, @NotNull ItemStack stack); }