Package net.neoforged.neoforge.capabilities

Class BlockCapabilityCache<T,C>

java.lang.Object
net.neoforged.neoforge.capabilities.BlockCapabilityCache<T,C>
public final class BlockCapabilityCache<T,C> extends Object
A cache for block capabilities, to be used to track capabilities at a specific position, with a specific context.

The cache is invalidated when the level is notified of a change via ILevelExtension.invalidateCapabilities(BlockPos).

Instances are automatically cleared by the garbage collector when they are no longer in use.

  • Field Details

    • capability

      private final BlockCapability<T,C> capability

    • level

      private final ServerLevel level

    • pos

      private final BlockPos pos

    • context

      private final C context

    • cacheValid

      private boolean cacheValid
      true if notifications received by the cache will be forwarded to listener. By default and after each invalidation, this is set to false. Calling getCapability() sets it to true.

    • cachedCap

      @Nullable private T cachedCap

    • canQuery

      private boolean canQuery

    • listener

      private final ICapabilityInvalidationListener listener

  • Constructor Details

  • Method Details

    • create

      public static <T, C> BlockCapabilityCache<T,C> create(BlockCapability<T,C> capability, ServerLevel level, BlockPos pos, C context)
      Creates a new cache instance and registers it to the level.
      Parameters:
      capability - the capability
      level - the level
      pos - the position
      context - extra context for the query

    • create

      public static <T, C> BlockCapabilityCache<T,C> create(BlockCapability<T,C> capability, ServerLevel level, BlockPos pos, C context, BooleanSupplier isValid, Runnable invalidationListener)
      Creates a new cache instance with an invalidation listener, and registers it to the level.

      A few details regarding the system:

      • Calling getCapability() from the invalidation listener is not supported, as the block being invalidated might not be ready to be queried again yet. If you receive an invalidation notification, you should wait for some time (e.g. until your own tick) before checking getCapability() again.
      • In general, do not perform any level access for the listener. The listener itself might be in a chunk that is being unloaded, for example.
      • The listener does not receive notifications before getCapability() is called. After each invalidation, getCapability() must be called again to enable further notifications.
      Parameters:
      capability - the capability
      level - the level
      pos - the position
      context - extra context for the query
      isValid - a function to check if the listener still wants to receive notifications. A typical example would be () -> !this.isRemoved() for a block entity that should not receive invalidation notifications anymore once it is removed.
      invalidationListener - the invalidation listener. Will be called whenever the capability of the cache might have changed.

    • level

      public ServerLevel level()

    • pos

      public BlockPos pos()

    • context

      public C context()

    • getCapability

      @Nullable public T getCapability()
      Gets the capability instance, or null if the capability is not present.

      If the target position is not loaded, this method will return null.