Package net.fabricmc.fabric.api.transfer.v1.fluid

Class FluidStorage

java.lang.Object

net.fabricmc.fabric.api.transfer.v1.fluid.FluidStorage

@Experimental
public final class FluidStorage
extends Object

Access to Storage<FluidVariant> instances.

Experimental feature, we reserve the right to remove or change it without further notice. The transfer API is a complex addition, and we want to be able to correct possible design mistakes.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	FluidStorage.CombinedItemApiProvider

Field Summary

Fields

Modifier and Type	Field	Description
static final Event<FluidStorage.CombinedItemApiProvider>	GENERAL_COMBINED_PROVIDER	Allows multiple API providers to return Storage<FluidVariant> implementations for some items.
static final ItemApiLookup<Storage<FluidVariant>,ContainerItemContext>	ITEM	Item access to fluid variant storages.
static final BlockApiLookup<Storage<FluidVariant>,Direction>	SIDED	Sided block access to fluid variant storages.

Method Summary

Modifier and Type	Method	Description
static Event<FluidStorage.CombinedItemApiProvider>	combinedItemApiProvider(Item item)	Get or create and register a FluidStorage.CombinedItemApiProvider event for the passed item.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SIDED

public static final BlockApiLookup<Storage<FluidVariant>,Direction> SIDED

Sided block access to fluid variant storages. Fluid amounts are always expressed in droplets. The Direction parameter may never be null. Refer to BlockApiLookup for documentation on how to use this field.

A simple way to expose fluid variant storages for a block entity hierarchy is to extend SidedStorageBlockEntity.

When the operations supported by a storage change, that is if the return value of Storage.supportsInsertion() or Storage.supportsExtraction() changes, the storage should notify its neighbors with a block update so that they can refresh their connections if necessary.

This may be queried safely both on the logical server and on the logical client threads. On the server thread (i.e. with a server world), all transfer functionality is always supported. On the client thread (i.e. with a client world), contents of queried Storages are unreliable and should not be modified.

ITEM

public static final ItemApiLookup<Storage<FluidVariant>,ContainerItemContext> ITEM

Item access to fluid variant storages. Querying should happen through ContainerItemContext.find(net.fabricmc.fabric.api.lookup.v1.item.ItemApiLookup<A, net.fabricmc.fabric.api.transfer.v1.context.ContainerItemContext>).

Fluid amounts are always expressed in droplets. By default, Fabric API only registers storage support for buckets that have a 1:1 mapping to their fluid, and for water potions.

combinedItemApiProvider(net.minecraft.item.Item) and GENERAL_COMBINED_PROVIDER should be used for API provider registration when multiple mods may want to offer a storage for the same item.

Base implementations are provided: EmptyItemFluidStorage and FullItemFluidStorage.

This may be queried both client-side and server-side. Returned APIs should behave the same regardless of the logical side.

GENERAL_COMBINED_PROVIDER

public static final Event<FluidStorage.CombinedItemApiProvider> GENERAL_COMBINED_PROVIDER

Allows multiple API providers to return Storage<FluidVariant> implementations for some items. combinedItemApiProvider(net.minecraft.item.Item) is per-item while this one is queried for all items, hence the "general" name.

Implementation note: This event is invoked both through an API Lookup fallback, and by the combinedItemApiProvider events. This means that per-item combined providers registered through combinedItemApiProvider DO NOT prevent these general providers from running, however regular providers registered through ItemApiLookup#register... that return a non-null API instance DO prevent it.

Method Details

combinedItemApiProvider

public static Event<FluidStorage.CombinedItemApiProvider> combinedItemApiProvider(Item item)

Get or create and register a FluidStorage.CombinedItemApiProvider event for the passed item. Allows multiple API providers to provide a Storage<FluidVariant> implementation for the same item.

When the item is queried for an API through ITEM, all the providers registered through the event will be invoked. All non-null Storage<FluidVariant> instances returned by the providers will be combined in a single storage, that will be the final result of the query, or null if no storage is offered by the event handlers.

This is appropriate to use when multiple mods could wish to expose the Fluid API for some items, for example when dealing with items added by the base Minecraft game such as buckets or empty bottles. A typical usage example is a mod adding support for filling empty bottles with a honey fluid: Fabric API already registers a storage for empty bottles to allow filling them with water through the event, and a mod can register an event handler that will attach a second storage allowing empty bottles to be filled with its honey fluid.

Throws:

IllegalStateException - If an incompatible provider is already registered for the item.