Fabric API - Crystal-Nest/harvest-with-ease GitHub Wiki

Multi-harvest and Mono-harvest

Since version 8.0.0.0 it is possible for a player to right-click harvest multiple crops at the same time in a flat squared area centered on the right-clicked crop.
When multi-harvesting, each event described below is fired once for each involved crop.
Each event has a parameter, first, that tells whether the current crop is the actual right-clicked crop (the one also at the center of the harvest area).
Finally, note that for events with the hitResult parameter, hitResult is always null unless first is true.

HARVEST_CHECK event

This event is fired when checking whether the player can harvest the right-clicked crop.
When the event fires, the right-clicked block will have been already verified as a crop block, meaning it is either a subclass of CropBlock, NetherWartBlock, CocoaBlock or its identifier is one of the items inside the crops property of this mod configuration file.

The last parameter passed to the listeners of this event is an instance of HarvestCheckEvent. It allows to cancel the event, preventing further processing from other listeners, and to peek at the current value that would be returned by this event when terminating.
The return value of your listener is what allows the player to right-click harvest and defaults to true. Be aware that, unless you cancel the event by calling setCanceled(boolean), execution by other listeners may change the final return value.
Basically what you return is either going to be passed as the current result value to the next listener or, if there are no other listeners, is just going to be returned. If you cancel the event, your return value is guaranteed to be the final return value.

Note that, when this event fires, the age of the crop won't have been determined yet, so even if true is returned at the end of this event, the right-click harvest may not happen.
Note also that this is the only event that fires on both server and client, unlike all other events that fire only server-side, so make sure to return and/or cancel the event the same on both times to avoid desynchronization.

BEFORE_HARVEST event

This event is fired only server-side right before all the harvesting related actions are taken. This event only serves as a hook for other mods to execute some code before right-click harvesting. If you wish to prevent the harvest use the HARVEST_CHECK event.

HARVEST_DROPS event

This event is fired only server-side when collecting the harvest drops to drop.
The default drops are calculated before dispatching the event and already have the one seed, the one that would be needed to replant, removed.

The last parameter passed to the listeners of this event is an instance of HarvestDropsEvent. It allows to cancel the event, preventing further processing from other listeners, and to peek at the current value that would be returned by this event when terminating.
The return value of your listener is the drops to drop, defaulting to what stated above. Be aware that, unless you cancel the event by calling setCanceled(boolean), execution by other listeners may change the final return value.
If you do not wish to change the list of drops you should return HarvestDropsEvent#getDrops().
Basically what you return is either going to be passed as the current result value to the next listener or, if there are no other listeners, is just going to be returned. If you cancel the event, your return value is guaranteed to be the final return value.

Calling HarvestDropsEvent#haveDropsChanged() will return whether the list of drops has changed from its default value.
Be aware that if you change the drops from their default value, then the other harvested blocks won't drop anything. This is generally not important as Vanilla and most mods only have crops made of a single block, so generally there are no other blocks to harvest. However this becomes important if the crop being harvested is a multi-block crop (e.g. Thermal Cultivation crops) because it means that instead of the whole crop (each block) only the right-clicked part will drop something.
If you need to change the drops you should also take care of this aspect. You can check whether a crop is a multi-block crop by calling HarvestWithEaseAPI#isTallCrop(World, BlockState, BlockPos). This will tell you whether the given crop is made of at least 2 vertically connected blocks. The precise number of blocks that make up a crop is not known and, if you need it, you need to calculate it yourself.

Note that this event is fired before resetting the crop age.

AFTER_HARVEST event

This event is fired only server-side right after all the harvesting related actions are taken (the right-click harvest succeeded). This event only serves as a hook for other mods to execute some code after right-click harvesting.

Event phases

There are 3 phases for each event:

  • HarvestWithEaseEvents#PRIORITY_PHASE for listeners that should be executed first, taking priority over others.
  • Event#DEFAULT_PHASE for listeners that do not need neither to be executed first or last.
  • HarvestWithEaseEvents#DEFERRED_PHASE for listeners that should be executed last, after others.