Modding:Right click events

This page was last verified for Vintage Story version 1.19.8.

The game source code refers to a right click as an 'interaction' (as opposed to left click which is called an 'attack'). The interaction is either routed to the currently held item in the hot bar, or to the selected block (the block in the world that the cursor is pointing at). Several methods are repeatedly called on the interaction target until the interaction is stopped. If the player is still holding right click when the interaction stops on the client, a new interaction is attempted.

Each player can only have one interaction in progress at a time. If they start an interaction with a block and look away, then they will be unable to start a new interaction until the old block allows the current interaction to be cancelled.

Interaction target priority

The system will attempt to start the interaction on the priority target. If the priority target rejects the interaction on the client side, then the system will attempt to start the interaction with the other target (held item / selected block). Which target has priority depends on whether the shift button is held, whether the held item has HeldPriorityInteract set, and whether the selected block has PlacedPriorityInteract set. Whichever criteria is met first in the following list determines the priority target.

1. Shift not held -> selected block has priority
2. Shift held and HeldPriorityInteract set on item -> held item has priority
3. Shift held and PlacedPriorityInteract set on selected block -> selected block has priority
4. Shift held and both targets have default priority -> held item has priority

Interaction methods

If the interaction target is a held item, then some combination of OnHeldInteractStart, OnHeldInteractStep, OnHeldInteractCancel, and OnHeldInteractStop will be called on it. If the interaction target is a selected block, then some combination of the corresponding block methods will be called instead: OnBlockInteractStart, OnBlockInteractStep, OnBlockInteractCancel, and OnBlockInteractStop.

There are 3 ways to stop an interaction. Note that it is recommended to have the client stop the interaction, because stopping the interaction on the client also stops the interaction on the server. If the server stops the interaction, then it will continue on the client until the client stops it too.

1. OnXXInteractStart - reject it before it starts, by returning false for a block or setting the handling reference parameter to NotHandled for an item. The system will attempt to send the interaction to the other target (held item / selected block) if there is one.
2. OnXXInteractStep - return false to signal a block/item initiated stop. For example, this is used by the poultice item to indicate that the poultice has been successfully applied.
3. OnXXInteractCancel - return true to accept a player initiated stop. Some of the ways the player can attempt to cancel the interaction are by releasing the mouse button or looking at another block.

The interaction can be thought of as going through several phases, which are summarized below. The interaction advances to the next phase unless the table describes otherwise.

Phase	Called methods	Description
start	OnXXInteractStart once	Rejecting the interaction jumps to the complete phase. For held items, the firstEvent parameter on OnHeldInteractStart is set to true if it is the first interaction after pressing the mouse. Blocks do not have an equivalent parameter.
step	OnXXInteractStep repeatedly	Returning false jumps to the stop phase.
cancel	OnXXInteractCancel and OnXXInteractStep repeatedly	Returning true from OnXXInteractCancel (accept the cancellation) jumps to either stop or complete (depending on the kind of cancellation). If the cancellation is rejected, then OnXXInteractStep is called next. Returning false jumps to the stop phase.
stop	OnXXInteractStop once
complete	OnXXInteractCancel spuriously on server	OnXXInteractCancel may be called spuriously on the server, if the interaction is only stopped on the server side, and then the client reaches the cancel phase. After the client reaches the complete phase, it will try to start a new interaction with firstEvent=false, if the mouse is still pressed.

Cancel reasons

This explains the specific behavior of the different cancel reasons. Note the row for player death during block interaction. In that case neither OnBlockInteractCancel nor OnBlockInteractStop is called on the client or server. OnBlockInteractStep simply stops getting called.

Target	Cancel Reason	Called on client / server	Rejection consequence	Skips OnXXInteractStop	Produces spurious cancels
Held item	ReleasedMouse	client	interaction continues	no	no
	Dropped	both	rejection ignored and stop is skipped	no	yes
	ChangeSlot	both	Prevents slot change on client side	yes	yes
	MovedAway	NA	NA	NA	NA
	Death	both	rejection ignored	no	no
	Destroyed (server removed item from slot)	client	rejection ignored	yes	no
Selected block	ReleasedMouse	client	interaction continues	no	no
	Dropped	NA	NA	NA	NA
	ChangeSlot	NA	NA	NA	NA
	MovedAway	both	continues interaction	yes	yes
	Death	neither	NA	yes	NA
	Destroyed	?	?	?	?

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.