Package net.neoforged.neoforge.capabilities

Class BlockCapability<T,C extends @Nullable Object>

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 @Nullable Object> 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 Details

  • Constructor Details

    • BlockCapability

      private BlockCapability(net.minecraft.resources.ResourceLocation name, Class<T> typeClass, Class<C> contextClass)

  • Method Details

    • create

      public static <T, C extends @Nullable Object> BlockCapability<T,C> create(net.minecraft.resources.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,@Nullable Void> createVoid(net.minecraft.resources.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:

    • createSided

      public static <T> BlockCapability<T,@Nullable net.minecraft.core.Direction> createSided(net.minecraft.resources.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.

      Mods that want to forward "all" capability requests should likely use getAllProxyable() instead.

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

    • getAllProxyable

      public static List<BlockCapability<?,?>> getAllProxyable()
      Returns a new immutable copy of all the currently known proxyable block capabilities.

      This method should typically only be used in the EventPriority.LOW or EventPriority.LOWEST phase of RegisterCapabilitiesEvent, or later, to ensure that all proxyable capabilities have been marked as such.

      Returns:
      a new immutable copy of all the currently known proxyable block capabilities
      See Also:

    • isProxyable

      public boolean isProxyable()
      Returns whether this capability is proxyable. This information is metadata: it does not change how the capability works internally, but it tells mods whether they should or should not register proxying capability providers.

      If the capability is proxyable, requests for this capability are safe to forward unilaterally to other blocks.

      If the capability is not proxyable, requests for this capability should not be forwarded to other blocks without further information. In that case, refer to documentation of the capability to understand under which circumstances it is safe to forward, if at all. For this reason, mods that forward "all" capabilities should not forward non-proxyable capabilities.

      Block capabilities are not proxyable by default. Any call to RegisterCapabilitiesEvent.setProxyable(BlockCapability) will mark the capability as proxyable. Any call to RegisterCapabilitiesEvent.setNonProxyable(BlockCapability) will mark the capability as non-proxyable, and prevent it from being marked as proxyable.

    • setProxyable

      void setProxyable(boolean proxyable)

    • getCapability

      @Internal @Nullable public T getCapability(net.minecraft.world.level.Level level, net.minecraft.core.BlockPos pos, @Nullable @Nullable net.minecraft.world.level.block.state.BlockState state, @Nullable @Nullable net.minecraft.world.level.block.entity.BlockEntity blockEntity, C context)