Package net.neoforged.neoforge.transfer

Interface ResourceHandler<T extends Resource>

Type Parameters:
T - The type of resource this handler manages.
All Known Implementing Classes:
BucketResourceHandler, CarriedSlotWrapper, CauldronWrapper, CombinedResourceHandler, ComposterWrapper.Bottom, ComposterWrapper.Top, DelegatingResourceHandler, EmptyResourceHandler, FluidStacksResourceHandler, InfiniteResourceHandler, ItemAccessFluidHandler, ItemAccessItemHandler, ItemAccessResourceHandler, ItemStackResourceHandler, ItemStacksResourceHandler, LivingEntityEquipmentWrapper.EquipmentTypeWrapper, LivingEntityEquipmentWrapper.SlotWrapper, PlayerInventoryWrapper, PlayerInventoryWrapper.ArmorSlotWrapper, RangedResourceHandler, ResourceStacksResourceHandler, StacksResourceHandler, VanillaContainerWrapper, VanillaContainerWrapper.SlotWrapper, VoidingResourceHandler, WorldlyContainerWrapper
public interface ResourceHandler<T extends Resource>
A generic handler for the transfer and storage of resources whether it be inserting, extracting, querying some value, etc.

Indices

A resource handler is organized into indices, which are addressed using an int between 0 and size() - 1.

An index represents a "slot", "tank", "buffer", depending on the type of resource.

Out-of-bounds access using methods that accept an index will usually throw an exception, so only indices between 0 (included) and the size (excluded) should be used. If a storage has a dynamic size, it should be lenient to accommodate for callers holding onto a previously returned size.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T extends Resource>
    Class<ResourceHandler<T>>
    asClass()
    Creates a class with the right generic type, such that it can be used to register a capability.
    int
    extract(int index, T resource, int amount, TransactionContext transaction)
    Extracts up to the given amount of a resource from the handler at the given index.
    default int
    extract(T resource, int amount, TransactionContext transaction)
    Tries to extract up to the given amount of a resource from the handler.
    default int
    getAmountAsInt(int index)
    Returns the amount of the currently stored resource at the given index, as an int.
    long
    getAmountAsLong(int index)
    Returns the amount of the currently stored resource at the given index, as a long.
    default int
    getCapacityAsInt(int index, T resource)
    Returns the capacity of the handler at the given index and for the given resource, irrespective of the current amount or resource currently at that index, as an int.
    long
    getCapacityAsLong(int index, T resource)
    Returns the capacity of the handler at the given index and for the given resource, irrespective of the current amount or resource currently at that index, as a long.
    T
    getResource(int index)
    Returns the resource at the given index, which may be empty.
    int
    insert(int index, T resource, int amount, TransactionContext transaction)
    Inserts up to the given amount of a resource into the handler at the given index.
    default int
    insert(T resource, int amount, TransactionContext transaction)
    Inserts up to the given amount of a resource into the handler.
    boolean
    isValid(int index, T resource)
    Returns whether the given resource is generally allowed to be contained at the given index, irrespective of the current amount or resource currently at that index.
    int
    size()
    Returns the current number of indices in this resource handler.

  • Method Details

    • size

      int size()
      Returns the current number of indices in this resource handler.

      This size provides a bound on the valid indices for this handler, see the documentation of ResourceHandler.

      Returns:
      The size of the resource handler. Can be 0 if the handler currently has no indices.

    • getResource

      T getResource(int index)
      Returns the resource at the given index, which may be empty.

      If the resource is empty, the stored amount must be 0.

      Parameters:
      index - The index to get the resource from.
      Returns:
      the resource at the given index, which may be empty

    • getAmountAsLong

      long getAmountAsLong(int index)
      Returns the amount of the currently stored resource at the given index, as a long.

      In general, resource handlers can report long amounts. However, if the handler is known to only support amounts up to Integer.MAX_VALUE, or if the caller prefers to deal in ints only, the int-returning overload can be used instead.

      The returned amount must be non-negative. If the stored resource is empty, the amount must be 0.

      Parameters:
      index - The index to get the amount from.
      Returns:
      the amount at the given index, as a long
      See Also:

    • getAmountAsInt

      @NonExtendable default int getAmountAsInt(int index)
      Returns the amount of the currently stored resource at the given index, as an int.

      This is a convenience method to clamp the amount to an int, for the cases where the handler is known to only support amounts up to Integer.MAX_VALUE, or if the caller prefers to deal in ints only.

      The returned amount must be non-negative. If the stored resource is empty, the amount must be 0.

      Parameters:
      index - The index to get the amount from.
      Returns:
      the amount at the given index, as an int
      See Also:

    • getCapacityAsLong

      long getCapacityAsLong(int index, T resource)
      Returns the capacity of the handler at the given index and for the given resource, irrespective of the current amount or resource currently at that index, as a long.

      In general, resource handlers can report long capacities. However, if the handler is known to only support capacities up to Integer.MAX_VALUE, or if the caller prefers to deal in ints only, the int-returning overload can be used instead.

      This function serves as a hint on the maximum amount the resource handler might contain, for example the handler can be considered full if amount >= capacity. Note that the returned capacity may overestimate the actual allowed amount, and it might be smaller than the current amount. The only way to know if a handler will accept a resource, is to try to insert it.

      Parameters:
      index - The index to get the capacity for.
      resource - The resource to get the capacity for. May be empty to get the general capacity at the index.
      Returns:
      the capacity at the given index, as a long
      See Also:

    • getCapacityAsInt

      @NonExtendable default int getCapacityAsInt(int index, T resource)
      Returns the capacity of the handler at the given index and for the given resource, irrespective of the current amount or resource currently at that index, as an int.

      This is a convenience method to get the capacity clamped to an int, for the cases where the handler is known to only support capacities up to Integer.MAX_VALUE, or if the caller prefers to deal in ints only.

      This function serves as a hint on the maximum amount the resource handler might contain, for example the handler can be considered full if amount >= capacity. Note that the returned capacity may overestimate the actual allowed amount, and it might be smaller than the current amount. The only way to know if a handler will accept a resource, is to try to insert it.

      Parameters:
      index - The index to get the limit for.
      resource - The resource to get the limit for. May be empty to get the general capacity at the index.
      Returns:
      the capacity at the given index, as an int
      See Also:

    • isValid

      boolean isValid(int index, T resource)
      Returns whether the given resource is generally allowed to be contained at the given index, irrespective of the current amount or resource currently at that index.

      This function serves as a hint on whether the resource handler can contain the resource or not. The only way to know if a handler will accept a resource, is to try to insert it.

      Parameters:
      index - The index to check.
      resource - The resource to check. Must be non-empty.
      Returns:
      whether the given resource is generally allowed to be contained at the given index, irrespective of the current amount or resource currently at that index

    • insert

      int insert(int index, T resource, int amount, TransactionContext transaction)
      Inserts up to the given amount of a resource into the handler at the given index.

      Changes to the handler are made in the context of a transaction.

      Parameters:
      index - The index to insert the resource into.
      resource - The resource to insert. Must be non-empty.
      amount - The maximum amount of the resource to insert. Must be non-negative.
      transaction - The transaction that this operation is part of.
      Returns:
      The amount that was inserted. Between 0 (inclusive, nothing was inserted) and amount (inclusive, everything was inserted).
      Throws:
      IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.
      See Also:

    • insert

      default int insert(T resource, int amount, TransactionContext transaction)
      Inserts up to the given amount of a resource into the handler.

      This function is preferred to the index-specific overload since it lets the handler decide how to distribute the resource.

      This method is expected to be more efficient than callers trying to find a suitable index for insertion themselves.

      Changes to the handler are made in the context of a transaction.

      Parameters:
      resource - The resource to insert. Must be non-empty.
      amount - The maximum amount of the resource to insert. Must be non-negative.
      transaction - The transaction that this operation is part of.
      Returns:
      The amount that was inserted. Between 0 (inclusive, nothing was inserted) and amount (inclusive, everything was inserted).
      Throws:
      IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.
      See Also:

    • extract

      int extract(int index, T resource, int amount, TransactionContext transaction)
      Extracts up to the given amount of a resource from the handler at the given index.

      Changes to the handler are made in the context of a transaction.

      Parameters:
      index - The index to extract the resource from.
      resource - The resource to extract. Must be non-empty.
      amount - The maximum amount of the resource to extract. Must be non-negative.
      transaction - The transaction that this operation is part of.
      Returns:
      The amount that was extracted. Between 0 (inclusive, nothing was extracted) and amount (inclusive, everything was extracted).
      Throws:
      IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.
      See Also:

    • extract

      default int extract(T resource, int amount, TransactionContext transaction)
      Tries to extract up to the given amount of a resource from the handler.

      This function is preferred to the index-specific overload since it lets the handler decide how to find indices that contain the resource.

      This method is expected to be more efficient than callers trying to find indices that contain the resource themselves.

      Changes to the handler are made in the context of a transaction.

      Parameters:
      resource - The resource to extract. Must be non-empty.
      amount - The maximum amount of the resource to extract. Must be non-negative.
      transaction - The transaction that this operation is part of.
      Returns:
      The amount that was extracted. Between 0 (inclusive, nothing was extracted) and amount (inclusive, everything was extracted).
      Throws:
      IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.
      See Also:

    • asClass

      static <T extends Resource> Class<ResourceHandler<T>> asClass()
      Creates a class with the right generic type, such that it can be used to register a capability.