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.ItemInteractionResult), 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 ItemInteractionResult	cancellationResult
private final UseOnContext	context
private final @Nullable Direction	face
private final InteractionHand	hand
private final ItemStack	heldItem
private final Level	level
private final @Nullable Player	player
private final BlockPos	pos
private final UseItemOnBlockEvent.UsePhase	usePhase

Constructor Summary

Constructors

Constructor	Description
UseItemOnBlockEvent(UseOnContext context, UseItemOnBlockEvent.UsePhase usePhase)

Method Summary

Modifier and Type	Method	Description
void	cancelWithResult(ItemInteractionResult 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.
ItemInteractionResult	getCancellationResult()
@Nullable Direction	getFace()
InteractionHand	getHand()
ItemStack	getItemStack()
Level	getLevel()
@Nullable Player	getPlayer()
BlockPos	getPos()	If the interaction was on an entity, will be a BlockPos centered on the entity.
net.neoforged.fml.LogicalSide	getSide()
UseOnContext	getUseOnContext()
UseItemOnBlockEvent.UsePhase	getUsePhase()	Returns The Use Phase of the interaction.
void	setCancellationResult(ItemInteractionResult result)	Set the ItemInteractionResult 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 Level level

player

@Nullable
private final @Nullable Player player

hand

private final InteractionHand hand

heldItem

private final ItemStack heldItem

pos

private final BlockPos pos

face

@Nullable
private final @Nullable Direction face

context

private final UseOnContext context

usePhase

private final UseItemOnBlockEvent.UsePhase usePhase

cancellationResult

private ItemInteractionResult cancellationResult

Constructor Details

UseItemOnBlockEvent

public UseItemOnBlockEvent(UseOnContext context,
 UseItemOnBlockEvent.UsePhase usePhase)

Method Details

getPlayer

@Nullable
public @Nullable Player getPlayer()

Returns:

player or null

getHand

public InteractionHand getHand()

Returns:

The hand involved in this interaction. Will never be null.

getItemStack

public ItemStack getItemStack()

Returns:

The itemstack involved in this interaction, ItemStack.EMPTY if the hand was empty.

getPos

public 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 Direction getFace()

Returns:

The face involved in this interaction. For all non-block interactions, this will return null.

getLevel

public Level getLevel()

Returns:

Convenience method to get the level of this interaction.

getUseOnContext

public 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:

• for semantics

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(ItemInteractionResult 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

• ItemInteractionResult.SUCCESS, ItemInteractionResult.CONSUME, ItemInteractionResult.CONSUME_PARTIAL, and FAIL will prevent further types of interaction attempts when provided from the ITEM_BEFORE_BLOCK phase.
• ItemInteractionResult.SUCCESS, ItemInteractionResult.CONSUME, and ItemInteractionResult.CONSUME_PARTIAL 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.
• ItemInteractionResult.SUCCESS will trigger the arm-swinging mechanic.
• ItemInteractionResult.PASS_TO_DEFAULT_BLOCK_INTERACTION will always allow proceeding to the next phase.
• ItemInteractionResult.SKIP_DEFAULT_BLOCK_INTERACTION will not call the block's use method

getCancellationResult

public ItemInteractionResult getCancellationResult()

Returns:

The ItemInteractionResult that will be returned to vanilla if the event is cancelled, instead of calling the relevant method of the event. By default, this is ItemInteractionResult.PASS_TO_DEFAULT_BLOCK_INTERACTION, meaning cancelled events will cause the client to keep trying more interactions until something works.

setCancellationResult

public void setCancellationResult(ItemInteractionResult result)

Set the ItemInteractionResult that will be returned to vanilla if the event is cancelled, instead of calling the relevant method of the event.