Package net.fabricmc.fabric.api.lookup.v1.item

Interface ItemApiLookup<A,C>

Type Parameters:

A - The type of the API.

C - The type of the additional context object.

@NonExtendable
public interface ItemApiLookup<A,C>

An object that allows retrieving APIs from item stacks. Instances of this interface can be obtained through get(net.minecraft.util.Identifier, java.lang.Class<A>, java.lang.Class<C>).

When trying to find(net.minecraft.item.ItemStack, C) an API for an item stack, the provider registered for the item of the stack will be queried if it exists. If it doesn't exist, or if it returns null, the fallback providers will be queried in order.

Usage Example

Let us reuse FluidContainer from the BlockApiLookup example. We will query FluidContainer instances from the stack directly. We need no context, so we will use Void.

 public interface FluidContainer {
     boolean containsFluids(); // return true if not empty
 }

We need to create the ItemApiLookup:

 public final class MyApi {
     public static final ItemApiLookup<FluidContainer, Void> FLUID_CONTAINER_ITEM = ItemApiLookup.get(new Identifier("mymod:fluid_container"), FluidContainer.class, Void.class);
 }

API instances are easy to access:

 FluidContainer container = MyApi.FLUID_CONTAINER_ITEM.find(itemStack, null); // Void is always null
 if (container != null) {
     // Do something with the container
     if (container.containsFluids()) {
         System.out.println("It contains fluids!");
     }
 }

For the query to return a useful result, we must expose the API:

 // If the item directly implements the interface, registerSelf can be used.
 public class InfiniteWaterItem implements FluidContainer {
     ＠Override
     public boolean containsFluids() {
         return true; // This item always contains fluids!
     }
 }
 MyApi.FLUID_CONTAINER_ITEM.registerSelf(INFINITE_WATER_ITEM);

 // Otherwise, registerForItems can be used.
 MyApi.FLUID_CONTAINER_ITEM.registerForItems((itemStack, ignored) -> {
     // return a FluidContainer for your item, or null if there is none
     // the second parameter is Void in this case, so it's always null and can be ignored
 }, ITEM_INSTANCE, ANOTHER_ITEM_INSTANCE); // register as many items as you want

 // General fallback, to interface with anything, for example another ItemApiLookup.
 MyApi.FLUID_CONTAINER_ITEM.registerFallback((itemStack, ignored) -> {
     // return something if available, or null
 });

Generic context types

Note that FluidContainer and Void were completely arbitrary in this example. We can define any ItemApiLookup<A, C>, where A is the type of the queried API, and C is the type of the additional context (the void parameter in the previous example). If no context is necessary, Void should be used, and null instances should be passed, like we did in the example.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ItemApiLookup.ItemApiProvider<A,C>

Method Summary

Modifier and Type	Method	Description
Class<A>	apiClass()	Return the API class of this lookup.
Class<C>	contextClass()	Return the context class of this lookup.
A	find(net.minecraft.item.ItemStack itemStack, C context)	Attempt to retrieve an API from an item stack.
static <A, C> ItemApiLookup<A,C>	get(net.minecraft.util.Identifier lookupId, Class<A> apiClass, Class<C> contextClass)	Retrieve the ItemApiLookup associated with an identifier, or create it if it didn't exist yet.
net.minecraft.util.Identifier	getId()	Return the identifier of this lookup.
@Nullable ItemApiLookup.ItemApiProvider<A,C>	getProvider(net.minecraft.item.Item item)	Return the provider for the passed item (registered with one of the register functions), or null if none was registered (yet).
void	registerFallback(ItemApiLookup.ItemApiProvider<A,C> fallbackProvider)	Expose the API for all queries: the fallbacks providers will be invoked if no object was found using the regular providers.
void	registerForItems(ItemApiLookup.ItemApiProvider<A,C> provider, net.minecraft.item.ItemConvertible... items)	Expose the API for the passed items.
void	registerSelf(net.minecraft.item.ItemConvertible... items)	Expose the API for the passed items directly implementing it.

Method Details

get

static <A,
C> ItemApiLookup<A,C> get(net.minecraft.util.Identifier lookupId,
 Class<A> apiClass,
 Class<C> contextClass)

Retrieve the ItemApiLookup associated with an identifier, or create it if it didn't exist yet.

Parameters:

lookupId - The unique identifier of the lookup.

apiClass - The class of the API.

contextClass - The class of the additional context.

Returns:

The unique lookup with the passed lookupId.

Throws:

IllegalArgumentException - If another apiClass or another contextClass was already registered with the same identifier.

find

@Nullable
A find(net.minecraft.item.ItemStack itemStack,
 C context)

Attempt to retrieve an API from an item stack.

Note: An API may or may not allow the item stack to be modified by the returned instance. API authors are strongly encouraged to document this behavior so that implementors can refer to the API documentation.
While providers may capture a reference to the stack, it is expected that they do not modify it directly.

Parameters:

itemStack - The item stack.

context - Additional context for the query, defined by type parameter C.

Returns:

The retrieved API, or null if no API was found.

registerSelf

void registerSelf(net.minecraft.item.ItemConvertible... items)

Expose the API for the passed items directly implementing it.

Parameters:

items - Items for which to expose the API.

Throws:

IllegalArgumentException - If the API class is not assignable from a class of one of the items.

registerForItems

void registerForItems(ItemApiLookup.ItemApiProvider<A,C> provider,
 net.minecraft.item.ItemConvertible... items)

Expose the API for the passed items. The mapping from the parameters of the query to the API is handled by the passed ItemApiLookup.ItemApiProvider.

Parameters:

provider - The provider.

items - The items.

registerFallback

void registerFallback(ItemApiLookup.ItemApiProvider<A,C> fallbackProvider)

Expose the API for all queries: the fallbacks providers will be invoked if no object was found using the regular providers.

Parameters:

fallbackProvider - The fallback provider.

getId

net.minecraft.util.Identifier getId()

Return the identifier of this lookup.

apiClass

Class<A> apiClass()

Return the API class of this lookup.

contextClass

Class<C> contextClass()

Return the context class of this lookup.

getProvider

@Nullable
@Nullable ItemApiLookup.ItemApiProvider<A,C> getProvider(net.minecraft.item.Item item)

Return the provider for the passed item (registered with one of the register functions), or null if none was registered (yet). Queries should go through find(net.minecraft.item.ItemStack, C), only use this to inspect registered providers!