A
- The type of the API.C
- The type of the additional context object.@ApiStatus.NonExtendable
public interface BlockApiLookup<A,C>
get(net.minecraft.util.Identifier, java.lang.Class<A>, java.lang.Class<C>)
.
When trying to find(net.minecraft.world.World, net.minecraft.util.math.BlockPos, C)
an API, the block or block entity at that position will be queried if it exists.
If it doesn't exist, or if it returns null
, the fallback providers will be queried in order.
Note: If you are going to query APIs a lot, consider using BlockApiCache
, it may drastically improve performance.
public interface FluidContainer {
boolean containsFluids(); // return true if not empty
}
Let us first create a static BlockApiLookup
instance that will manage the registration and the query.
public final class MyApi {
public static final BlockApiLookup<FluidContainer, Direction> FLUID_CONTAINER = BlockApiLookup.get(new Identifier("mymod:fluid_container"), FluidContainer.class, Direction.class);
}
Using that, we can query instances of FluidContainer
:
FluidContainer container = MyApi.FLUID_CONTAINER.find(world, pos, direction);
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, functions that provide an API for a block or a block entity must be registered.
// If the block entity directly implements the interface, registerSelf can be used.
public class ContainerBlockEntity implements FluidContainer {
// ...
}
BlockEntityType<ContainerBlockEntity> CONTAINER_BLOCK_ENTITY_TYPE;
MyApi.FLUID_CONTAINER.registerSelf(CONTAINER_BLOCK_ENTITY_TYPE);
// For more complicated block entity logic, registerForBlockEntities can be used.
// For example, let's provide a stored field, and only when the direction is UP:
public class MyBlockEntity {
public final FluidContainer upContainer;
// ...
}
MyApi.FLUID_CONTAINER.registerForBlockEntities((blockEntity, direction) -> {
if (direction == Direction.UP) { // only expose from the top
// return a field
return ((MyBlockEntity) blockEntity).upContainer;
} else {
return null;
}
}, BLOCK_ENTITY_TYPE_1, BLOCK_ENTITY_TYPE_2);
// Without a block entity, registerForBlocks can be used.
MyApi.FLUID_CONTAINER.registerForBlocks((world, pos, state, blockEntity, direction) -> {
// return a FluidContainer for your block, or null if there is none
}, BLOCK_INSTANCE, ANOTHER_BLOCK_INSTANCE); // register as many blocks as you want
// Block entity fallback, for example to interface with another mod's FluidInventory.
MyApi.FLUID_CONTAINER.registerFallback((world, pos, state, blockEntity, direction) -> {
if (blockEntity instanceof FluidInventory) {
// return wrapper
}
return null;
});
// General fallback, to interface with anything, for example another BlockApiLookup.
MyApi.FLUID_CONTAINER.registerFallback((world, pos, state, blockEntity, direction) -> {
// return something if available, or null
});
BlockApiCache<A, C>
instead of directly querying the BlockApiLookup
.
// 1) create and store an instance
BlockApiCache<FluidContainer, Direction> cache = BlockApiCache.create(MyApi.FLUID_CONTAINER, serverWorld, pos);
// 2) use it later, the block entity instance will be cached among other things
FluidContainer container = cache.find(direction);
if (container != null) {
// ...
}
// 2bis) if the caller is able to cache the block state as well, for example by listening to neighbor updates,
// that will further improve performance.
FluidContainer container = cache.find(direction, cachedBlockState);
if (container != null) {
// ...
}
// no need to destroy the cache, the garbage collector will take care of it
FluidContainer
and Direction
were completely arbitrary in this example.
We can define any BlockApiLookup<A, C>
, where A
is the type of the queried API, and C
is the type of the additional context
(the direction parameter in the previous example).
If no context is necessary, Void
should be used, and null
instances should be passed.Modifier and Type | Interface and Description |
---|---|
static interface |
BlockApiLookup.BlockApiProvider<A,C> |
static interface |
BlockApiLookup.BlockEntityApiProvider<A,C> |
Modifier and Type | Method and Description |
---|---|
A |
find(net.minecraft.world.World world,
net.minecraft.util.math.BlockPos pos,
@Nullable net.minecraft.block.BlockState state,
@Nullable net.minecraft.block.entity.BlockEntity blockEntity,
C context)
Attempt to retrieve an API from a block in the world.
|
default A |
find(net.minecraft.world.World world,
net.minecraft.util.math.BlockPos pos,
C context)
Attempt to retrieve an API from a block in the world.
|
static <A,C> BlockApiLookup<A,C> |
get(net.minecraft.util.Identifier lookupId,
Class<A> apiClass,
Class<C> contextClass)
Retrieve the
BlockApiLookup associated with an identifier, or create it if it didn't exist yet. |
void |
registerFallback(BlockApiLookup.BlockApiProvider<A,C> fallbackProvider)
Expose the API for all queries: the provider will be invoked if no object was found using the block or block entity providers.
|
void |
registerForBlockEntities(BlockApiLookup.BlockEntityApiProvider<A,C> provider,
net.minecraft.block.entity.BlockEntityType<?>... blockEntityTypes)
Expose the API for instances of the passed block entity types.
|
void |
registerForBlocks(BlockApiLookup.BlockApiProvider<A,C> provider,
net.minecraft.block.Block... blocks)
Expose the API for the passed blocks.
|
void |
registerSelf(net.minecraft.block.entity.BlockEntityType<?>... blockEntityTypes)
Expose the API for the passed block entities directly implementing it.
|
static <A,C> BlockApiLookup<A,C> get(net.minecraft.util.Identifier lookupId, Class<A> apiClass, Class<C> contextClass)
BlockApiLookup
associated with an identifier, or create it if it didn't exist yet.lookupId
- The unique identifier of the lookup.apiClass
- The class of the API.contextClass
- The class of the additional context.IllegalArgumentException
- If another apiClass
or another contextClass
was already registered with the same identifier.@Nullable default A find(net.minecraft.world.World world, net.minecraft.util.math.BlockPos pos, C context)
BlockApiCache
if you are doing frequent queries at the same position.
Note: If the block state or the block entity is known, it is more efficient to use find(World, BlockPos, BlockState, BlockEntity, Object)
.
world
- The world.pos
- The position of the block.context
- Additional context for the query, defined by type parameter C.null
if no API was found.@Nullable A find(net.minecraft.world.World world, net.minecraft.util.math.BlockPos pos, @Nullable @Nullable net.minecraft.block.BlockState state, @Nullable @Nullable net.minecraft.block.entity.BlockEntity blockEntity, C context)
BlockApiCache
if you are doing frequent queries at the same position.world
- The world.pos
- The position of the block.context
- Additional context for the query, defined by type parameter C.state
- The block state at the target position, or null if unknown.blockEntity
- The block entity at the target position if it is known, or null if it is unknown or does not exist.null
if no API was found.void registerSelf(net.minecraft.block.entity.BlockEntityType<?>... blockEntityTypes)
Implementation note: this is checked at registration time by creating block entity instances using the passed types.
blockEntityTypes
- Block entity types for which to expose the API.IllegalArgumentException
- If the API class is not assignable from instances of the passed block entity types.void registerForBlocks(BlockApiLookup.BlockApiProvider<A,C> provider, net.minecraft.block.Block... blocks)
BlockApiLookup.BlockApiProvider
.provider
- The provider.blocks
- The blocks.void registerForBlockEntities(BlockApiLookup.BlockEntityApiProvider<A,C> provider, net.minecraft.block.entity.BlockEntityType<?>... blockEntityTypes)
BlockApiLookup.BlockEntityApiProvider
.provider
- The provider.blockEntityTypes
- The block entity types.void registerFallback(BlockApiLookup.BlockApiProvider<A,C> fallbackProvider)
fallbackProvider
- The fallback provider.