Package net.neoforged.neoforge.event.entity.player

Class UseItemOnBlockEvent

java.lang.Object
net.neoforged.bus.api.Event
net.neoforged.neoforge.event.entity.player.UseItemOnBlockEvent
All Implemented Interfaces:
net.neoforged.bus.api.ICancellableEvent
public class UseItemOnBlockEvent extends net.neoforged.bus.api.Event implements net.neoforged.bus.api.ICancellableEvent
Fires on both the client and server thread when a player interacts with a block.

The event fires in three phases, corresponding with the three interaction behaviors: IItemExtension.onItemUseFirst(net.minecraft.world.item.ItemStack, net.minecraft.world.item.context.UseOnContext), BlockBehaviour.useItemOn(net.minecraft.world.item.ItemStack, net.minecraft.world.level.block.state.BlockState, net.minecraft.world.level.Level, net.minecraft.core.BlockPos, net.minecraft.world.entity.player.Player, net.minecraft.world.InteractionHand, net.minecraft.world.phys.BlockHitResult), and Item.useOn(net.minecraft.world.item.context.UseOnContext).

The event fires after the interaction logic decides to run the particular interaction behavior, as opposed to PlayerInteractEvent.RightClickBlock which fires once-per-right-click, before the behavior-choosing logic.

If the event is cancelled via cancelWithResult(net.minecraft.world.InteractionResult), then the normal interaction behavior for that phase will not run, and the specified InteractionResult will be returned instead.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    UseItemOnBlockEvent.UsePhase
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private net.minecraft.world.InteractionResult
    cancellationResult
     
    private final net.minecraft.world.item.context.UseOnContext
    context
     
    private final @Nullable net.minecraft.core.Direction
    face
     
    private final net.minecraft.world.InteractionHand
    hand
     
    private final net.minecraft.world.item.ItemStack
    heldItem
     
    private final net.minecraft.world.level.Level
    level
     
    private final @Nullable net.minecraft.world.entity.player.Player
    player
     
    private final net.minecraft.core.BlockPos
    pos
     
    private final UseItemOnBlockEvent.UsePhase
    usePhase
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    UseItemOnBlockEvent(net.minecraft.world.item.context.UseOnContext context, UseItemOnBlockEvent.UsePhase usePhase)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelWithResult(net.minecraft.world.InteractionResult result)
    Cancels the use interaction (preventing the block or item's use behavior from running) and provides the specified result to the interaction logic instead.
    net.minecraft.world.InteractionResult
    getCancellationResult()
     
    @Nullable net.minecraft.core.Direction
    getFace()
     
    net.minecraft.world.InteractionHand
    getHand()
     
    net.minecraft.world.item.ItemStack
    getItemStack()
     
    net.minecraft.world.level.Level
    getLevel()
     
    @Nullable net.minecraft.world.entity.player.Player
    getPlayer()
     
    net.minecraft.core.BlockPos
    getPos()
    If the interaction was on an entity, will be a BlockPos centered on the entity.
    net.neoforged.fml.LogicalSide
    getSide()
     
    net.minecraft.world.item.context.UseOnContext
    getUseOnContext()
     
    UseItemOnBlockEvent.UsePhase
    getUsePhase()
    Returns The Use Phase of the interaction.
    void
    setCancellationResult(net.minecraft.world.InteractionResult result)
    Set the InteractionResult that will be returned to vanilla if the event is cancelled, instead of calling the relevant method of the event.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface net.neoforged.bus.api.ICancellableEvent

    isCanceled, setCanceled

  • Field Details

    • level

      private final net.minecraft.world.level.Level level

    • player

      @Nullable private final @Nullable net.minecraft.world.entity.player.Player player

    • hand

      private final net.minecraft.world.InteractionHand hand

    • heldItem

      private final net.minecraft.world.item.ItemStack heldItem

    • pos

      private final net.minecraft.core.BlockPos pos

    • face

      @Nullable private final @Nullable net.minecraft.core.Direction face

    • context

      private final net.minecraft.world.item.context.UseOnContext context

    • usePhase

      private final UseItemOnBlockEvent.UsePhase usePhase

    • cancellationResult

      private net.minecraft.world.InteractionResult cancellationResult

  • Constructor Details

    • UseItemOnBlockEvent

      public UseItemOnBlockEvent(net.minecraft.world.item.context.UseOnContext context, UseItemOnBlockEvent.UsePhase usePhase)

  • Method Details

    • getPlayer

      @Nullable public @Nullable net.minecraft.world.entity.player.Player getPlayer()
      Returns:
      player or null

    • getHand

      public net.minecraft.world.InteractionHand getHand()
      Returns:
      The hand involved in this interaction. Will never be null.

    • getItemStack

      public net.minecraft.world.item.ItemStack getItemStack()
      Returns:
      The itemstack involved in this interaction, ItemStack.EMPTY if the hand was empty.

    • getPos

      public net.minecraft.core.BlockPos getPos()
      If the interaction was on an entity, will be a BlockPos centered on the entity. If the interaction was on a block, will be the position of that block. Otherwise, will be a BlockPos centered on the player. Will never be null.
      Returns:
      The position involved in this interaction.

    • getFace

      @Nullable public @Nullable net.minecraft.core.Direction getFace()
      Returns:
      The face involved in this interaction. For all non-block interactions, this will return null.

    • getLevel

      public net.minecraft.world.level.Level getLevel()
      Returns:
      Convenience method to get the level of this interaction.

    • getUseOnContext

      public net.minecraft.world.item.context.UseOnContext getUseOnContext()
      Returns:
      context

    • getUsePhase

      public UseItemOnBlockEvent.UsePhase getUsePhase()
      Returns The Use Phase of the interaction.
      Returns:
      The Use Phase of the interaction
      See Also:

    • getSide

      public net.neoforged.fml.LogicalSide getSide()
      Returns:
      The effective, i.e. logical, side of this interaction. This will be LogicalSide.CLIENT on the client thread, and LogicalSide.SERVER on the server thread.

    • cancelWithResult

      public void cancelWithResult(net.minecraft.world.InteractionResult result)

      Cancels the use interaction (preventing the block or item's use behavior from running) and provides the specified result to the interaction logic instead.

      Invoke this if you intend to prevent the default interaction behavior and replace it with your own.

      Parameters:
      result - InteractionResult to return to the interaction logic
      • InteractionResult.SUCCESS, InteractionResult.CONSUME, and FAIL will prevent further types of interaction attempts when provided from the ITEM_BEFORE_BLOCK phase.
      • InteractionResult.SUCCESS, InteractionResult.CONSUME will trigger advancements on the server (except in the ITEM_BEFORE_BLOCK phase), and will also prevent the ITEM_AFTER_BLOCK item interaction from occurring if provided during the BLOCK phase.
      • InteractionResult.SUCCESS will trigger the arm-swinging mechanic.
      • InteractionResult.TRY_WITH_EMPTY_HAND will always allow proceeding to the next phase.
      • InteractionResult.PASS will not call the block's use method

    • getCancellationResult

      public net.minecraft.world.InteractionResult getCancellationResult()
      Returns:
      The InteractionResult that will be returned to vanilla if the event is cancelled, instead of calling the relevant method of the event. By default, this is InteractionResult.TRY_WITH_EMPTY_HAND, meaning cancelled events will cause the client to keep trying more interactions until something works.

    • setCancellationResult

      public void setCancellationResult(net.minecraft.world.InteractionResult result)
      Set the InteractionResult that will be returned to vanilla if the event is cancelled, instead of calling the relevant method of the event.