Package net.neoforged.neoforge.transfer.energy

Interface EnergyHandler

All Known Implementing Classes:
DelegatingEnergyHandler, EmptyEnergyHandler, InfiniteEnergyHandler, ItemAccessEnergyHandler, LimitingEnergyHandler, SimpleEnergyHandler, VoidingEnergyHandler
public interface EnergyHandler
A handler for the transfer and storage of energy.

This capability interface is used for NeoForge's energy system, see the exposed capabilities in

invalid reference 
Capabilities.EnergyHandler
.

This interface can be also be used for other energy systems, provided that they register a capability under a different name.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    extract(int amount, TransactionContext transaction)
    Extracts up to the given amount of energy from the handler.
    default int
    getAmountAsInt()
    Returns the amount of energy currently stored, as an int.
    long
    getAmountAsLong()
    Returns the amount of energy currently stored, as a long.
    default int
    getCapacityAsInt()
    Returns the capacity of the handler, irrespective of the current amount, as an int.
    long
    getCapacityAsLong()
    Returns the capacity of the handler, irrespective of the current amount, as a long.
    int
    insert(int amount, TransactionContext transaction)
    Inserts up to the given amount of energy into the handler.

  • Method Details

    • getAmountAsLong

      long getAmountAsLong()
      Returns the amount of energy currently stored, as a long.

      In general, energy 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.

      Returns:
      the amount as a long
      See Also:

    • getAmountAsInt

      @NonExtendable default int getAmountAsInt()
      Returns the amount of energy currently stored, 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.

      Returns:
      the amount as an int
      See Also:

    • getCapacityAsLong

      long getCapacityAsLong()
      Returns the capacity of the handler, irrespective of the current amount, as a long.

      In general, energy 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 energy 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.

      Returns:
      the capacity, as a long
      See Also:

    • getCapacityAsInt

      @NonExtendable default int getCapacityAsInt()
      Returns the capacity of the handler, irrespective of the current amount, 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 energy 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.

      Returns:
      the capacity, as an int
      See Also:

    • insert

      int insert(int amount, TransactionContext transaction)
      Inserts up to the given amount of energy into the handler.

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

      Parameters:
      amount - The maximum amount of energy 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 amount is negative. See also TransferPreconditions.checkNonNegative(int) to help perform this check.

    • extract

      int extract(int amount, TransactionContext transaction)
      Extracts up to the given amount of energy from the handler.

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

      Parameters:
      amount - The maximum amount of energy 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 amount is negative. See also TransferPreconditions.checkNonNegative(int) to help perform this check.