Package net.neoforged.neoforge.capabilities

Class BlockCapability<T,C>

java.lang.Object

net.neoforged.neoforge.capabilities.BaseCapability<T,C>

net.neoforged.neoforge.capabilities.BlockCapability<T,C>

Type Parameters:

T - type of queried objects

C - type of the additional context

public final class BlockCapability<T,C>
extends BaseCapability<T,C>

A BlockCapability gives flexible access to objects of type T located in the world.

Querying a block capability

To get an object of type T, use ILevelExtension.getCapability(BlockCapability, BlockPos, Object). For example, to query an item handler in the world, from a specific side:

 Level level = ...;
 BlockPos pos = ...;
 Direction side = ...;

 IItemHandler maybeHandler = level.getCapability(Capabilities.ItemHandler.BLOCK, pos, side);
 if (maybeHandler != null) {
     // Use maybeHandler
 }
 

For repeated queries at a specific position, use BlockCapabilityCache to improve performance.

Providing a capability for a block entity

To provide objects of type T, register providers to RegisterCapabilitiesEvent. For example:

 modBus.addListener(RegisterCapabilitiesEvent.class, event -> {
     event.registerBlockEntity(
         Capabilities.ItemHandler.BLOCK, // capability to register for
         MY_BLOCK_ENTITY_TYPE,
         (myBlockEntity, side) -> <return the IItemHandler for myBlockEntity and side>);
 });
 

If a previously returned capability is not valid anymore, or if a new capability is available, ILevelExtension.invalidateCapabilities(BlockPos) MUST be called to notify the caches (see below).

Providing a capability for a plain block

For blocks without a block entity, we use registerBlock instead:

 modBus.addListener(RegisterCapabilitiesEvent.class, event -> {
     event.registerBlock(
         Capabilities.ItemHandler.BLOCK, // capability to register for
         (level, pos, state, be, side) -> <return the IItemHandler>,
         // blocks to register for
         MY_ITEM_HANDLER_BLOCK, MY_OTHER_ITEM_HANDLER_BLOCK);
 });
 

Plain blocks must invalidate their capabilities whenever they change, including on placement and removal. For example:

 public class MyBlock extends Block {
     ＠Override
     public void onPlace(BlockState state, Level level, BlockPos pos, BlockState oldState, boolean movedByPiston) {
         // Invalidate capabilities on block placement or block state change
         level.invalidateCapabilities(pos);
     }

     ＠Override
     public void onRemove(BlockState state, Level level, BlockPos pos, BlockState newState, boolean movedByPiston) {
         super.onRemove(state, level, pos, newState, movedByPiston);
         // Invalidate capabilities on block removal or block state change
         level.invalidateCapabilities(pos);
     }
 }
 

Field Summary

Fields

Modifier and Type	Field	Description
(package private) final Map<Block,List<IBlockCapabilityProvider<T,C>>>	providers
private static final CapabilityRegistry<BlockCapability<?,?>>	registry

Constructor Summary

Constructors

Modifier	Constructor	Description
private	BlockCapability(ResourceLocation name, Class<T> typeClass, Class<C> contextClass)

Method Summary

Modifier and Type	Method	Description
static <T, C> BlockCapability<T,C>	create(ResourceLocation name, Class<T> typeClass, Class<C> contextClass)	Creates a new block capability, or gets it if it already exists.
static <T> BlockCapability<T,@Nullable Direction>	createSided(ResourceLocation name, Class<T> typeClass)	Creates a new block capability with nullable Direction context, or gets it if it already exists.
static <T> BlockCapability<T,Void>	createVoid(ResourceLocation name, Class<T> typeClass)	Creates a new block capability with Void context, or gets it if it already exists.
static List<BlockCapability<?,?>>	getAll()	Returns a new immutable copy of all the currently known block capabilities.
T	getCapability(Level level, BlockPos pos, @Nullable BlockState state, @Nullable BlockEntity blockEntity, C context)

Methods inherited from class net.neoforged.neoforge.capabilities.BaseCapability

contextClass, name, typeClass

Methods inherited from class java.lang.Object

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

Field Details

registry

private static final CapabilityRegistry<BlockCapability<?,?>> registry

providers

final Map<Block,List<IBlockCapabilityProvider<T,C>>> providers

Constructor Details

BlockCapability

private BlockCapability(ResourceLocation name,
 Class<T> typeClass,
 Class<C> contextClass)

Method Details

create

public static <T,
C> BlockCapability<T,C> create(ResourceLocation name,
 Class<T> typeClass,
 Class<C> contextClass)

Creates a new block capability, or gets it if it already exists.

Parameters:

name - name of the capability

typeClass - type of the queried API

contextClass - type of the additional context

createVoid

public static <T> BlockCapability<T,Void> createVoid(ResourceLocation name,
 Class<T> typeClass)

Creates a new block capability with Void context, or gets it if it already exists. This should be used for capabilities that do not require any additional context.

See Also:

• create(ResourceLocation, Class, Class)

createSided

public static <T>
BlockCapability<T,@Nullable Direction> createSided(ResourceLocation name,
 Class<T> typeClass)

Creates a new block capability with nullable Direction context, or gets it if it already exists.

getAll

public static List<BlockCapability<?,?>> getAll()

Returns a new immutable copy of all the currently known block capabilities.

Returns:

a new immutable copy of all the currently known block capabilities

getCapability

@Internal
@Nullable
public T getCapability(Level level,
 BlockPos pos,
 @Nullable
 @Nullable BlockState state,
 @Nullable
 @Nullable BlockEntity blockEntity,
 C context)